Skip to content

3D engine that AI agents drive

18.1 KB
Raw Blame
import assert from 'node:assert/strict';
import test from 'node:test';
import { mat4, quat, vec3 } from 'gl-matrix';
import { Object3D } from 'three';
import { createSceneGraph } from '../src/scene-graph.js';
import { createAnimationClip, createAnimationPlayer } from '../src/animation.js';
import { createAnimationMixer } from '../src/animation-mixer.js';
import { box } from '../src/geometry.js';

function transform(translation = [0, 0, 0], angles = [0, 0, 0], scale = [1, 1, 1]) {
  return mat4.fromRotationTranslationScale(mat4.create(), quat.fromEuler(quat.create(), ...angles), translation, scale);
}

function closeMatrix(actual, expected, tolerance = 2e-5) {
  for (let index = 0; index < 16; index++) {
    assert.ok(Math.abs(actual[index] - expected[index]) < tolerance, `component ${index}: ${actual[index]} differs from ${expected[index]}`);
  }
}

function snapshot(graph) {
  return graph.nodes.map(node => ({ name: node.name, parent: node.parent, world: Array.from(node.worldMatrix) }));
}

function material() {
  return { color: [0.5, 0.6, 0.7], metallic: 0.2, roughness: 0.5, emission: 0, map: {} };
}

test('child-first definitions propagate nested rotations and nonuniform scales like Three Object3D', () => {
  const definitions = [
    { name: 'tip', parent: 'arm', matrix: transform([0, 2, 0], [15, 25, 30], [0.5, 1.5, 0.75]) },
    { name: 'arm', parent: 'body', matrix: transform([1, 0, 0], [0, 0, 60], [1, 2, 1]) },
    { name: 'body', matrix: transform([3, 4, 5], [0, 45, 0], [2, 3, 4]) },
  ];
  const graph = createSceneGraph(definitions);
  const reference = new Map();
  for (const definition of definitions) {
    const object = new Object3D();
    object.matrixAutoUpdate = false;
    object.matrix.fromArray(definition.matrix);
    reference.set(definition.name, object);
  }
  reference.get('body').add(reference.get('arm'));
  reference.get('arm').add(reference.get('tip'));
  reference.get('body').updateMatrixWorld(true);
  for (const node of graph.nodes) closeMatrix(node.worldMatrix, reference.get(node.name).matrixWorld.elements);
  const reordered = createSceneGraph([...definitions].reverse());
  for (const node of graph.nodes) closeMatrix(reordered.getNode(node.name).worldMatrix, node.worldMatrix);
});

test('pivot conjugation places the pivot correctly under parent translation, rotation and scale', () => {
  const graph = createSceneGraph([
    { name: 'parent', matrix: transform([2, 0, 0]) },
    { name: 'rotor', parent: 'parent', matrix: transform([5, 0, 0], [0, 0, 90]), pivot: [1, 0, 0] },
  ]);
  const rotor = graph.getNode('rotor');
  closeMatrix(rotor.worldMatrix, transform([8, -1, 0], [0, 0, 90]));
  const pivotPosition = vec3.transformMat4(new Float64Array(3), [1, 0, 0], rotor.worldMatrix);
  assert.ok(Math.abs(pivotPosition[0] - 8) < 1e-5);
  assert.ok(Math.abs(pivotPosition[1]) < 1e-5);
  graph.getNode('parent').localMatrix.set(transform([0, 0, 0], [0, 0, 90], [2, 3, 1]));
  graph.update();
  const transformedPivot = vec3.transformMat4(new Float64Array(3), [1, 0, 0], rotor.worldMatrix);
  assert.ok(Math.abs(transformedPivot[0]) < 1e-5);
  assert.ok(Math.abs(transformedPivot[1] - 12) < 1e-5);
});

test('roots, empty graphs and multiple render meshes keep a stable CrucibleRenderer part shape', () => {
  const geometry = box(0, 1);
  const sharedMaterial = material();
  const graph = createSceneGraph([
    { name: 'first', matrix: transform([2, 0, 0]), geometry, material: sharedMaterial },
    { name: 'group' },
    { name: 'second', matrix: transform([0, 3, 0]), geometry, material: sharedMaterial },
  ]);
  const parts = graph.parts;
  const targets = graph.animationTargets;
  assert.equal(parts.length, 2);
  assert.equal(targets.length, 3);
  assert.deepEqual(parts.map(part => part.name), ['first', 'second']);
  for (const part of parts) {
    assert.equal(part.geometry, geometry);
    assert.equal(part.material, sharedMaterial);
    assert.equal(part.matrix, graph.getNode(part.name).worldMatrix);
    assert.ok(part.matrix instanceof Float32Array);
    assert.ok(part.matrix.every(Number.isFinite));
    assert.ok(part.geometry.positions instanceof Float32Array);
  }
  for (const target of targets) assert.equal(target.matrix, graph.getNode(target.name).localMatrix);
  assert.equal(graph.update(), parts);
  assert.equal(graph.parts, parts);
  assert.equal(graph.animationTargets, targets);
  const empty = createSceneGraph();
  assert.deepEqual(empty.nodes, []);
  assert.deepEqual(empty.update(), []);
});

test('definition matrices and pivots copy serializable inputs while geometry and material remain shared', () => {
  const definitions = [{ name: 'root', matrix: Array.from(transform([3, 0, 0])), pivot: [1, 0, 0] }];
  const restored = createSceneGraph(JSON.parse(JSON.stringify(definitions)));
  const graph = createSceneGraph(definitions);
  definitions[0].matrix[12] = 100;
  definitions[0].pivot[0] = 100;
  definitions[0].name = 'changed';
  graph.update();
  closeMatrix(graph.getNode('root').worldMatrix, restored.getNode('root').worldMatrix);
  assert.deepEqual(Array.from(graph.getNode('root').pivot), [1, 0, 0]);
  assert.throws(() => graph.getNode('changed'), /not found/);
});

test('nonsingular affine shear and reflected transforms remain valid graph transforms', () => {
  const shear = mat4.create();
  shear[4] = 0.5;
  const graph = createSceneGraph([
    { name: 'reflected', matrix: transform([0, 0, 0], [0, 0, 0], [-1, 2, 3]) },
    { name: 'sheared', parent: 'reflected', matrix: shear },
  ]);
  assert.ok(mat4.determinant(graph.getNode('sheared').worldMatrix) < 0);
  const clip = createAnimationClip({ duration: 1, tracks: [{ target: 'sheared', property: 'translation', keyframes: [{ time: 0, value: [0, 0, 0] }] }] });
  assert.throws(() => createAnimationPlayer(clip, graph.animationTargets), /shear/);
});

test('local mixer and parent animation propagate independently for arbitrary seek order', () => {
  const graph = createSceneGraph([
    { name: 'parent', matrix: transform([0, 0, 0], [0, 0, 0], [2, 3, 1]) },
    { name: 'child', parent: 'parent', matrix: transform([1, 0, 0]), pivot: [1, 0, 0], geometry: box(0, 1), material: material() },
  ]);
  const parentClip = createAnimationClip({ duration: 2, tracks: [{ target: 'parent', property: 'translation', keyframes: [
    { time: 0, value: [0, 0, 0] }, { time: 2, value: [4, 0, 0] },
  ] }] });
  const childClip = createAnimationClip({ duration: 2, tracks: [{ target: 'child', property: 'rotation', keyframes: [
    { time: 0, value: [0, 0, 0, 1] }, { time: 2, value: Array.from(quat.fromEuler(quat.create(), 0, 0, 90)) },
  ] }] });
  const parentPlayer = createAnimationPlayer(parentClip, graph.animationTargets);
  const mixer = createAnimationMixer(graph.animationTargets);
  mixer.clipAction(childClip).play();
  parentPlayer.apply(1);
  mixer.apply(1);
  graph.update();
  const expected = snapshot(graph);
  const node = graph.getNode('child');
  const world = node.worldMatrix;
  const local = node.localMatrix;
  const pivotPosition = vec3.transformMat4(new Float64Array(3), [1, 0, 0], world);
  assert.ok(Math.abs(pivotPosition[0] - 6) < 1e-5);
  assert.ok(Math.abs(pivotPosition[1]) < 1e-5);
  for (const time of [2, 0, 1.75, 0.25, 1]) {
    mixer.apply(time);
    parentPlayer.apply(time);
    graph.update();
  }
  assert.deepEqual(snapshot(graph), expected);
  assert.equal(node.worldMatrix, world);
  assert.equal(node.localMatrix, local);
});

test('animation target material assignment forwards retained isolation to render parts and preserves map identity', () => {
  const shared = Object.freeze(material());
  const graph = createSceneGraph([
    { name: 'first', geometry: box(0, 1), material: shared },
    { name: 'second', geometry: box(0, 1), material: shared },
  ]);
  const clip = createAnimationClip({ duration: 2, tracks: [{ target: 'first', property: 'emission', keyframes: [
    { time: 0, value: 0 }, { time: 2, value: 2 },
  ] }] });
  const player = createAnimationPlayer(clip, graph.animationTargets);
  const renderPart = graph.parts[0];
  const isolated = renderPart.material;
  assert.notEqual(isolated, shared);
  assert.equal(isolated.map, shared.map);
  assert.equal(graph.animationTargets[0].material, isolated);
  assert.equal(graph.getNode('first').material, isolated);
  const mixer = createAnimationMixer(graph.animationTargets);
  mixer.clipAction(clip).play();
  assert.equal(renderPart.material, isolated);
  player.apply(1);
  assert.equal(renderPart.material.emission, 1);
  mixer.apply(2);
  assert.equal(renderPart.material.emission, 2);
  assert.equal(renderPart.material, isolated);
  assert.equal(graph.parts[1].material, shared);
  assert.equal(shared.emission, 0);
  const replacement = { ...isolated, emission: 3 };
  graph.animationTargets[0].material = replacement;
  assert.equal(renderPart.material, replacement);
});

test('all published world matrices remain unchanged when any local, pivot or composed world is invalid', () => {
  const graph = createSceneGraph([{ name: 'root' }, { name: 'child', parent: 'root', matrix: transform([1, 0, 0]) }]);
  const expected = snapshot(graph);
  const root = graph.getNode('root');
  const child = graph.getNode('child');
  root.localMatrix[12] = 5;
  for (const corrupt of [
    () => { child.localMatrix[0] = NaN; },
    () => { child.localMatrix[3] = 1; },
    () => { child.localMatrix[0] = 0; },
    () => { child.pivot[0] = Infinity; },
  ]) {
    child.localMatrix.set(transform([1, 0, 0]));
    child.pivot[0] = 0;
    corrupt();
    assert.throws(() => graph.update(), RangeError);
    assert.deepEqual(snapshot(graph), expected);
  }
  child.pivot[0] = 0;
  root.localMatrix.set(transform([0, 0, 0], [0, 0, 0], [1e30, 1, 1]));
  child.localMatrix.set(transform([0, 0, 0], [0, 0, 0], [1e30, 1, 1]));
  assert.throws(() => graph.update(), /finite Float32/);
  assert.deepEqual(snapshot(graph), expected);
  root.localMatrix.set(transform([0, 0, 0], [0, 0, 0], [1e-30, 1, 1]));
  child.localMatrix.set(transform([0, 0, 0], [0, 0, 0], [1e-30, 1, 1]));
  assert.throws(() => graph.update(), /nonsingular/);
  assert.deepEqual(snapshot(graph), expected);
  root.localMatrix.set(transform([5, 0, 0]));
  child.localMatrix.set(transform([1, 0, 0]));
  graph.update();
  assert.equal(child.worldMatrix[12], 6);
});

test('keepWorld reparent preserves pivoted subtrees under rotated nonuniform scales without changing identities', () => {
  const graph = createSceneGraph([
    { name: 'first', matrix: transform([2, 3, 4], [0, 35, 15], [2, 3, 4]) },
    { name: 'second', matrix: transform([-3, 1, 2], [20, -25, 10], [1, 2, 3]) },
    { name: 'child', parent: 'first', matrix: transform([1, 2, 0], [30, 45, 0]), pivot: [0.5, 1, 0], geometry: box(0, 1), material: material() },
    { name: 'tip', parent: 'child', matrix: transform([0, 2, 1]) },
  ]);
  const child = graph.getNode('child');
  const localIdentity = child.localMatrix;
  const worldIdentity = child.worldMatrix;
  const partsIdentity = graph.parts;
  const childWorld = Array.from(child.worldMatrix);
  const tipWorld = Array.from(graph.getNode('tip').worldMatrix);
  assert.equal(graph.reparent('child', 'second', { keepWorld: true }), graph);
  assert.equal(child.parent, 'second');
  assert.equal(child.localMatrix, localIdentity);
  assert.equal(child.worldMatrix, worldIdentity);
  assert.equal(graph.parts, partsIdentity);
  closeMatrix(child.worldMatrix, childWorld);
  closeMatrix(graph.getNode('tip').worldMatrix, tipWorld);
  graph.reparent('child', null, { keepWorld: true });
  assert.equal(child.parent, null);
  closeMatrix(child.worldMatrix, childWorld);
  closeMatrix(graph.getNode('tip').worldMatrix, tipWorld);
});

test('reparent without keepWorld preserves local pose and keepWorld includes unpublished local edits', () => {
  const graph = createSceneGraph([
    { name: 'first', matrix: transform([2, 0, 0]) },
    { name: 'second', matrix: transform([10, 0, 0]) },
    { name: 'child', parent: 'first', matrix: transform([1, 0, 0]) },
  ]);
  const child = graph.getNode('child');
  const initialLocal = Array.from(child.localMatrix);
  graph.reparent('child', 'second');
  assert.deepEqual(Array.from(child.localMatrix), initialLocal);
  assert.equal(child.worldMatrix[12], 11);
  graph.getNode('second').localMatrix[12] = 20;
  graph.reparent('child', 'first', { keepWorld: true });
  assert.equal(child.worldMatrix[12], 21);
  assert.equal(child.localMatrix[12], 19);
  assert.equal(graph.getNode('second').worldMatrix[12], 20);
});

test('reparent rejects cycles, excessive depth and invalid candidate worlds atomically', () => {
  const graph = createSceneGraph([{ name: 'root' }, { name: 'child', parent: 'root' }, { name: 'other' }], { maxDepth: 2 });
  const expected = snapshot(graph);
  const local = Array.from(graph.getNode('root').localMatrix);
  assert.throws(() => graph.reparent('root', 'child'), /cycle/);
  assert.throws(() => graph.reparent('root', 'root'), /cycle/);
  assert.throws(() => graph.reparent('other', 'child'), /maxDepth/);
  assert.throws(() => graph.reparent('child', 'missing'), /not found/);
  assert.throws(() => graph.reparent('missing', 'root'), /not found/);
  assert.throws(() => graph.reparent('child', 'other', { keepWorld: 1 }), TypeError);
  assert.deepEqual(snapshot(graph), expected);
  assert.deepEqual(Array.from(graph.getNode('root').localMatrix), local);

  const extreme = createSceneGraph([
    { name: 'large', matrix: transform([0, 0, 0], [0, 0, 0], [1e30, 1, 1]) },
    { name: 'small', matrix: transform([0, 0, 0], [0, 0, 0], [1e-30, 1, 1]) },
    { name: 'child', matrix: transform([0, 0, 0], [0, 0, 0], [1e30, 1, 1]) },
  ]);
  const previous = snapshot(extreme);
  const previousLocal = Array.from(extreme.getNode('child').localMatrix);
  assert.throws(() => extreme.reparent('child', 'large'), /finite Float32/);
  assert.throws(() => extreme.reparent('child', 'small', { keepWorld: true }), /finite Float32/);
  assert.deepEqual(snapshot(extreme), previous);
  assert.deepEqual(Array.from(extreme.getNode('child').localMatrix), previousLocal);
});

test('hierarchy guards bound node count and depth without recursive traversal', () => {
  assert.throws(() => createSceneGraph([{ name: 'first' }, { name: 'first' }]), /Duplicate/);
  assert.throws(() => createSceneGraph([{ name: 'child', parent: 'missing' }]), /not found/);
  assert.throws(() => createSceneGraph([{ name: 'first', parent: 'second' }, { name: 'second', parent: 'first' }]), /cycle/);
  assert.throws(() => createSceneGraph([{ name: 'self', parent: 'self' }]), /cycle/);
  assert.throws(() => createSceneGraph([{ name: 'root' }, { name: 'child', parent: 'root' }], { maxDepth: 1 }), /maxDepth/);
  assert.throws(() => createSceneGraph([{ name: 'first' }, { name: 'second' }], { maxNodes: 1 }), /maxNodes/);
  for (const limit of [0, -1, 1.5, Infinity, NaN]) {
    assert.throws(() => createSceneGraph([], { maxNodes: limit }), RangeError);
    assert.throws(() => createSceneGraph([], { maxDepth: limit }), RangeError);
  }
  const chain = Array.from({ length: 300 }, (_, index) => ({ name: `node-${index}`, parent: index ? `node-${index - 1}` : null }));
  assert.throws(() => createSceneGraph(chain), /maxDepth/);
  assert.equal(createSceneGraph(chain, { maxDepth: 300 }).nodes.length, 300);
});

test('malformed matrices, pivots and mesh definitions fail before graph publication', () => {
  assert.throws(() => createSceneGraph({}), TypeError);
  assert.throws(() => createSceneGraph([{ name: '' }]), TypeError);
  assert.throws(() => createSceneGraph([{ name: 'node', parent: 1 }]), TypeError);
  assert.throws(() => createSceneGraph([{ name: 'node', matrix: [1] }]), TypeError);
  const nonfinite = Array.from(mat4.create());
  nonfinite[0] = 1e100;
  assert.throws(() => createSceneGraph([{ name: 'node', matrix: nonfinite }]), TypeError);
  assert.throws(() => createSceneGraph([{ name: 'node', matrix: transform([0, 0, 0], [0, 0, 0], [0, 1, 1]) }]), /nonsingular/);
  const projective = mat4.create();
  projective[3] = 0.5;
  assert.throws(() => createSceneGraph([{ name: 'node', matrix: projective }]), /affine/);
  assert.throws(() => createSceneGraph([{ name: 'node', pivot: [Infinity, 0, 0] }]), TypeError);
  assert.throws(() => createSceneGraph([{ name: 'node', geometry: {} }]), TypeError);
  assert.throws(() => createSceneGraph([{ name: 'node', material: {} }]), TypeError);
});

test('update reuses parent matrices and effective-local buffers across repeated evaluation', () => {
  const graph = createSceneGraph([{ name: 'parent' }, { name: 'child', parent: 'parent', matrix: transform([1, 0, 0]) }]);
  const originalMultiply = mat4.multiply;
  let retained;
  let calls = 0;
  mat4.multiply = (output, parent, local) => {
    if (!retained) retained = [output, parent, local];
    else {
      assert.equal(output, retained[0]);
      assert.equal(parent, retained[1]);
      assert.equal(local, retained[2]);
    }
    calls++;
    return originalMultiply(output, parent, local);
  };
  try {
    for (let frame = 0; frame < 200; frame++) {
      graph.getNode('parent').localMatrix[12] = frame * 17 % 20;
      graph.update();
    }
  } finally {
    mat4.multiply = originalMultiply;
  }
  assert.equal(calls, 200);
});

test('replaceLocalMatrices moves the named nodes and their children, and the returned function puts them back', () => {
  const graph = createSceneGraph([
    { name: 'parent' },
    { name: 'child', parent: 'parent', matrix: transform([1, 0, 0]) },
    { name: 'other' },
  ]);
  const before = snapshot(graph);
  const restore = graph.replaceLocalMatrices(new Map([['parent', transform([0, 5, 0])]]));
  closeMatrix(graph.getNode('parent').worldMatrix, transform([0, 5, 0]));
  closeMatrix(graph.getNode('child').worldMatrix, transform([1, 5, 0]));
  assert.deepEqual(snapshot(graph).find(node => node.name === 'other'), before.find(node => node.name === 'other'));
  restore();
  assert.deepEqual(snapshot(graph), before);
});

test('replaceLocalMatrices throws on a non-finite matrix or an unknown name and leaves the graph unchanged', () => {
  const graph = createSceneGraph([{ name: 'a' }, { name: 'b' }]);
  const before = snapshot(graph);
  const broken = transform([1, 2, 3]);
  broken[5] = Number.NaN;
  assert.throws(() => graph.replaceLocalMatrices(new Map([['a', transform([9, 9, 9])], ['b', broken]])));
  assert.deepEqual(snapshot(graph), before);
  assert.throws(() => graph.replaceLocalMatrices(new Map([['missing', transform()]])));
  assert.deepEqual(snapshot(graph), before);
});