3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import './support/load-agent-scene-modules.mjs';
import test from 'node:test';
import assert from 'node:assert/strict';
import { createAgentScene } from '../src/agent-scene.js';
import { AGENT_SCENE_CAPABILITIES } from '../src/agent-scene-capabilities.js';
import { createCollisionSurface, findFirstCollision } from '../src/particle-collision.js';
import { createParticleLaunches, particleStateAt } from '../src/particles.js';
import { icoSphere } from '../src/geometry.js';
// A unit box is 1 m wide; the slab is scaled to 4 m x 0.2 m x 4 m, so its top face sits at y = 0.1.
const SLAB_TOP = 0.1;
function dropRecipe(system, { colliderScale = [4, 0.2, 4], extra = {} } = {}) {
return {
format: 'crucible.scene', schemaVersion: 1,
geometries: [{ id: 'speck', type: 'box', bevel: 0 }, { id: 'block', type: 'box', bevel: 0 }],
materials: [{ id: 'glow', color: [1, 0.5, 0.1], emission: 4 }],
nodes: [
{ id: 'sparks', geometry: 'speck', material: 'glow' },
{ id: 'slab', geometry: 'block', material: 'glow', scale: colliderScale },
],
particles: { systems: [{ node: 'sparks', count: 1, seed: 3, speed: 0, size: 0.04, lifetime: 6, emitter: { shape: 'point', position: [0.3, 2, 0.2] }, colliders: ['slab'], ...system }], ...extra },
};
}
function particleCenters(scene, count = 1) {
const positions = scene.parts.find(part => part.name === 'sparks').geometry.positions;
const perParticle = positions.length / 3 / count;
return Array.from({ length: count }, (unused, particle) => {
const center = [0, 0, 0];
for (let vertex = 0; vertex < perParticle; vertex++) {
for (let axis = 0; axis < 3; axis++) center[axis] += positions[(particle * perParticle + vertex) * 3 + axis] / perParticle;
}
return center;
});
}
function traceOf(scene, times) {
return times.map(time => {
scene.sampleMotion(time);
return particleCenters(scene)[0];
});
}
const frames = Array.from({ length: 300 }, (unused, frame) => frame / 100);
test('particles bounce off a box: they never pass through it and rise again after the hit', () => {
const scene = createAgentScene(dropRecipe({ bounce: 0.6 }));
const heights = traceOf(scene, frames).map(center => center[1]);
assert.ok(Math.min(...heights) >= SLAB_TOP - 1e-3, `lowest ${Math.min(...heights)} is below the slab top`);
const lowestIndex = heights.indexOf(Math.min(...heights.slice(0, 120)));
const risen = Math.max(...heights.slice(lowestIndex, lowestIndex + 40));
assert.ok(risen > heights[lowestIndex] + 0.2, 'the particle rebounds upward after landing');
assert.ok(risen < 2, 'a bounce with 0.6 restitution does not reach the drop height');
});
test('a bounce keeps its energy ratio: the first apex is about the bounce squared of the drop height', () => {
const scene = createAgentScene(dropRecipe({ bounce: 0.5, friction: 0 }));
const heights = traceOf(scene, Array.from({ length: 220 }, (unused, frame) => frame / 100)).map(center => center[1] - SLAB_TOP);
const firstApex = Math.max(...heights.slice(70, 130));
const dropHeight = 2 - SLAB_TOP;
assert.ok(Math.abs(firstApex / dropHeight - 0.25) < 0.05, `apex ratio ${firstApex / dropHeight}`);
});
test('without bounce a particle sticks where it lands, on the top face', () => {
const scene = createAgentScene(dropRecipe({ bounce: 0 }));
const [early, late] = [1.5, 5].map(time => traceOf(scene, [time])[0]);
assert.ok(Math.abs(early[1] - SLAB_TOP) < 1e-3, `rests at ${early[1]}`);
assert.deepEqual(late, early, 'a stuck particle does not move again');
});
test('a fast particle does not tunnel through a thin collider', () => {
const scene = createAgentScene(dropRecipe({ speed: 300, direction: [0, -1, 0], spread: 0, bounce: 0.2 }, { colliderScale: [4, 0.01, 4] }));
const heights = traceOf(scene, frames).map(center => center[1]);
assert.ok(Math.min(...heights) >= 0.005 - 1e-3, `lowest ${Math.min(...heights)} went through the sheet`);
});
test('friction slows the particle along the surface, and a slow bounce comes to rest', () => {
const slide = { speed: 3, direction: [1, -0.3, 0], spread: 0, bounce: 0.5 };
const slipped = traceOf(createAgentScene(dropRecipe({ ...slide, friction: 0 })), [1.2])[0];
const gripped = traceOf(createAgentScene(dropRecipe({ ...slide, friction: 0.9 })), [1.2])[0];
assert.ok(gripped[0] < slipped[0] - 0.3, `friction travel ${gripped[0]} against ${slipped[0]}`);
const settled = createAgentScene(dropRecipe({ bounce: 0.4, friction: 0.5 }));
const [late, later] = traceOf(settled, [4, 5.5]);
assert.deepEqual(later, late, 'the particle has come to rest');
assert.ok(Math.abs(late[1] - SLAB_TOP) < 1e-2);
});
test('the same seed gives the same frames, forward, after seeking back and in a second scene', () => {
const system = { count: 40, seed: 11, speed: [1, 4], spread: 60, bounce: 0.6, friction: 0.3, spin: [-300, 300], color: [[1, 0.8, 0.2], [0.8, 0.05, 0]], alpha: [1, 0], lifetime: [2, 5], emitter: { shape: 'sphere', radius: 0.3, position: [0, 1.5, 0] } };
const scene = createAgentScene(dropRecipe(system));
const bytesAt = time => {
scene.sampleMotion(time);
const geometry = scene.parts.find(part => part.name === 'sparks').geometry;
return [Array.from(geometry.positions), Array.from(geometry.normals), Array.from(geometry.colors)];
};
const first = bytesAt(1.37);
const later = bytesAt(3.1);
assert.notDeepEqual(later[0], first[0]);
assert.deepEqual(bytesAt(1.37), first, 'seeking back repeats the frame');
bytesAt(5.5);
assert.deepEqual(bytesAt(3.1), later, 'seeking back from the end repeats a later frame');
const fresh = createAgentScene(dropRecipe(system));
fresh.sampleMotion(3.1);
const direct = fresh.parts.find(part => part.name === 'sparks').geometry;
assert.deepEqual(Array.from(direct.positions), later[0], 'a jump straight to a time matches walking there');
});
test('spin turns each particle in place and never changes where it flies', () => {
const plain = createAgentScene(dropRecipe({ count: 5, bounce: 0.5, speed: 2, spread: 40 }));
const spinning = createAgentScene(dropRecipe({ count: 5, bounce: 0.5, speed: 2, spread: 40, spin: [200, 400] }));
plain.sampleMotion(1.1);
spinning.sampleMotion(1.1);
particleCenters(plain, 5).forEach((center, index) => {
center.forEach((value, axis) => assert.ok(Math.abs(value - particleCenters(spinning, 5)[index][axis]) < 1e-5));
});
const spunVertices = spinning.parts.find(part => part.name === 'sparks').geometry;
assert.notDeepEqual(Array.from(spunVertices.positions), Array.from(plain.parts.find(part => part.name === 'sparks').geometry.positions));
for (let offset = 0; offset < spunVertices.normals.length; offset += 3) {
assert.ok(Math.abs(Math.hypot(...spunVertices.normals.slice(offset, offset + 3)) - 1) < 1e-4, 'rotated normals stay unit length');
}
});
test('color and alpha follow the life: start, middle, end', () => {
const scene = createAgentScene(dropRecipe({ lifetime: 4, color: [[1, 0.5, 0], [0, 0.5, 1]], alpha: [1, 0] }));
const colorAt = time => {
scene.sampleMotion(time);
return Array.from(scene.parts.find(part => part.name === 'sparks').geometry.colors.slice(0, 3));
};
// Alpha multiplies the color: at 80 percent of the life the color is [0.2, 0.5, 0.8] and alpha 0.2.
assert.deepEqual(colorAt(0).map(value => Number(value.toFixed(4))), [1, 0.5, 0]);
assert.deepEqual(colorAt(2).map(value => Number(value.toFixed(4))), [0.25, 0.25, 0.25]);
assert.deepEqual(colorAt(3.2).map(value => Number(value.toFixed(4))), [0.04, 0.1, 0.16]);
});
test('a system without color or alpha writes no vertex colors', () => {
const scene = createAgentScene(dropRecipe({ bounce: 0.5 }));
scene.sampleMotion(1);
assert.equal(scene.parts.find(part => part.name === 'sparks').geometry.colors, undefined);
});
test('collision input is validated and the capabilities describe it', () => {
const rejects = (system, pattern) => assert.throws(() => createAgentScene(dropRecipe(system)), pattern);
rejects({ bounce: 1.5 }, /bounce/);
rejects({ friction: -1 }, /friction/);
rejects({ colliders: ['ghost'] }, /particles\.systems\[0\]\.colliders\[0\]: got "ghost"; expected the ID of a node in the recipe/);
rejects({ colliders: ['sparks'] }, /particles\.systems\[0\]\.colliders: got \["sparks"\]; expected node IDs other than the system/);
rejects({ colliders: 'slab' }, /colliders/);
rejects({ alpha: [0, 2] }, /alpha/);
rejects({ alpha: 'clear' }, /alpha/);
rejects({ color: [1, 1, 1] }, /vector|3 numbers|color/i);
rejects({ color: [[1, 1, 1]] }, /color/);
rejects({ spin: 'fast' }, /spin/);
const recipe = dropRecipe({});
recipe.particles.systems.push({ node: 'slab', colliders: ['slab'] });
assert.throws(() => createAgentScene(recipe));
assert.match(AGENT_SCENE_CAPABILITIES.particles.collision, /colliders/);
assert.doesNotMatch(AGENT_SCENE_CAPABILITIES.particles.notes, /No collision/);
});
test('a collider system node of another system and too many triangles are refused', () => {
const recipe = dropRecipe({});
recipe.nodes.push({ id: 'dust', geometry: 'speck', material: 'glow' });
recipe.particles.systems.push({ node: 'dust', count: 1, colliders: ['sparks'] });
assert.throws(() => createAgentScene(recipe), /particle system node/);
const dense = dropRecipe({});
dense.geometries.push({ id: 'ball', type: 'sphere', segments: 64 });
dense.nodes[1].geometry = 'ball';
assert.throws(() => createAgentScene(dense), /triangles/);
});
test('the collision surface reports the nearest face and skips meshes the path cannot reach', () => {
const quad = (height, size) => ({
positions: Float64Array.from([-size, height, -size, size, height, -size, size, height, size, -size, height, size]),
indices: Uint32Array.from([0, 2, 1, 0, 3, 2]),
});
const surface = createCollisionSurface([quad(0, 1), quad(5, 1), quad(0, 0.1)]);
assert.equal(surface.triangleCount, 6);
const contact = { fraction: Infinity, normal: [0, 0, 0], onFloor: false };
assert.equal(findFirstCollision(surface, [0.5, 3, 0.5], [0.5, -1, 0.5], contact), true);
assert.ok(Math.abs(contact.fraction - 0.75) < 1e-12 && contact.normal[1] === 1, 'hits the quad at y 0 from above');
contact.fraction = Infinity;
assert.equal(findFirstCollision(surface, [0.5, 4, 0.5], [0.5, 3, 0.5], contact), false, 'a path between the two layers');
contact.fraction = Infinity;
assert.equal(findFirstCollision(surface, [9, 3, 9], [9, -1, 9], contact), false, 'a path far to the side');
contact.fraction = Infinity;
assert.equal(findFirstCollision(surface, [0.5, 1, 0.5], [1.5, 1, 0.5], contact), false, 'a path parallel to the faces');
assert.equal(findFirstCollision(surface, [0.5, -1, 0.5], [0.5, 3, 0.5], contact), true);
assert.equal(contact.normal[1], -1, 'the normal faces the side the particle came from');
});
test('a floor bounce needs no collider, and the closed form still serves a free fall', () => {
const forces = { gravity: [0, -9.81, 0], wind: [0, 0, 0], fields: [], drag: 0, floor: 0, bounce: 0.5, friction: 0 };
const settings = { count: 1, seed: 1, emitter: { shape: 'point', position: [0, 2, 0], halfExtents: [0, 0, 0], radius: 0 }, lifetime: [5, 5], speed: [0, 0], direction: [0, 1, 0], spreadRadians: 0, size: [1, 1], forces };
const launches = createParticleLaunches(settings);
assert.ok(launches.track, 'bounce uses the stepped integrator');
const state = { position: [0, 0, 0], scale: 0 };
let apex = 0;
for (let time = 0.7; time < 1.2; time += 0.01) apex = Math.max(apex, particleStateAt(launches, 0, forces, 'constant', time, state).position[1]);
assert.ok(Math.abs(apex / 2 - 0.25) < 0.05, `apex ${apex}`);
const free = createParticleLaunches({ ...settings, forces: { ...forces, bounce: 0 } });
assert.equal(free.track, undefined);
assert.equal(particleStateAt(free, 0, { ...forces, bounce: 0 }, 'constant', 3, state).position[1], 0, 'lands on the floor in closed form');
});
test('stepping from birth every frame stays cheap enough for long lives, and playback continues from the last frame', () => {
const system = { count: 500, seed: 5, speed: [2, 6], spread: 50, bounce: 0.6, friction: 0.2, lifetime: 20, emitter: { shape: 'sphere', radius: 0.5, position: [0, 2, 0] } };
const scene = createAgentScene(dropRecipe(system));
const start = performance.now();
for (let frame = 0; frame <= 120; frame++) scene.sampleMotion(frame / 6);
const playback = performance.now() - start;
const cold = createAgentScene(dropRecipe(system));
const coldStart = performance.now();
cold.sampleMotion(20 - 0.01);
const coldSeek = performance.now() - coldStart;
assert.ok(playback < 20000 && coldSeek < 20000, `playback ${playback.toFixed(0)} ms for 121 frames, cold seek to the end ${coldSeek.toFixed(0)} ms`);
});
test('Coulomb friction stops a slider after about v squared over two mu g, and a settled particle stops turning', () => {
const forces = { gravity: [0, -9.81, 0], wind: [0, 0, 0], fields: [], drag: 0, floor: 0, bounce: 0.3, friction: 0.5 };
const settings = { count: 1, seed: 1, emitter: { shape: 'point', position: [0, 0.0005, 0], halfExtents: [0, 0, 0], radius: 0 }, lifetime: [8, 8], speed: [3, 3], direction: [1, 0, 0], spreadRadians: 0, size: [1, 1], spin: [400, 400], forces };
const launches = createParticleLaunches(settings);
const state = { position: [0, 0, 0], scale: 0 };
const [early, late] = [3, 6].map(time => {
particleStateAt(launches, 0, forces, 'constant', time, state);
return { x: state.position[0], angle: state.angle };
});
assert.ok(early.x > 0.8 && early.x < 1, `slid ${early.x} m, expected about 0.9`);
assert.deepEqual(late, early, 'the slider is at rest and no longer turns');
});
test('the default bounce with colliders reads as debris', () => {
const heights = traceOf(createAgentScene(dropRecipe({})), frames).map(center => center[1]);
const rise = Math.max(...heights.slice(65, 100)) - SLAB_TOP;
assert.ok(rise > 0 && rise < 0.3, `default bounce rebounds ${rise} m from a 1.9 m drop`);
});
test('a path through a vertex or an edge midpoint of a scaled mesh always hits it', () => {
const geometry = icoSphere(2);
const positions = Float64Array.from(geometry.positions, value => value * 0.37);
const surface = createCollisionSurface([{ positions, indices: geometry.indices }]);
const drops = [];
for (let vertex = 0; vertex < positions.length; vertex += 3) drops.push([positions[vertex], positions[vertex + 2]]);
for (let corner = 0; corner < geometry.indices.length; corner += 3) {
for (const [first, second] of [[0, 1], [1, 2], [2, 0]]) {
const start = geometry.indices[corner + first] * 3;
const end = geometry.indices[corner + second] * 3;
drops.push([(positions[start] + positions[end]) / 2, (positions[start + 2] + positions[end + 2]) / 2]);
}
}
const leaks = drops.filter(([x, z]) => !findFirstCollision(surface, [x, 6, z], [x, -6, z], { fraction: Infinity, normal: [0, 1, 0], onFloor: false }));
assert.equal(leaks.length, 0, `${leaks.length} of ${drops.length} drops fell through the mesh`);
});