Skip to content

3D engine that AI agents drive

10.1 KB
Raw Blame
import './support/load-agent-scene-modules.mjs';
import test from 'node:test';
import assert from 'node:assert/strict';
import { createAgentScene, loadPhysicsEngine, needsPhysics } from '../src/agent-scene.js';
import { AGENT_SCENE_CAPABILITIES } from '../src/agent-scene-capabilities.js';

await loadPhysicsEngine();

function recipe(physics, extraNodes = []) {
  return {
    format: 'crucible.scene', schemaVersion: 1,
    geometries: [
      { id: 'slab', type: 'box' },
      { id: 'ball', type: 'sphere' },
    ],
    materials: [{ id: 'paint', color: [0.6, 0.5, 0.4] }],
    nodes: [
      { id: 'floor', geometry: 'slab', material: 'paint', translation: [0, -0.25, 0], scale: [6, 0.5, 6] },
      { id: 'ball', geometry: 'ball', material: 'paint', translation: [0, 2, 0], scale: [0.5, 0.5, 0.5] },
      ...extraNodes,
    ],
    physics,
  };
}

const dropOnFloor = { duration: 3, bodies: [{ node: 'floor', type: 'fixed' }, { node: 'ball', shape: 'ball', restitution: 0.3 }] };

function matrixSnapshot(scene) {
  return scene.parts.map(part => Array.from(part.matrix));
}

test('a recipe physics section drops a body onto a trimesh floor and seeks deterministically', () => {
  const scene = createAgentScene(recipe(dropOnFloor));
  scene.sampleMotion(1.2);
  const middle = matrixSnapshot(scene);
  scene.sampleMotion(0);
  assert.equal(scene.parts[1].matrix[13], 2, 'time zero is the authored pose');
  scene.sampleMotion(3);
  const rested = scene.parts[1].matrix[13];
  assert.ok(Math.abs(rested - 0.5) < 0.02, `ball rests on the floor, got ${rested}`);
  scene.sampleMotion(1.2);
  assert.deepEqual(matrixSnapshot(scene), middle);
  scene.sampleMotion(null);
  assert.equal(scene.parts[1].matrix[13], 2);
});

test('scene_inspect reports contacts, resting state and sensors as numbers', () => {
  const scene = createAgentScene(recipe({
    duration: 3,
    bodies: [
      { node: 'floor', type: 'fixed' },
      { node: 'ball', shape: 'ball' },
      { node: 'zone', type: 'fixed', sensor: true },
    ],
  }, [{ id: 'zone', geometry: 'slab', material: 'paint', translation: [0, 1.2, 0], scale: [2, 0.2, 2] }]));
  const { physics } = scene.inspect({});
  const ball = physics.bodies.find(body => body.node === 'ball');
  assert.ok(ball.restsAtTime > 0.3 && ball.restsAtTime < 3);
  assert.ok(Math.abs(ball.finalPosition[1] - 0.5) < 0.02);
  assert.deepEqual(physics.contacts.map(({ a, b, touchingAtEnd }) => ({ a, b, touchingAtEnd })), [{ a: 'ball', b: 'floor', touchingAtEnd: true }]);
  assert.deepEqual(physics.sensorEvents.map(event => [event.sensor, event.other, event.kind]), [['zone', 'ball', 'enter'], ['zone', 'ball', 'leave']]);
});

test('physics is recorded again only when its inputs change', () => {
  const scene = createAgentScene(recipe(dropOnFloor));
  scene.apply([{ type: 'set-physics', physics: { ...dropOnFloor, bodies: [{ node: 'floor', type: 'fixed' }, { node: 'ball', shape: 'ball', restitution: 0.9 }] } }], { expectedRevision: 0 });
  scene.sampleMotion(0.9);
  const bouncy = scene.parts[1].matrix[13];
  scene.apply([{ type: 'set-physics', physics: null }], { expectedRevision: 1 });
  assert.equal(scene.inspect({}).physics, null);
  assert.equal(scene.parts[1].matrix[13], 2);
  assert.ok(bouncy < 2);
  assert.equal(scene.exportRecipe().physics, null);
});

test('masks and layers decide what a body falls through', () => {
  const scene = createAgentScene(recipe({
    duration: 3,
    bodies: [{ node: 'floor', type: 'fixed', layer: 1, collidesWith: [1] }, { node: 'ball', shape: 'ball', layer: 2, collidesWith: [2] }],
  }));
  scene.sampleMotion(3);
  assert.ok(scene.parts[1].matrix[13] < -10);
});

test('bad physics sections fail with a message that names the fix', () => {
  const cases = [
    [{ duration: 3, bodies: [{ node: 'missing' }] }, /^RangeError: physics\.bodies\[0\]\.node: got "missing"; expected the ID of a recipe node, one of /],
    [{ duration: 0, bodies: [{ node: 'ball' }] }, /duration/],
    [{ duration: 3, bodies: [] }, /at least one body/],
    [{ duration: 3, bodies: [{ node: 'ball', shape: 'trimesh' }] }, /dynamic/],
    [{ duration: 3, bodies: [{ node: 'ball' }, { node: 'ball' }] }, /^RangeError: physics\.bodies\[1\]\.node: got "ball"; expected a node with one physics body only/],
    [{ duration: 3, bodies: [{ node: 'ball', color: 1 }] }, /^TypeError: physics\.bodies\[0\]\.color: got 1; expected no such field; use one of node, type, shape/],
    [{ duration: 3, bodies: [{ node: 'ball' }], joints: [{ type: 'fixed', bodyA: 'ball', bodyB: 'floor' }] }, /physics body/],
    [{ duration: 3, bodies: [{ node: 'ball', layer: 16 }] }, /layer/],
  ];
  for (const [physics, message] of cases) {
    assert.throws(() => createAgentScene(recipe(physics)), message);
  }
});

test('a node cannot have both a physics body and a motion track on its pose', () => {
  const input = recipe({ duration: 3, bodies: [{ node: 'ball' }] });
  input.motion = { duration: 1, tracks: [{ kind: 'node', id: 'ball', property: 'translation', keyframes: [{ time: 0, value: [0, 0, 0] }, { time: 1, value: [1, 0, 0] }] }] };
  assert.throws(() => createAgentScene(input), /^RangeError: physics\.bodies\[0\]\.node: got "[^"]+"; expected a node without a motion translation or rotation track; pick the track or the body, not both/);
});

test('a trimesh over the triangle limit is refused before it is copied', () => {
  const input = recipe({ duration: 1, bodies: [{ node: 'floor', type: 'fixed' }] });
  input.geometries[0] = { id: 'slab', type: 'sphere', segments: 200, rings: 200 };
  assert.throws(() => createAgentScene(input), /triangles/);
});

test('capabilities name the physics surface and the detector finds a section', () => {
  assert.deepEqual(AGENT_SCENE_CAPABILITIES.physics.shapes, ['box', 'ball', 'capsule', 'convex', 'trimesh']);
  assert.ok(AGENT_SCENE_CAPABILITIES.operations.includes('set-physics'));
  assert.equal(needsPhysics(recipe(dropOnFloor)), true);
  assert.equal(needsPhysics(recipe(undefined)), false);
  assert.equal(needsPhysics([{ type: 'set-physics', physics: null }]), false);
});

test('recipe physics supports cylinder, cone, compound shapes, spring joints, motors, events and force fields', () => {
  const scene = createAgentScene(recipe({
    duration: 1,
    gravity: [0, 0, 0],
    fields: [{ type: 'wind', direction: [0, 0, 1], strength: 6 }],
    bodies: [
      { node: 'floor', type: 'fixed', shape: 'cylinder' },
      { node: 'ball', shape: 'cone', mass: 1 },
      { node: 'slider', shape: 'compound', shapes: [
        { shape: 'box', halfExtents: [0.2, 0.2, 0.2], translation: [-0.2, 0, 0] },
        { shape: 'ball', radius: 0.2, translation: [0.2, 0, 0] },
        { shape: 'cylinder', radius: 0.1, halfHeight: 0.2 },
      ] },
      { node: 'bob', shape: 'capsule' },
    ],
    joints: [
      { name: 'track', type: 'prismatic', bodyA: 'floor', bodyB: 'slider', anchorA: [0, 2, 0], anchorB: [0, 0, 0], axis: [1, 0, 0], limits: [-2, 2], motor: { mode: 'position', target: 0.8, stiffness: 60, damping: 10, maxForce: 100 }, contactsEnabled: false },
      { type: 'spring', bodyA: 'floor', bodyB: 'bob', anchorA: [0, 2, 0], anchorB: [0, 0, 0], restLength: 0.5, stiffness: 30, damping: 3 },
    ],
    events: [
      { time: 0.2, type: 'impulse', body: 'ball', impulse: [3, 0, 0], torqueImpulse: [0, 1, 0], point: [0, 2, 0] },
      { tick: 30, type: 'jointMotor', joint: 'track', motor: { mode: 'velocity', target: -0.5, damping: 10, maxForce: 50 } },
    ],
  }, [
    { id: 'slider', geometry: 'slab', material: 'paint', translation: [0, 1.75, 0], rotation: [0, 0, 0, 1], scale: [0.4, 0.4, 0.4] },
    { id: 'bob', geometry: 'ball', material: 'paint', translation: [0, 0.5, 0], scale: [0.3, 0.3, 0.3] },
  ]));
  scene.sampleMotion(1);
  const { physics } = scene.inspect({});
  const ball = physics.bodies.find(body => body.node === 'ball');
  const bob = physics.bodies.find(body => body.node === 'bob');
  assert.ok(ball.finalPosition[0] > 1.5, `impulse pushes ball along +X, got ${ball.finalPosition[0]}`);
  assert.ok(ball.finalPosition[2] > 2, `wind field pushes ball along +Z, got ${ball.finalPosition[2]}`);
  assert.ok(bob.finalPosition[1] > 0.8, `spring pulls bob upward, got ${bob.finalPosition[1]}`);

  const kinScene = createAgentScene(recipe({ duration: 1, bodies: [{ node: 'floor', type: 'kinematic', shape: 'box' }], events: [{ time: 0.1, type: 'kinematicPose', body: 'floor', translation: [0, 1, 0], rotation: [0, 0, 0, 1] }] }));
  kinScene.sampleMotion(0.5);
  assert.equal(kinScene.parts[0].matrix[13], 1);
  assert.throws(() => createAgentScene(recipe({ duration: 1, bodies: [{ node: 'ball', shape: 'compound', shapes: [] }] })), /at least one sub-collider/);
  assert.throws(() => createAgentScene(recipe({ duration: 1, bodies: [{ node: 'ball', shapes: [{ shape: 'box', halfExtents: [1, 1, 1] }] }] })), /compound/);
  assert.throws(() => createAgentScene(recipe({ duration: 1, bodies: [{ node: 'ball' }], events: [{ time: 0.1, type: 'impulse', body: 'ball' }] })), /impulse or torqueImpulse/);
  assert.throws(() => createAgentScene(recipe({ duration: 1, bodies: [{ node: 'floor', type: 'kinematic', shape: 'box' }], events: [{ time: 0.1, type: 'kinematicPose', body: 'floor' }] })), /translation or rotation/);
});

test('a recipe fixed joint with breakImpulse breaks under a hard hit and the report lists it', () => {
  const slab = { id: 'slab', geometry: 'slab', material: 'paint', translation: [0, 4, 0], scale: [0.6, 0.3, 0.6] };
  const glue = { name: 'glue', type: 'fixed', bodyA: 'floor', bodyB: 'ball', anchorA: [0, 2.25, 0], anchorB: [0, 0, 0], breakImpulse: 2 };
  const physics = joint => ({
    duration: 1.5,
    bodies: [{ node: 'floor', type: 'fixed' }, { node: 'ball', shape: 'ball', mass: 1 }, { node: 'slab', shape: 'box', mass: 5 }],
    joints: [joint],
  });
  const scene = createAgentScene(recipe(physics(glue), [slab]));
  scene.sampleMotion(1.5);
  const report = scene.inspect({}).physics;
  assert.equal(report.jointBreaks.length, 1);
  assert.equal(report.jointBreaks[0].joint, 'glue');
  assert.ok(report.jointBreaks[0].impulse >= 2);
  assert.throws(() => createAgentScene(recipe(physics({ ...glue, type: 'spherical' }), [slab])), /breakImpulse/);
  assert.throws(() => createAgentScene(recipe(physics({ ...glue, breakImpulse: 0 }), [slab])), /breakImpulse/);
});