Skip to content

3D engine that AI agents drive

17.1 KB
Raw Blame
import './support/load-agent-scene-modules.mjs';
import test from 'node:test';
import assert from 'node:assert/strict';
import { createAgentScene, agentSceneModulesNeeded } from '../src/agent-scene.js';
import { AGENT_SCENE_CAPABILITIES } from '../src/agent-scene-capabilities.js';
import { bakeCloth, createCloth, sampleClothFrames, weldVertices, CLOTH_LIMITS } from '../src/cloth.js';

function flagRecipe(cloth, extraNodes = [], segments = 12) {
  return {
    format: 'crucible.scene', schemaVersion: 1,
    geometries: [
      { id: 'sheet', type: 'grid', segments },
      { id: 'ball', type: 'sphere' },
      { id: 'slab', type: 'box', bevel: 0 },
    ],
    materials: [{ id: 'fabric', color: [0.7, 0.2, 0.2], doubleSided: true }, { id: 'stone', color: [0.5, 0.5, 0.5] }],
    nodes: [
      { id: 'flag', geometry: 'sheet', material: 'fabric', translation: [0, 2, 0], scale: [2, 1.5, 1] },
      ...extraNodes,
    ],
    cloth,
  };
}

const hangingFlag = { duration: 2, sheets: [{ node: 'flag', pin: ['top'] }] };

function clothPositions(scene, nodeId = 'flag') {
  return Array.from(scene.parts.find(part => part.name === nodeId).geometry.positions);
}

function worldY(scene, nodeId, localY) {
  const matrix = scene.parts.find(part => part.name === nodeId).matrix;
  return matrix[5] * localY + matrix[13];
}

test('the same time gives the same cloth positions, and a seek backwards reproduces them', () => {
  const scene = createAgentScene(flagRecipe({ ...hangingFlag, wind: [0, 0, 6] }));
  scene.sampleMotion(1.3);
  const first = clothPositions(scene);
  scene.sampleMotion(0.4);
  const earlier = clothPositions(scene);
  assert.notDeepEqual(earlier, first);
  scene.sampleMotion(1.3);
  assert.deepEqual(clothPositions(scene), first, 'seeking back to the same time repeats the positions');
  scene.sampleMotion(2);
  scene.sampleMotion(0.4);
  assert.deepEqual(clothPositions(scene), earlier, 'seeking backwards from the end repeats the earlier frame');
  const fresh = createAgentScene(flagRecipe({ ...hangingFlag, wind: [0, 0, 6] }));
  fresh.sampleMotion(1.3);
  assert.deepEqual(clothPositions(fresh), first, 'a second scene from the same recipe bakes identical frames');
});

test('time zero is the rest sheet, null restores it and a seek counts as a topology change', () => {
  const scene = createAgentScene(flagRecipe(hangingFlag));
  const restGeometry = scene.parts[0].geometry;
  const initialTopology = scene.topologyRevision;
  scene.sampleMotion(1);
  assert.notEqual(scene.parts[0].geometry, restGeometry);
  assert.ok(scene.topologyRevision > initialTopology, 'renderers must swap the deformed part');
  scene.sampleMotion(0);
  assert.equal(scene.parts[0].geometry, restGeometry);
  scene.sampleMotion(1);
  scene.sampleMotion(null);
  assert.equal(scene.parts[0].geometry, restGeometry);
  scene.sampleMotion(1);
  scene.sampleMotion(99);
  const held = clothPositions(scene);
  scene.sampleMotion(2);
  assert.deepEqual(clothPositions(scene), held, 'cloth holds its last frame after its duration');
});

test('pinned particles stay put while the rest of the sheet falls and hangs below the pins', () => {
  const scene = createAgentScene(flagRecipe(hangingFlag));
  scene.sampleMotion(2);
  const positions = clothPositions(scene);
  let topY = -Infinity;
  let bottomY = Infinity;
  for (let index = 0; index < positions.length; index += 3) {
    topY = Math.max(topY, positions[index + 1]);
    bottomY = Math.min(bottomY, positions[index + 1]);
  }
  assert.ok(Math.abs(topY - 0.5) < 1e-4, `the pinned top row did not move, got ${topY}`);
  assert.ok(bottomY < -0.1 && bottomY > -0.75, `the free edge hangs, got ${bottomY}`);
  assert.ok(worldY(scene, 'flag', topY) > 2.7, 'pinned row stays at its authored height');
});

test('stretch stays bounded under gravity and wind', () => {
  const recording = bakeSheet({ wind: [0, 0, 8], frames: 121, pinned: 'top' });
  const { positions, triangles } = recording.rest;
  const last = new Float32Array(recording.result.particleCount * 3);
  sampleClothFrames(recording.result, 2, last);
  let longest = 0;
  for (let corner = 0; corner < triangles.length; corner += 3) {
    for (let side = 0; side < 3; side++) {
      const first = triangles[corner + side] * 3;
      const second = triangles[corner + (side + 1) % 3] * 3;
      const restLength = Math.hypot(positions[first] - positions[second], positions[first + 1] - positions[second + 1], positions[first + 2] - positions[second + 2]);
      const length = Math.hypot(last[first] - last[second], last[first + 1] - last[second + 1], last[first + 2] - last[second + 2]);
      longest = Math.max(longest, length / restLength);
    }
  }
  assert.ok(longest < 1.25, `edges stretch at most 25 percent, got ${longest}`);
});

test('wind pushes the sheet along the wind and a calm sheet stays in its plane', () => {
  const calm = createAgentScene(flagRecipe(hangingFlag));
  const windy = createAgentScene(flagRecipe({ ...hangingFlag, wind: [0, 0, 8] }));
  calm.sampleMotion(1.5);
  windy.sampleMotion(1.5);
  const depth = scene => {
    const positions = clothPositions(scene);
    let total = 0;
    for (let index = 2; index < positions.length; index += 3) total += positions[index];
    return total / (positions.length / 3);
  };
  assert.ok(Math.abs(depth(calm)) < 1e-3, 'no wind, no sideways drift');
  assert.ok(depth(windy) > 0.05, `wind along +z pushes the sheet, got ${depth(windy)}`);
});

test('a sheet dropped on a ball drapes over it and never enters it', () => {
  const recipe = flagRecipe(
    { duration: 2, sheets: [{ node: 'flag' }], colliders: [{ node: 'ball', shape: 'ball' }] },
    [{ id: 'ball', geometry: 'ball', material: 'stone', translation: [0, 0, 0], scale: [0.5, 0.5, 0.5] }],
  );
  recipe.nodes[0] = { id: 'flag', geometry: 'sheet', material: 'fabric', translation: [0, 1, 0], rotation: [-0.7071068, 0, 0, 0.7071068], scale: [1.6, 1.6, 1] };
  const scene = createAgentScene(recipe);
  scene.sampleMotion(2);
  const matrix = scene.parts[0].matrix;
  const localPositions = clothPositions(scene);
  let nearest = Infinity;
  let lowest = Infinity;
  for (let index = 0; index < localPositions.length; index += 3) {
    const x = matrix[0] * localPositions[index] + matrix[4] * localPositions[index + 1] + matrix[8] * localPositions[index + 2] + matrix[12];
    const y = matrix[1] * localPositions[index] + matrix[5] * localPositions[index + 1] + matrix[9] * localPositions[index + 2] + matrix[13];
    const z = matrix[2] * localPositions[index] + matrix[6] * localPositions[index + 1] + matrix[10] * localPositions[index + 2] + matrix[14];
    nearest = Math.min(nearest, Math.hypot(x, y, z));
    lowest = Math.min(lowest, y);
  }
  assert.ok(nearest > 0.5 - 0.01, `no particle is inside the ball, nearest ${nearest}`);
  assert.ok(lowest < 0.4, `the edges fall past the ball's equator, lowest ${lowest}`);
});

test('a box collider acts as a floor the sheet stops on', () => {
  const recipe = flagRecipe(
    { duration: 2, sheets: [{ node: 'flag' }], colliders: [{ node: 'floor' }] },
    [{ id: 'floor', geometry: 'slab', material: 'stone', translation: [0, 0.5, 0], scale: [8, 0.2, 8] }],
  );
  recipe.nodes[0] = { id: 'flag', geometry: 'sheet', material: 'fabric', translation: [0, 2, 0], rotation: [-0.7071068, 0, 0, 0.7071068], scale: [1, 1, 1] };
  const scene = createAgentScene(recipe);
  scene.sampleMotion(2);
  const matrix = scene.parts[0].matrix;
  const positions = clothPositions(scene);
  let lowest = Infinity;
  for (let index = 0; index < positions.length; index += 3) {
    lowest = Math.min(lowest, matrix[1] * positions[index] + matrix[5] * positions[index + 1] + matrix[9] * positions[index + 2] + matrix[13]);
  }
  assert.ok(lowest >= 0.6 - 1e-3, `the sheet rests on the floor top at 0.6, lowest ${lowest}`);
});

test('the report lists particles, pinned count and final bounds', () => {
  const scene = createAgentScene(flagRecipe(hangingFlag));
  const report = scene.inspect().cloth;
  assert.equal(report.sheets[0].node, 'flag');
  assert.equal(report.sheets[0].particles, 13 * 13);
  assert.equal(report.sheets[0].pinned, 13);
  assert.equal(report.frames, 121);
  assert.equal(createAgentScene({ ...flagRecipe(null) }).inspect().cloth, undefined);
});

test('cloth recipes need the cloth module and plain recipes do not', () => {
  assert.deepEqual(agentSceneModulesNeeded(flagRecipe(hangingFlag)), ['cloth']);
  assert.deepEqual(agentSceneModulesNeeded(flagRecipe(null)), []);
});

test('set-cloth edits the section, null clears it and the recipe round trips', () => {
  const scene = createAgentScene(flagRecipe(null));
  assert.throws(() => scene.sampleMotion(1), /no motion, physics, cloth, particles/);
  scene.apply([{ type: 'set-cloth', cloth: hangingFlag }], { expectedRevision: scene.revision });
  scene.sampleMotion(1);
  const exported = scene.exportRecipe();
  assert.equal(exported.cloth.sheets[0].node, 'flag');
  const again = createAgentScene(exported);
  again.sampleMotion(1);
  assert.deepEqual(clothPositions(again), clothPositions(scene));
  scene.apply([{ type: 'set-cloth', cloth: null }], { expectedRevision: scene.revision });
  assert.equal(scene.exportRecipe().cloth, null);
  assert.equal(scene.parts[0].geometry.positions.length, createAgentScene(flagRecipe(null)).parts[0].geometry.positions.length);
});

test('editing a scene while the cloth is posed returns the rest sheet and tells renderers', () => {
  const scene = createAgentScene(flagRecipe(hangingFlag));
  scene.sampleMotion(1);
  const topology = scene.topologyRevision;
  scene.apply([{ type: 'set-material', id: 'fabric', roughness: 0.4 }], { expectedRevision: scene.revision });
  assert.ok(scene.topologyRevision > topology);
  assert.equal(scene.parts[0].geometry.positions.length, 13 * 13 * 3);
});

test('hostile cloth sections are rejected before any solver runs', () => {
  const bad = (cloth, pattern, nodes) => assert.throws(() => createAgentScene(flagRecipe(cloth, nodes)), pattern);
  bad({ duration: 2, sheets: [] }, /cloth\.sheets: got \[\]; expected at least one sheet/);
  bad({ duration: 0, sheets: [{ node: 'flag' }] }, /cloth\.duration: got 0; expected a number from 0\.1 to 10/);
  bad({ duration: 11, sheets: [{ node: 'flag' }] }, /cloth\.duration: got 11; expected a number from 0\.1 to 10/);
  bad({ duration: 2, sheets: [{ node: 'missing' }] }, /cloth\.sheets\[0\]\.node: got "missing"; expected the ID of a node in the recipe/);
  bad({ duration: 2, sheets: [{ node: 'flag' }, { node: 'flag' }] }, /cloth\.sheets\[1\]\.node: got "flag"; expected a node that cloth uses once/);
  bad({ duration: 2, sheets: [{ node: 'flag', stiffness: 2 }] }, /cloth\.sheets\[0\]\.stiffness: got 2; expected a number from 0\.01 to 1/);
  bad({ duration: 2, sheets: [{ node: 'flag', density: 0 }] }, /cloth\.sheets\[0\]\.density: got 0; expected a number from 0\.01 to 10/);
  bad({ duration: 2, sheets: [{ node: 'flag', pin: ['middle'] }] }, /cloth\.sheets\[0\]\.pin\[0\]: got "middle"; expected one of top, bottom/);
  bad({ duration: 2, sheets: [{ node: 'flag', surprise: 1 }] }, /cloth\.sheets\[0\]\.surprise: got 1; expected no such field/);
  bad({ duration: 2, surprise: 1, sheets: [{ node: 'flag' }] }, /cloth\.surprise: got 1; expected no such field/);
  bad({ duration: 2, wind: [0, 0, NaN], sheets: [{ node: 'flag' }] }, /finite/);
  bad({ duration: 2, wind: [0, 0, 1e9], sheets: [{ node: 'flag' }] }, /cloth\.wind\[2\]: got 1000000000; expected a number from -100 to 100/);
  bad({ duration: 2, gravity: [0, -Infinity, 0], sheets: [{ node: 'flag' }] }, /finite/);
  bad({ duration: 2, sheets: Array.from({ length: 9 }, () => ({ node: 'flag' })) }, /cloth\.sheets: got "9 entries"; expected an array of at most 8 entries/);
  bad({ duration: 2, sheets: [{ node: 'flag' }], colliders: Array.from({ length: 17 }, () => ({ node: 'flag' })) }, /cloth\.colliders: got "17 entries"; expected an array of at most 16 entries/);
  bad({ duration: 2, sheets: [{ node: 'flag' }], colliders: [{ node: 'flag' }] }, /cloth\.colliders\[0\]\.node: got "flag"; expected a node that cloth uses once/);
  bad({ duration: 2, sheets: [{ node: 'flag' }], colliders: [{ node: 'stone', shape: 'cone' }] }, /cloth\.colliders\[0\]\.shape: got "cone"; expected one of ball, box/, [{ id: 'stone', geometry: 'ball', material: 'stone' }]);
  bad({ duration: 2, sheets: [{ node: 'flag' }], colliders: [{ node: 'child' }] }, /cloth\.colliders\[0\]\.node: got "child"; expected a root node with no parent/, [{ id: 'child', parent: 'flag', geometry: 'ball', material: 'stone' }]);
  bad('cloth', /cloth: got "cloth"; expected a plain object/);
  bad({ duration: 2, sheets: 'flag' }, /cloth\.sheets: got "flag"; expected an array/);
});

test('particle and frame limits reject oversized bakes with a clear error', () => {
  const huge = flagRecipe({ duration: 10, sheets: [{ node: 'flag' }] }, [], 64);
  assert.throws(() => createAgentScene(huge), /solver operations|particle positions/);
  assert.throws(() => bakeCloth(new Float64Array(3 * (CLOTH_LIMITS.maxParticles + 1)), new Uint32Array([0, 1, 2]), { frameCount: 2 }), /particles/);
  const bounded = flagRecipe({ duration: 1, sheets: [{ node: 'flag' }] }, [], 64);
  assert.ok(createAgentScene(bounded).parts.length === 1, 'a 64 by 64 grid for one second fits');
});

test('a cloth node cannot also carry motion or a physics body', () => {
  const withMotion = flagRecipe(hangingFlag);
  withMotion.motion = { duration: 1, loop: false, tracks: [{ kind: 'node', id: 'flag', property: 'translation', interpolation: 'LINEAR', keyframes: [{ time: 0, value: [0, 2, 0] }, { time: 1, value: [1, 2, 0] }] }] };
  assert.throws(() => createAgentScene(withMotion), /cloth\.sheets\[0\]\.node: got "flag"; expected a node that stays where it is/);
});

test('welding joins vertices at one position so a seam cannot tear', () => {
  const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0]);
  const welded = weldVertices(positions, new Uint32Array([0, 1, 2, 3, 4, 5]));
  assert.equal(welded.representatives.length, 4);
  assert.equal(welded.particleOfVertex[1], welded.particleOfVertex[3]);
  assert.equal(welded.triangles.length, 6);
});

test('capabilities describe cloth limits that match the solver', () => {
  assert.equal(AGENT_SCENE_CAPABILITIES.cloth.limits.maxParticles, CLOTH_LIMITS.maxParticles);
  assert.equal(AGENT_SCENE_CAPABILITIES.cloth.limits.substeps, CLOTH_LIMITS.substeps);
  assert.equal(AGENT_SCENE_CAPABILITIES.cloth.limits.iterations, CLOTH_LIMITS.iterations);
  assert.ok(AGENT_SCENE_CAPABILITIES.operations.includes('set-cloth'));
  assert.ok(AGENT_SCENE_CAPABILITIES.geometryTypes.includes('grid'));
});

function bakeSheet({ wind, frames, pinned }) {
  const segments = 8;
  const positions = [];
  for (let row = 0; row <= segments; row++) {
    for (let column = 0; column <= segments; column++) {
      positions.push(column / segments - 0.5, 2 - row / segments, 0);
    }
  }
  const triangles = [];
  for (let row = 0; row < segments; row++) {
    for (let column = 0; column < segments; column++) {
      const first = row * (segments + 1) + column;
      const below = first + segments + 1;
      triangles.push(first, first + 1, below, first + 1, below + 1, below);
    }
  }
  const rest = { positions: Float64Array.from(positions), triangles: Uint32Array.from(triangles) };
  const topRow = pinned === 'top' ? Array.from({ length: segments + 1 }, (_, column) => column) : [];
  const result = bakeCloth(rest.positions, rest.triangles, { wind, pinned: topRow, frameCount: frames });
  return { rest, result };
}

test('the solver is bit-exact between runs', () => {
  const first = bakeSheet({ wind: [1, 0, 4], frames: 61, pinned: 'top' }).result.frames;
  const second = bakeSheet({ wind: [1, 0, 4], frames: 61, pinned: 'top' }).result.frames;
  assert.deepEqual(Buffer.from(first.buffer), Buffer.from(second.buffer));
});

const QUAD_POSITIONS = new Float32Array([0, 1, 0, 1, 1, 0, 0, 1, 1, 1, 1, 1]);
const QUAD_TRIANGLES = new Uint32Array([0, 1, 2, 1, 3, 2]);

test('a zero time step leaves the cloth where it is', () => {
  const cloth = createCloth(QUAD_POSITIONS, QUAD_TRIANGLES, {});
  cloth.step(0);
  assert.deepEqual(Array.from(cloth.positions), Array.from(QUAD_POSITIONS));
});

test('a time step that is negative, not a number or longer than a second names deltaSeconds', () => {
  const cloth = createCloth(QUAD_POSITIONS, QUAD_TRIANGLES, {});
  for (const bad of [-1 / 60, NaN, 1e6]) {
    assert.throws(() => cloth.step(bad), /Cloth step needs deltaSeconds from 0 to 1,/, `deltaSeconds ${bad}`);
  }
});

test('bakeCloth names a frameCount or framesPerSecond it cannot record', () => {
  for (const frameCount of [-2, 2.5, undefined]) {
    assert.throws(() => bakeCloth(QUAD_POSITIONS, QUAD_TRIANGLES, { frameCount }), /Cloth frameCount must be a whole number from 1/, `frameCount ${frameCount}`);
  }
  assert.throws(() => bakeCloth(QUAD_POSITIONS, QUAD_TRIANGLES, { frameCount: 3, framesPerSecond: 0 }), /Cloth framesPerSecond must be at least 1/);
});

test('sampleClothFrames rejects a NaN time and still reads the end for Infinity', () => {
  const recording = bakeCloth(QUAD_POSITIONS, QUAD_TRIANGLES, { frameCount: 3 });
  const target = new Float32Array(12);
  assert.throws(() => sampleClothFrames(recording, NaN, target), /Cloth sample time must be seconds/);
  sampleClothFrames(recording, Infinity, target);
  assert.deepEqual(Array.from(target), Array.from(recording.frames.subarray(24, 36)));
});