Skip to content

3D engine that AI agents drive

11.9 KB
Raw Blame
import './support/load-agent-scene-modules.mjs';
import assert from 'node:assert/strict';
import test from 'node:test';
import { mat4 } from 'gl-matrix';
import { createAgentScene } from '../src/agent-scene.js';
import { AGENT_SCENE_CAPABILITIES } from '../src/agent-scene-capabilities.js';
import { CONSTRAINT_TYPES } from '../src/node-constraints.js';
import { eulerFromQuaternion, quaternionFromEuler } from '../src/rotation-euler.js';

// Each case builds an owner and a target, then compares the owner's world matrix with a pose worked out by hand.

const DEGREES = Math.PI / 180;

function sampled(nodes, constraint) {
  const scene = createAgentScene({
    format: 'crucible.scene', schemaVersion: 1,
    geometries: [{ id: 'box', type: 'box', bevel: 0 }],
    materials: [{ id: 'paint', color: [0.6, 0.6, 0.6] }],
    nodes: nodes.map(node => ({ geometry: 'box', material: 'paint', ...node })),
    motion: { duration: 1, tracks: [], constraints: [{ node: 'owner', ...constraint }] },
  });
  scene.sampleMotion(0);
  return scene.parts.find(part => part.name === 'owner').matrix;
}

function assertClose(actual, expected, label, tolerance = 1e-4) {
  expected.forEach((value, index) => {
    assert.ok(Math.abs(actual[index] - value) <= tolerance, `${label}: ${JSON.stringify(Array.from(actual))} vs ${JSON.stringify(expected)}`);
  });
}

const translationOf = matrix => Array.from(mat4.getTranslation(new Float64Array(3), matrix));
const column = (matrix, index) => Array.from(matrix.slice(index * 4, index * 4 + 3));
const eulerDegrees = matrix => eulerFromQuaternion(mat4.getRotation(new Float64Array(4), matrix)).map(radians => radians / DEGREES);
const owner = { id: 'owner' };
const targetAt = translation => ({ id: 'target', translation });

test('copy_transforms gives the owner the target world matrix', () => {
  const rotation = Array.from(quaternionFromEuler(new Float64Array(4), 20 * DEGREES, 30 * DEGREES, 40 * DEGREES));
  const target = { id: 'target', translation: [1, 2, 3], rotation, scale: [2, 3, 4] };
  const matrix = sampled([owner, target], { type: 'copy_transforms', target: 'target' });
  const expected = mat4.fromRotationTranslationScale(new Float64Array(16), rotation, [1, 2, 3], [2, 3, 4]);
  assertClose(matrix, Array.from(expected), 'copy_transforms');
});

test('limit_distance pulls a far owner onto the sphere, keeping its direction', () => {
  const matrix = sampled([{ ...owner, translation: [6, 8, 0] }, targetAt([0, 0, 0])], { type: 'limit_distance', target: 'target', distance: 5 });
  assertClose(translationOf(matrix), [3, 4, 0], 'inside, far owner');
});

test('limit_distance inside leaves a near owner, outside pushes it out and surface does both', () => {
  const near = [{ ...owner, translation: [0.6, 0.8, 0] }, targetAt([0, 0, 0])];
  assertClose(translationOf(sampled(near, { type: 'limit_distance', target: 'target', distance: 5 })), [0.6, 0.8, 0], 'inside, near owner');
  assertClose(translationOf(sampled(near, { type: 'limit_distance', target: 'target', distance: 5, mode: 'outside' })), [3, 4, 0], 'outside');
  assertClose(translationOf(sampled(near, { type: 'limit_distance', target: 'target', distance: 5, mode: 'surface' })), [3, 4, 0], 'surface');
});

test('limit_scale clamps each ranged axis and leaves the others', () => {
  const matrix = sampled([{ ...owner, scale: [5, 0.1, 2] }], { type: 'limit_scale', x: [1, 3], y: [0.5, 2] });
  assertClose([column(matrix, 0)[0], column(matrix, 1)[1], column(matrix, 2)[2]], [3, 0.5, 2], 'scale');
});

test('stretch_to aims +y at the target and keeps volume with x and z', () => {
  const matrix = sampled([owner, targetAt([0, 0, 4])], { type: 'stretch_to', target: 'target', restLength: 2 });
  const thin = Math.sqrt(0.5);
  assertClose(column(matrix, 0), [-thin, 0, 0], 'x column');
  assertClose(column(matrix, 1), [0, 0, 2], 'y column stretched to 4 over rest 2');
  assertClose(column(matrix, 2), [0, thin, 0], 'z column');
});

test('stretch_to takes its rest length from the rest pose, and volume none leaves x and z alone', () => {
  const matrix = sampled([owner, targetAt([0, 0, 2])], { type: 'stretch_to', target: 'target', volume: 'none' });
  assertClose(column(matrix, 1), [0, 0, 1], 'unstretched at rest');
  assertClose(column(matrix, 0), [-1, 0, 0], 'x column');
});

test('locked_track turns only about the lock axis', () => {
  const matrix = sampled([owner, targetAt([3, 0, 5])], { type: 'locked_track', target: 'target' });
  assertClose(column(matrix, 1), [1, 0, 0], 'track axis y points along x, the target seen from the lock plane');
  assertClose(column(matrix, 2), [0, 0, 1], 'lock axis z does not move');
  assertClose(eulerDegrees(matrix), [0, 0, -90], 'euler');
});

test('transformation maps a clamped target channel range onto the owner', () => {
  const asRotation = sampled([owner, targetAt([5, 0, 0])], {
    type: 'transformation', target: 'target', destination: 'rotation', map: ['x', 'y', 'x'], fromMax: [10, 10, 10], toMax: [90, 90, 180],
  });
  assertClose(eulerDegrees(asRotation), [45, 0, 90], 'half way along x');
  const clamped = sampled([owner, targetAt([20, 0, 0])], {
    type: 'transformation', target: 'target', fromMax: [10, 10, 10], toMax: [1, 2, 3], map: ['x', 'y', 'x'],
  });
  assertClose(translationOf(clamped), [1, 0, 3], 'clamped to the top of the range');
});

test('action reads a keyed curve at the target channel position', () => {
  const action = { type: 'action', target: 'target', max: 10, min: 0, keys: [{ at: 0, value: [0, 0, 0] }, { at: 0.5, value: [0, 2, 0] }, { at: 1, value: [0, 2, 10] }] };
  assertClose(translationOf(sampled([owner, targetAt([2.5, 0, 0])], action)), [0, 1, 0], 'first segment');
  assertClose(translationOf(sampled([owner, targetAt([7.5, 0, 0])], action)), [0, 2, 5], 'second segment');
  assertClose(translationOf(sampled([owner, targetAt([99, 0, 0])], action)), [0, 2, 10], 'past the end');
});

test('the new constraints refuse bad fields', () => {
  const pair = [owner, targetAt([1, 0, 0])];
  const refuses = (constraint, pattern) => assert.throws(() => sampled(pair, constraint), pattern);
  refuses({ type: 'limit_scale', x: [0, 2] }, /minimum must be above 0/);
  refuses({ type: 'limit_distance', target: 'target', distance: -1 }, /distance/);
  refuses({ type: 'locked_track', target: 'target', trackAxis: '+z', lockAxis: 'z' }, /different axes/);
  refuses({ type: 'stretch_to', target: 'target', volume: 'all' }, /volume/);
  refuses({ type: 'transformation', target: 'target', fromMax: [0, 1, 1] }, /fromMax must differ/);
  refuses({ type: 'transformation', target: 'target', map: ['x', 'y'] }, /map/);
  refuses({ type: 'action', target: 'target', min: 1, max: 1, keys: [] }, /min must be below max/);
  refuses({ type: 'action', target: 'target', min: 0, max: 1, keys: [{ at: 0, value: [0, 0, 0] }] }, /at least 2/);
  refuses({ type: 'action', target: 'target', min: 0, max: 1, keys: [{ at: 0.5, value: [0, 0, 0] }, { at: 0.5, value: [1, 0, 0] }] }, /rising/);
  refuses({ type: 'copy_transforms' }, /target/);
});

test('the newer types accept their fields in args, the shape the MCP schema uses', () => {
  const nested = sampled([{ ...owner, translation: [6, 8, 0] }, targetAt([0, 0, 0])], { type: 'limit_distance', args: { target: 'target', distance: 5, influence: 1 } });
  assertClose(translationOf(nested), [3, 4, 0], 'args');
  const pair = [owner, targetAt([1, 0, 0])];
  assert.throws(() => sampled(pair, { type: 'limit_distance', args: { target: 'target', distance: 5, speed: 1 } }), /Allowed fields/);
  assert.throws(() => sampled(pair, { type: 'limit_distance', target: 'target', args: { target: 'target', distance: 5 } }), /both directly and in args/);
});

test('scene_capabilities lists every constraint type', () => {
  assert.deepEqual([...AGENT_SCENE_CAPABILITIES.motionConstraints].sort(), [...CONSTRAINT_TYPES].sort());
});

test('maintain_volume, damped_track, pivot, follow_path, clamp_to, shrinkwrap and armature constraints work deterministically', () => {
  // maintain_volume
  const vol = sampled([{ ...owner, scale: [1, 4, 1] }], { type: 'maintain_volume', freeAxis: 'y', volume: 1 });
  assertClose([column(vol, 0)[0], column(vol, 1)[1], column(vol, 2)[2]], [0.5, 4, 0.5], 'maintain_volume');

  // damped_track
  const damped = sampled([owner, targetAt([0, 0, 5])], { type: 'damped_track', target: 'target', trackAxis: '+y' });
  assertClose(column(damped, 1), [0, 0, 1], 'damped_track +y aims at +z');

  // pivot
  const rotatedOwner = { id: 'owner', translation: [0, 0, 0], rotation: Array.from(quaternionFromEuler(new Float64Array(4), 0, 0, 90 * DEGREES)) };
  const pivoted = sampled([rotatedOwner, targetAt([1, 0, 0])], { type: 'pivot', target: 'target', offset: [0, 0, 0] });
  assertClose(translationOf(pivoted), [1, -1, 0], 'pivot 90 deg around [1,0,0]');

  // follow_path
  const pathScene = createAgentScene({
    format: 'crucible.scene', schemaVersion: 1,
    geometries: [{ id: 'box', type: 'box', bevel: 0 }],
    materials: [{ id: 'paint', color: [0.6, 0.6, 0.6] }],
    nodes: [{ id: 'owner', geometry: 'box', material: 'paint' }],
    motion: {
      duration: 1, tracks: [],
      constraints: [{ type: 'follow_path', node: 'owner', points: [[0, 0, 0], [0, 0, 4]], followCurve: true, forwardAxis: '+z', upAxis: 'y', duration: 1 }],
    },
  });
  pathScene.sampleMotion(0.5);
  const pathMat = pathScene.parts[0].matrix;
  assertClose(translationOf(pathMat), [0, 0, 2], 'follow_path midpoint');
  assertClose(column(pathMat, 2), [0, 0, 1], 'follow_path tangent +z');

  // clamp_to
  const clamped = sampled([{ ...owner, translation: [3, 5, 0] }], { type: 'clamp_to', points: [[0, 0, 0], [4, 2, 0]], mainAxis: 'x' });
  assertClose(translationOf(clamped), [3, 1.5, 0], 'clamp_to along x');

  // shrinkwrap nearest & project
  const nearest = sampled([{ ...owner, translation: [0, 5, 0] }, { id: 'target', translation: [0, 0, 0], scale: [2, 2, 2] }], { type: 'shrinkwrap', target: 'target', mode: 'nearest', distance: 0.5 });
  assertClose(translationOf(nearest), [0, 1.5, 0], 'shrinkwrap nearest');
  const projected = sampled([{ ...owner, translation: [0.5, 5, 0] }, { id: 'target', translation: [0, 0, 0], scale: [2, 2, 2] }], { type: 'shrinkwrap', target: 'target', mode: 'project', projectAxis: '-y', distance: 0.2 });
  assertClose(translationOf(projected), [0.5, 1.2, 0], 'shrinkwrap project');

  // armature constraint
  const armScene = createAgentScene({
    format: 'crucible.scene', schemaVersion: 1,
    geometries: [{ id: 'box', type: 'box', bevel: 0 }],
    materials: [{ id: 'paint', color: [0.6, 0.6, 0.6] }],
    nodes: [
      { id: 'owner', geometry: 'box', material: 'paint', translation: [0, 0, 0] },
      { id: 'b1', geometry: 'box', material: 'paint', translation: [0, 0, 0] },
      { id: 'b2', geometry: 'box', material: 'paint', translation: [0, 0, 0] },
    ],
    motion: {
      duration: 1,
      tracks: [
        { kind: 'node', id: 'b1', property: 'translation', keyframes: [{ time: 0, value: [0, 0, 0] }, { time: 1, value: [4, 0, 0] }] },
        { kind: 'node', id: 'b2', property: 'translation', keyframes: [{ time: 0, value: [0, 0, 0] }, { time: 1, value: [0, 4, 0] }] },
      ],
      constraints: [{ type: 'armature', node: 'owner', targets: [{ target: 'b1', weight: 0.75 }, { target: 'b2', weight: 0.25 }] }],
    },
  });
  armScene.sampleMotion(1);
  assertClose(translationOf(armScene.parts.find(part => part.name === 'owner').matrix), [3, 1, 0], 'armature weighted blend');

  // floor useRotation and transformation mix
  const tiltedFloor = { id: 'target', translation: [0, 0, 0], rotation: Array.from(quaternionFromEuler(new Float64Array(4), 0, 0, -45 * DEGREES)) };
  const floored = sampled([{ ...owner, translation: [0, -1, 0] }, tiltedFloor], { type: 'floor', target: 'target', axis: '+y', useRotation: true });
  assert.ok(floored[13] > -0.6, 'tilted floor lifts owner');

  const added = sampled([{ ...owner, translation: [1, 2, 3] }, targetAt([5, 0, 0])], {
    type: 'transformation', target: 'target', fromMax: [10, 10, 10], toMax: [2, 0, 0], mix: 'add',
  });
  assertClose(translationOf(added), [2, 2, 3], 'transformation add');
});