Skip to content

3D engine that AI agents drive

12.4 KB
Raw Blame
import './support/load-agent-scene-modules.mjs';
import assert from 'node:assert/strict';
import test from 'node:test';
import { mat4, quat, vec3 } 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';

const DEGREES = Math.PI / 180;

function nodeRecipe(nodes, motion, materials = []) {
  return {
    format: 'crucible.scene', schemaVersion: 1,
    geometries: [{ id: 'box', type: 'box', bevel: 0 }],
    materials: [{ id: 'paint', color: [0.6, 0.6, 0.6] }, ...materials],
    nodes: nodes.map(node => ({ geometry: 'box', material: 'paint', ...node })),
    ...(motion ? { motion } : {}),
  };
}

function part(scene, name) {
  return scene.parts.find(candidate => candidate.name === name);
}

function worldPosition(scene, name) {
  return Array.from(mat4.getTranslation(new Float64Array(3), part(scene, name).matrix));
}

function worldEulerDegrees(scene, name) {
  return eulerFromQuaternion(mat4.getRotation(new Float64Array(4), part(scene, name).matrix)).map(radians => radians / DEGREES);
}

function rotationOf(x, y, z) {
  return Array.from(quaternionFromEuler(new Float64Array(4), x * DEGREES, y * DEGREES, z * DEGREES));
}

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

function sampledAt(recipe, time) {
  const scene = createAgentScene(recipe);
  scene.sampleMotion(time);
  return scene;
}

const SOURCE = { id: 'source', translation: [1, 2, 3], rotation: rotationOf(20, 30, 40), scale: [2, 3, 4] };
const OWNER = { id: 'owner', translation: [0, 0, 0], scale: [1, 1, 1] };
const motionWith = (constraints, extra = {}) => ({ duration: 1, tracks: [], constraints, ...extra });

test('copy_location copies chosen axes, inverts, and can offset', () => {
  const run = options => worldPosition(sampledAt(nodeRecipe([SOURCE, { ...OWNER, translation: [5, 5, 5] }], motionWith([{ type: 'copy_location', node: 'owner', target: 'source', ...options }])), 0), 'owner');
  assertClose(run({}), [1, 2, 3]);
  assertClose(run({ axes: ['x', 'z'] }), [1, 5, 3]);
  assertClose(run({ invert: ['y'] }), [1, -2, 3]);
  assertClose(run({ offset: true }), [6, 7, 8]);
});

test('copy_rotation replaces chosen Euler axes in world space and adds on request', () => {
  const owner = { ...OWNER, rotation: rotationOf(10, 0, 0) };
  const run = options => worldEulerDegrees(sampledAt(nodeRecipe([SOURCE, owner], motionWith([{ type: 'copy_rotation', node: 'owner', target: 'source', ...options }])), 0), 'owner');
  assertClose(run({}), [20, 30, 40], 1e-3);
  assertClose(run({ axes: ['z'] }), [10, 0, 40], 1e-3);
  assertClose(run({ axes: ['x'], mix: 'add' }), [30, 0, 0], 1e-3);
});

test('copy_scale copies and multiplies', () => {
  const owner = { ...OWNER, scale: [2, 2, 2] };
  const scaleOf = options => {
    const scene = sampledAt(nodeRecipe([{ ...SOURCE, rotation: [0, 0, 0, 1] }, owner], motionWith([{ type: 'copy_scale', node: 'owner', target: 'source', ...options }])), 0);
    return Array.from(mat4.getScaling(new Float64Array(3), part(scene, 'owner').matrix));
  };
  assertClose(scaleOf({}), [2, 3, 4]);
  assertClose(scaleOf({ axes: ['y'] }), [2, 3, 2]);
  assertClose(scaleOf({ offset: true }), [4, 6, 8]);
});

test('limit_location and limit_rotation clamp, in world or local space', () => {
  const owner = { ...OWNER, translation: [5, -5, 0.5], rotation: rotationOf(80, -70, 10) };
  const scene = sampledAt(nodeRecipe([owner], motionWith([
    { type: 'limit_location', node: 'owner', x: [-1, 1], y: [-1, 1] },
    { type: 'limit_rotation', node: 'owner', x: [-45, 45], y: [-30, 30] },
  ])), 0);
  assertClose(worldPosition(scene, 'owner'), [1, -1, 0.5]);
  assertClose(worldEulerDegrees(scene, 'owner'), [45, -30, 10], 1e-3);
  const underParent = sampledAt(nodeRecipe([{ id: 'holder', translation: [10, 0, 0] }, { ...OWNER, parent: 'holder', translation: [5, 0, 0] }],
    motionWith([{ type: 'limit_location', node: 'owner', x: [0, 2], space: 'local' }])), 0);
  assertClose(worldPosition(underParent, 'owner'), [12, 0, 0]);
});

test('track_to points the track axis at the target with the up axis toward worldUp', () => {
  const recipe = nodeRecipe([{ id: 'lamp', translation: [-1, 1, 0], scale: [0.1, 0.1, 0.1] }, { id: 'ball', translation: [0.3, 1.5, 0.3], scale: [0.05, 0.05, 0.05] }],
    motionWith([{ type: 'track_to', node: 'lamp', target: 'ball' }]));
  const matrix = part(sampledAt(recipe, 0), 'lamp').matrix;
  const trackAxis = vec3.normalize(new Float64Array(3), [-matrix[8], -matrix[9], -matrix[10]]);
  const toBall = vec3.normalize(new Float64Array(3), [1.3, 0.5, 0.3]);
  assertClose(trackAxis, Array.from(toBall), 1e-5);
  assert.ok(matrix[5] > 0, 'the up axis leans toward world up');
  const plusZ = nodeRecipe(recipe.nodes, motionWith([{ type: 'track_to', node: 'lamp', target: 'ball', trackAxis: '+z', upAxis: 'x', worldUp: [0, 0, 1] }]));
  const turned = part(sampledAt(plusZ, 0), 'lamp').matrix;
  assertClose(vec3.normalize(new Float64Array(3), [turned[8], turned[9], turned[10]]), Array.from(toBall), 1e-5);
  assert.ok(turned[2] > 0, 'the x axis leans toward the given up');
});

test('child_of keeps the owner in place at rest and carries it with the target; influence blends', () => {
  const nodes = [{ id: 'platform', translation: [1, 0, 0] }, { id: 'cargo', translation: [0, 1, 0], scale: [0.2, 0.2, 0.2] }];
  const move = { kind: 'node', id: 'platform', property: 'translation', keyframes: [{ time: 0, value: [1, 0, 0] }, { time: 1, value: [3, 0, 0] }] };
  const run = (options, time) => worldPosition(sampledAt(nodeRecipe(nodes, { duration: 1, tracks: [move], constraints: [{ type: 'child_of', node: 'cargo', target: 'platform', ...options }] }), time), 'cargo');
  assertClose(run({}, 0), [0, 1, 0]);
  assertClose(run({}, 1), [2, 1, 0]);
  assertClose(run({ influence: 0.5 }, 1), [1, 1, 0]);
  assertClose(run({ inverse: 'none' }, 0), [1, 1, 0]);
});

test('floor keeps a node above the target plane along the chosen axis', () => {
  const run = (y, options = {}) => worldPosition(sampledAt(nodeRecipe([{ id: 'ground', translation: [0, 0.5, 0] }, { id: 'ball', translation: [0, y, 0] }],
    motionWith([{ type: 'floor', node: 'ball', target: 'ground', ...options }])), 0), 'ball');
  assertClose(run(-1), [0, 0.5, 0]);
  assertClose(run(2), [0, 2, 0]);
  assertClose(run(0, { offset: 0.25 }), [0, 0.75, 0]);
});

test('constraints run in order on the result of the one before', () => {
  const recipe = nodeRecipe([SOURCE, { ...OWNER, translation: [9, 9, 9] }], motionWith([
    { type: 'copy_location', node: 'owner', target: 'source' },
    { type: 'limit_location', node: 'owner', y: [0, 1] },
  ]));
  assertClose(worldPosition(sampledAt(recipe, 0), 'owner'), [1, 1, 3]);
});

test('constraints follow a target moved by a track and a seek equals playing', () => {
  const recipe = nodeRecipe([{ id: 'lead', translation: [0, 0, 0] }, { id: 'follower', translation: [0, 0, 0] }, { id: 'ground', translation: [0, 0.2, 0] }], {
    duration: 2,
    tracks: [{ kind: 'node', id: 'lead', property: 'translation', keyframes: [{ time: 0, value: [0, 1, 0] }, { time: 2, value: [4, -1, 2] }] }],
    constraints: [
      { type: 'copy_location', node: 'follower', target: 'lead', influence: { clamp: [{ mul: ['time', 0.5] }, 0, 1] } },
      { type: 'floor', node: 'follower', target: 'ground' },
    ],
  });
  const played = createAgentScene(recipe);
  [0, 0.4, 0.8, 1.2, 1.6, 2, 1.2, 0.5].forEach(time => played.sampleMotion(time));
  const sought = createAgentScene(recipe);
  sought.sampleMotion(1.4);
  played.sampleMotion(1.4);
  assert.deepEqual(worldPosition(sought, 'follower'), worldPosition(played, 'follower'));
  assertClose(worldPosition(sought, 'follower'), [0.7 * 2.8, 0.2, 0.7 * 1.4], 1e-5, 'a 70 percent blend toward the lead, floored at the ground');
  sought.sampleMotion(0);
  assertClose(worldPosition(sought, 'follower'), [0, 0.2, 0], 1e-6);
});

test('drivers set a node component and a material property from time and other nodes', () => {
  const recipe = nodeRecipe([{ id: 'wheel', translation: [0, 1, 0] }, { id: 'lamp', translation: [0, 0, 0] }, { id: 'bulb', material: 'glow' }], {
    duration: 2,
    tracks: [{ kind: 'node', id: 'wheel', property: 'translation', keyframes: [{ time: 0, value: [0, 1, 0] }, { time: 2, value: [4, 1, 0] }] }],
    drivers: [
      { target: { kind: 'node', id: 'lamp', property: 'rotation', component: 'z' }, expression: { mul: [{ node: 'wheel', property: 'translation', component: 'x' }, 10] } },
      { target: { kind: 'node', id: 'lamp', property: 'translation', component: 'y' }, expression: { add: [1, { mul: [0.5, { sin: [{ mul: ['time', 3.14159265] }] }] }] } },
      { target: { kind: 'material', id: 'glow', property: 'roughness' }, expression: { clamp: [{ div: ['time', 2] }, 0, 1] } },
      { target: { kind: 'material', id: 'glow', property: 'color', component: 'x' }, expression: { saturate: [{ node: 'wheel', property: 'translation', component: 'x' }] } },
    ],
  }, [{ id: 'glow', color: [0.1, 0.2, 0.3], roughness: 0.9 }]);
  const scene = sampledAt(recipe, 0.5);
  assertClose(worldEulerDegrees(scene, 'lamp'), [0, 0, 10], 1e-3);
  assertClose(worldPosition(scene, 'lamp'), [0, 1.5, 0], 1e-4);
  const glow = part(scene, 'bulb').material;
  assert.ok(Math.abs(glow.roughness - 0.25) < 1e-6, `roughness ${glow.roughness}`);
  assertClose(glow.color, [1, 0.2, 0.3], 1e-6);
  const resampled = sampledAt(recipe, 0.5);
  assert.deepEqual(worldPosition(resampled, 'lamp'), worldPosition(scene, 'lamp'));
});

test('a seek equals play for drivers too', () => {
  const recipe = nodeRecipe([{ id: 'lamp' }], { duration: 3, tracks: [], drivers: [{ target: { kind: 'node', id: 'lamp', property: 'translation', component: 'x' }, expression: { mul: ['time', 2] } }] });
  const played = createAgentScene(recipe);
  [0, 1, 2.5, 0.5].forEach(time => played.sampleMotion(time));
  const sought = sampledAt(recipe, 0.5);
  assert.deepEqual(worldPosition(played, 'lamp'), worldPosition(sought, 'lamp'));
});

test('drivers and constraints reject anything that is not bounded data', () => {
  const driver = expression => nodeRecipe([{ id: 'lamp' }], { duration: 1, tracks: [], drivers: [{ target: { kind: 'node', id: 'lamp', property: 'translation', component: 'x' }, expression }] });
  assert.throws(() => createAgentScene(driver('process.exit(1)')), /use a number, "time"/);
  assert.throws(() => createAgentScene(driver({ constructor: [1, 2] })), /unknown operator/);
  assert.throws(() => createAgentScene(driver({ add: [1] })), /2 to 8 operands/);
  assert.throws(() => createAgentScene(driver({ node: 'missing', property: 'translation', component: 'x' })), /not in this scene/);
  assert.throws(() => createAgentScene(driver({ div: [1, 0] })).sampleMotion(0), /finite/);
  let deep = 1;
  for (let level = 0; level < 10; level++) deep = { neg: [deep] };
  assert.throws(() => createAgentScene(driver(deep)), /nests deeper/);
  const clash = nodeRecipe([{ id: 'lamp' }], {
    duration: 1, tracks: [{ kind: 'node', id: 'lamp', property: 'translation', keyframes: [{ time: 0, value: [0, 0, 0] }] }],
    drivers: [{ target: { kind: 'node', id: 'lamp', property: 'translation', component: 'x' }, expression: 1 }],
  });
  assert.throws(() => createAgentScene(clash), /a track on .* already moves/);
  const constraint = fields => nodeRecipe([{ id: 'lamp' }, { id: 'ball' }], motionWith([{ type: 'copy_location', node: 'lamp', target: 'ball', ...fields }]));
  assert.throws(() => createAgentScene(constraint({ target: 'lamp' })), /itself/);
  assert.throws(() => createAgentScene(constraint({ axes: ['w'] })), /distinct axes/);
  assert.throws(() => createAgentScene(constraint({ influence: 2 })), /influence/);
  assert.throws(() => createAgentScene(constraint({ extra: 1 })), /Unknown or unsupported/);
  assert.throws(() => createAgentScene(nodeRecipe([{ id: 'lamp' }], motionWith([{ type: 'wiggle', node: 'lamp' }]))), /type must be one of/);
  assert.throws(() => createAgentScene(nodeRecipe([{ id: 'lamp' }], motionWith([{ type: 'limit_rotation', node: 'lamp', x: [-200, 10] }]))), /within -180 and 180/);
});

test('the capabilities list every constraint type', () => {
  assert.deepEqual([...AGENT_SCENE_CAPABILITIES.motionConstraints], [...CONSTRAINT_TYPES]);
  assert.ok(quat.length(rotationOf(1, 2, 3)) > 0);
});