Skip to content

3D engine that AI agents drive

15.9 KB
Raw Blame
import './support/load-agent-scene-modules.mjs';
import test from 'node:test';
import assert from 'node:assert/strict';
import { Client } from '@modelcontextprotocol/client';
import { InMemoryTransport } from '@modelcontextprotocol/server';
import { createAgentMcpServer } from '../scripts/mcp-server.mjs';
import { walkerRecipe } from '../bench/agent-modeling/walker.mjs';
import { MOTION_TRACK_KINDS } from '../src/agent-motion.js';
import { MOTION_TRACK_KIND_NAMES } from '../src/motion-track-kinds.js';
import { createAgentScene, loadPhysicsEngine, AGENT_SCENE_CAPABILITIES } from '../src/agent-scene.js';

await loadPhysicsEngine();

function oneBoxRecipe(extra = {}) {
  return {
    format: 'crucible.scene', schemaVersion: 1,
    geometries: [{ id: 'cube', type: 'box', bevel: 0 }],
    materials: [{ id: 'red', color: [1, 0, 0] }],
    nodes: [{ id: 'a', geometry: 'cube', material: 'red' }],
    ...extra,
  };
}

function fractureRecipe() {
  return oneBoxRecipe({
    nodes: [
      { id: 'floor', geometry: 'cube', material: 'red', scale: [10, 0.2, 10], translation: [0, -0.1, 0] },
      { id: 'crate', geometry: 'cube', material: 'red', translation: [0, 2, 0] },
    ],
    physics: { duration: 1, bodies: [{ node: 'floor', type: 'fixed' }] },
  });
}

async function withRoundTripClient(use) {
  let scene;
  const runtime = {
    activeSessionId() { return scene ? 'round-trip' : null; },
    async capabilities() { return { scene: AGENT_SCENE_CAPABILITIES, phase: 'idle', availableIn: 'test' }; },
    async create({ recipe }) {
      scene = createAgentScene(recipe);
      return { sessionId: 'round-trip', revision: scene.revision };
    },
    async apply({ expectedRevision, operations }) {
      scene.apply(operations, { expectedRevision });
      return { sessionId: 'round-trip', revision: scene.revision };
    },
    async exportRecipe() { return { sessionId: 'round-trip', revision: scene.revision, recipe: scene.exportRecipe() }; },
    async close() {},
  };
  const server = createAgentMcpServer(runtime);
  const client = new Client({ name: 'crucible-recipe-round-trip-test', version: '1' });
  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
  await server.connect(serverTransport);
  await client.connect(clientTransport);
  try {
    return await use(client, () => scene);
  } finally {
    await client.close();
    await server.close();
  }
}

async function call(client, name, argumentsValue) {
  const result = await client.callTool({ name, arguments: argumentsValue });
  const text = result.content?.find(item => item.type === 'text')?.text ?? '';
  return { isError: result.isError === true, text, structured: result.structuredContent };
}

async function exportedRecipe(client) {
  const exported = await call(client, 'scene_export_recipe', {});
  assert.equal(exported.isError, false, exported.text);
  return exported.structured.recipe;
}

async function applyOperations(client, operations) {
  const revision = (await call(client, 'scene_export_recipe', {})).structured.revision;
  return call(client, 'scene_apply', { expectedRevision: revision, operations });
}

async function assertAccepted(client, recipe) {
  const created = await call(client, 'scene_create', { recipe });
  assert.equal(created.isError, false, created.text);
}

test('an exported one-box recipe is accepted by scene_create unchanged', async () => {
  await withRoundTripClient(async client => {
    await assertAccepted(client, oneBoxRecipe());
    await assertAccepted(client, await exportedRecipe(client));
    await assertAccepted(client, oneBoxRecipe({ environment: { setup: 'sunset' } }));
    const sunset = await exportedRecipe(client);
    await assertAccepted(client, sunset);
    const applied = await applyOperations(client, [{ type: 'set-environment', environment: sunset.environment }]);
    assert.equal(applied.isError, false, applied.text);
  });
});

test('an exported recipe with fracture joints is accepted by scene_create', async () => {
  await withRoundTripClient(async client => {
    await assertAccepted(client, fractureRecipe());
    const fractured = await applyOperations(client, [{ type: 'fracture-node', node: 'crate', cells: 4, strength: 10, seed: 1 }]);
    assert.equal(fractured.isError, false, fractured.text);
    const recipe = await exportedRecipe(client);
    const joint = recipe.physics.joints[0];
    assert.equal(typeof joint.name, 'string');
    assert.equal(joint.breakImpulse, 10);
    await assertAccepted(client, recipe);
  });
});

test('scene_create accepts physics events, fields and ragdoll', async () => {
  await withRoundTripClient(async client => {
    const withEvents = fractureRecipe();
    withEvents.physics.bodies.push({ node: 'crate', type: 'dynamic' });
    withEvents.physics.events = [{ time: 0.1, body: 'crate', impulse: [1, 0, 0] }];
    withEvents.physics.fields = [{ type: 'wind', direction: [1, 0, 0], strength: 2 }];
    await assertAccepted(client, withEvents);
    await assertAccepted(client, await exportedRecipe(client));
    const ragdoll = fractureRecipe();
    ragdoll.physics.ragdoll = { armature: 'missing-rig' };
    const refused = await call(client, 'scene_create', { recipe: ragdoll });
    assert.doesNotMatch(refused.text, /Unrecognized key/);
    assert.match(refused.text, /armature/);
  });
});

test('scene_create accepts effects flash and distortion', async () => {
  await withRoundTripClient(async client => {
    const recipe = oneBoxRecipe({
      effects: {
        flash: { node: 'a', startTime: 0, attack: 0, decay: 0.15, intensity: 3.5, radius: 6, ambient: 0.15 },
        distortion: [{ shape: 'ring', node: 'a', startTime: 0, speed: 45, thickness: 2.2, strength: 1 }],
      },
    });
    await assertAccepted(client, recipe);
    const applied = await applyOperations(client, [{ type: 'set-effects', effects: recipe.effects }]);
    assert.equal(applied.isError, false, applied.text);
  });
});

test('scene_create accepts the grid mesh base the docs use for decals', async () => {
  await withRoundTripClient(async client => {
    const recipe = oneBoxRecipe({
      geometries: [{ id: 'badge', type: 'mesh', base: { type: 'grid', segments: 16 }, edits: [{ op: 'solidify', thickness: 0.02, offset: -1 }] }],
      nodes: [{ id: 'a', geometry: 'badge', material: 'red' }],
    });
    await assertAccepted(client, recipe);
  });
});

test('scene_create names the bad field and the allowed ones for a malformed motion track', async () => {
  await withRoundTripClient(async client => {
    const recipe = oneBoxRecipe({
      motion: { duration: 1, tracks: [{ node: 'a', property: 'translation', keyframes: [{ time: 0, value: [0, 0, 0] }] }] },
    });
    const created = await call(client, 'scene_create', { recipe });
    assert.equal(created.isError, true);
    assert.match(created.text, /Unknown or unsupported motion track field: node/);
    assert.match(created.text, /Allowed fields: kind, id, property/);
  });
});

test('scene_create accepts a recipe ragdoll on a real armature', async () => {
  await withRoundTripClient(async client => {
    const recipe = walkerRecipe();
    delete recipe.motion;
    recipe.geometries.push({ id: 'slab', type: 'box' });
    recipe.nodes.push({ id: 'floor', geometry: 'slab', material: 'cloth', translation: [0, -0.25, 0], scale: [8, 0.5, 8] });
    recipe.armatures[0].translation = [0, 1, 0];
    recipe.physics = { duration: 1, bodies: [{ node: 'floor', type: 'fixed' }], ragdoll: { armature: 'rig' } };
    await assertAccepted(client, recipe);
  });
});

test('scene_create accepts the plane mesh base and refuses segments outside 1 to 64', async () => {
  await withRoundTripClient(async client => {
    const withSegments = segments => oneBoxRecipe({
      geometries: [{ id: 'sheet', type: 'mesh', base: { type: 'plane', segments } }],
      nodes: [{ id: 'a', geometry: 'sheet', material: 'red' }],
    });
    await assertAccepted(client, withSegments(8));
    for (const segments of [0, 65]) {
      const refused = await call(client, 'scene_create', { recipe: withSegments(segments) });
      assert.equal(refused.isError, true);
    }
  });
});

test('scene_create names the valid kinds and properties for a motion track with a wrong kind or property', async () => {
  await withRoundTripClient(async client => {
    const keyframes = [{ time: 0, value: [0, 0, 0] }];
    const createdWith = track => call(client, 'scene_create', { recipe: oneBoxRecipe({ motion: { duration: 1, tracks: [track] } }) });
    const missingKind = await createdWith({ id: 'a', property: 'translation', keyframes });
    assert.match(missingKind.text, /needs kind \(node, material, camera, morph, geometry, light, sun, environment, effects\)/);
    const wrongKind = await createdWith({ kind: 'sky', id: 'a', property: 'translation', keyframes });
    assert.match(wrongKind.text, /Unknown motion track kind: "sky"\. Kinds: node, material/);
    const wrongProperty = await createdWith({ kind: 'node', id: 'a', property: 'bogus', keyframes });
    assert.match(wrongProperty.text, /Unknown node track property: "bogus"\. node properties: translation, rotation, scale\./);
  });
});

function morphTrackRecipe() {
  return {
    format: 'crucible.scene', schemaVersion: 1,
    geometries: [{ id: 'face', type: 'mesh', base: { type: 'box', bevel: 0, subdivisions: 2 }, shapeKeys: [{ name: 'lift', offsets: [{ select: { tag: 'top' }, offset: [0, 0.5, 0] }] }] }],
    materials: [{ id: 'skin' }],
    nodes: [{ id: 'head', geometry: 'face', material: 'skin' }],
    camera: { eye: [3, 2, 4], target: [0, 0.5, 0], fov: 45 },
    motion: { duration: 2, tracks: [{ kind: 'morph', id: 'lift', property: 'weight', keyframes: [{ time: 0, value: 0 }, { time: 1, value: 1 }] }] },
  };
}

test('scene_create accepts a morph motion track and the shape key weight animates', async () => {
  await withRoundTripClient(async (client, currentScene) => {
    const created = await call(client, 'scene_create', { recipe: morphTrackRecipe() });
    assert.notEqual(created.isError, true, created.text);
    const weightAt = time => {
      currentScene().sampleMotion(time);
      return Array.from(currentScene().parts.find(part => part.morph).morph.weights)[0];
    };
    assert.equal(weightAt(0), 0);
    assert.equal(weightAt(1), 1);
  });
});

test('scene_create takes every motion track kind the backend lists', async () => {
  assert.deepEqual([...MOTION_TRACK_KIND_NAMES], [...MOTION_TRACK_KINDS], 'the MCP leaf list matches the motion backend');
  assert.deepEqual([...MOTION_TRACK_KINDS], ['node', 'material', 'camera', 'morph', 'geometry', 'light', 'sun', 'environment', 'effects']);
  await withRoundTripClient(async client => {
    const wrongKind = await call(client, 'scene_create', { recipe: oneBoxRecipe({ motion: { duration: 1, tracks: [{ kind: 'sky', id: 'a', property: 'x', keyframes: [{ time: 0, value: 0 }] }] } }) });
    assert.match(wrongKind.text, new RegExp(`Kinds: ${MOTION_TRACK_KINDS.join(', ')}\.`));
  });
});

const MODIFIER_EXAMPLES = [
  { type: 'cycles', before: 'mirror', after: 'offset', beforeCount: 2, afterCount: 3 },
  { type: 'stepped', step: 0.2, offset: 0.05 },
  { type: 'noise', scale: 0.5, strength: 0.3, phase: 0.1, seed: 7 },
  { type: 'generator', coefficients: [0, 1, 0.5], additive: true },
  { type: 'limits', min: -5, max: 5 },
  { type: 'envelope', points: [{ time: 0, min: -1, max: 1 }, { time: 1, min: -2, max: 2 }], referenceMin: -1, referenceMax: 1 },
];

function everyMotionFieldRecipe() {
  const keyframes = (first, second) => [{ time: 0, value: first }, { time: 1, value: second }];
  return oneBoxRecipe({
    nodes: [
      { id: 'a', geometry: 'cube', material: 'red' },
      { id: 'b', geometry: 'cube', material: 'red', translation: [3, 0, 0] },
    ],
    motion: {
      duration: 2,
      tracks: [
        { kind: 'node', id: 'a', property: 'translation', interpolation: 'LINEAR', extrapolation: 'linear', modifiers: MODIFIER_EXAMPLES.slice(1, 3), keyframes: keyframes([0, 0, 0], [1, 0, 0]) },
        { kind: 'node', id: 'a', property: 'scale', keyframes: keyframes([1, 1, 1], [2, 2, 2]), modifiers: [MODIFIER_EXAMPLES[0]] },
        { kind: 'node', id: 'b', property: 'translation', modifiers: [MODIFIER_EXAMPLES[3], MODIFIER_EXAMPLES[4], MODIFIER_EXAMPLES[5]], keyframes: keyframes([3, 0, 0], [3, 1, 0]) },
        { kind: 'material', id: 'red', property: 'roughness', extrapolation: 'linear', keyframes: keyframes(0.2, 0.6) },
        { kind: 'camera', property: 'eye', extrapolation: 'linear', keyframes: keyframes([0, 1, 6], [0, 1, 5]) },
      ],
    },
  });
}

function everyJointFieldRecipe() {
  const bodyNode = (id, x) => ({ id, geometry: 'cube', material: 'red', translation: [x, 1, 0] });
  const motor = { mode: 'position', target: 0.5, stiffness: 50, damping: 2, maxForce: 500 };
  return oneBoxRecipe({
    nodes: [
      { id: 'floor', geometry: 'cube', material: 'red', scale: [20, 0.2, 20], translation: [0, -0.1, 0] },
      bodyNode('p', 0), bodyNode('q', 1.5), bodyNode('r', 3), bodyNode('s', 4.5), bodyNode('t', 6), bodyNode('u', 7.5),
    ],
    physics: {
      duration: 1,
      bodies: [
        { node: 'floor', type: 'fixed' },
        ...['p', 'q', 'r', 's', 't', 'u'].map(node => ({ node, type: 'dynamic' })),
      ],
      joints: [
        { name: 'hinge', type: 'revolute', bodyA: 'p', bodyB: 'q', anchorA: [0.75, 0, 0], anchorB: [-0.75, 0, 0], axis: [0, 0, 1], limits: [-1, 1], motor, contactsEnabled: true },
        { name: 'slide', type: 'prismatic', bodyA: 'q', bodyB: 'r', axis: [1, 0, 0], limits: [0, 2], motor: { mode: 'velocity', target: 1, damping: 5, maxForce: 100 }, contactsEnabled: false },
        { name: 'glue', type: 'fixed', bodyA: 'r', bodyB: 's', breakImpulse: 25 },
        { name: 'ball', type: 'spherical', bodyA: 's', bodyB: 't', contactsEnabled: true },
        { name: 'band', type: 'spring', bodyA: 't', bodyB: 'u', restLength: 1.2, stiffness: 30, damping: 1.5, contactsEnabled: false },
      ],
    },
  });
}

for (const [label, buildRecipe, section] of [
  ['motion track', everyMotionFieldRecipe, 'motion'],
  ['physics joint', everyJointFieldRecipe, 'physics'],
]) {
  test(`every ${label} field the backend supports survives export, scene_create and export again`, async () => {
    await withRoundTripClient(async client => {
      await assertAccepted(client, buildRecipe());
      const firstExport = await exportedRecipe(client);
      assert.ok(firstExport[section], `${section} is exported`);
      await assertAccepted(client, firstExport);
      assert.deepEqual(await exportedRecipe(client), firstExport);
    });
  });
}

test('the exported motion and joint recipes keep each field that was authored', async () => {
  await withRoundTripClient(async client => {
    await assertAccepted(client, everyMotionFieldRecipe());
    const tracks = (await exportedRecipe(client)).motion.tracks;
    assert.ok(tracks.some(track => track.extrapolation === 'linear'));
    const modifierTypes = new Set(tracks.flatMap(track => (track.modifiers ?? []).map(modifier => modifier.type)));
    assert.deepEqual([...modifierTypes].sort(), MODIFIER_EXAMPLES.map(modifier => modifier.type).sort());
    await assertAccepted(client, everyJointFieldRecipe());
    const joints = (await exportedRecipe(client)).physics.joints;
    for (const field of ['name', 'motor', 'contactsEnabled', 'breakImpulse', 'restLength', 'stiffness', 'damping']) {
      assert.ok(joints.some(joint => joint[field] !== undefined), `joint field ${field} is exported`);
    }
  });
});

test('more than 8 modifiers and a spring joint without stiffness are refused', async () => {
  await withRoundTripClient(async client => {
    const tooMany = everyMotionFieldRecipe();
    tooMany.motion.tracks[0].modifiers = Array.from({ length: 9 }, () => MODIFIER_EXAMPLES[1]);
    assert.equal((await call(client, 'scene_create', { recipe: tooMany })).isError, true);
    const noStiffness = everyJointFieldRecipe();
    delete noStiffness.physics.joints[4].stiffness;
    const refusedSpring = await call(client, 'scene_create', { recipe: noStiffness });
    assert.equal(refusedSpring.isError, true);
    assert.match(refusedSpring.text, /stiffness/);
  });
});