3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// The two soft body films of docs/physics.md: a jelly cube landing and a flag lowered into folds on itself.
// Each is one recipe. The film test and the preview script both bake that recipe, so what is measured is what is rendered.
import { createHash } from 'node:crypto';
import '../tests/support/load-agent-scene-modules.mjs';
import { createAgentScene } from '../src/agent-scene.js';
export const FILM_FRAMES_PER_SECOND = 60;
const FLOOR_THICKNESS = 0.01;
const GROUND_NODE = { id: 'ground', geometry: 'floor', material: 'stone', translation: [0, -0.5, 0], scale: [8, 1, 8] };
const CAMERA = { fov: 34 };
function baseRecipe({ geometries, materials, nodes, motion, cloth, camera, floorColor = [0.55, 0.55, 0.58], environment }) {
return {
format: 'crucible.scene', schemaVersion: 1,
geometries: [...geometries, { id: 'floor', type: 'box', bevel: 0 }],
materials: [...materials, { id: 'stone', color: floorColor }],
nodes: [...nodes, GROUND_NODE],
camera: { ...CAMERA, ...camera },
motion,
cloth,
...(environment ? { environment } : {}),
};
}
/** A rounded jelly cube, 0.5 m across, dropped from 1.95 m above the floor. */
export function jellyCubeRecipe() {
return baseRecipe({
geometries: [{ id: 'jelly', type: 'box', bevel: 0.12, subdivisions: 3 }],
materials: [{ id: 'gel', color: [0.25, 0.85, 0.45] }],
nodes: [
{ id: 'cube', geometry: 'jelly', material: 'gel', translation: [0, 2.2, 0], scale: [0.5, 0.5, 0.5] },
{ id: 'clock' },
],
// A recipe needs authored motion before a render job accepts a start time; the cloth bake reads the same clock.
motion: { duration: 2, loop: false, tracks: [{ kind: 'node', id: 'clock', property: 'translation', interpolation: 'LINEAR', keyframes: [{ time: 0, value: [0, 0, 0] }, { time: 2, value: [0, 0, 0] }] }] },
camera: { eye: [0.45, 0.22, 1.75], target: [0, 0.3, 0] },
cloth: {
duration: 2,
sheets: [{ node: 'cube', softBody: { shape: 0.15, pressure: 1 }, stiffness: 0.9, bend: 0, damping: 2 }],
colliders: [{ node: 'ground', shape: 'box' }],
},
});
}
// The pole's path: a wide whip from side to side on the way down so the sheet billows and ripples, a landing at 0.8 s, then a zig-zag drag
// 2 m across the floor that pulls the cloth into a thin crumpled layer.
const POLE_KEYFRAMES = [
{ time: 0, value: [0, 2.0, 0] },
{ time: 0.15, value: [0.5, 1.85, 0.4] },
{ time: 0.3, value: [-0.5, 1.4, -0.4] },
{ time: 0.45, value: [0.4, 0.8, 0.5] },
{ time: 0.6, value: [-0.2, 0.3, -0.2] },
{ time: 0.8, value: [0, 0.012, 0] },
{ time: 1.1, value: [0.3, 0.012, 0.7] },
{ time: 1.5, value: [-0.3, 0.012, 1.1] },
{ time: 1.9, value: [0.3, 0.012, 1.5] },
{ time: 2.4, value: [0, 0.012, 1.9] },
{ time: 3, value: [0, 0.012, 2.0] },
];
export const FLAG_FILM_SECONDS = 3;
// The fine flag: a 64 by 64 grid for 4 s with dihedral bending, so the cloth folds in many soft ripples instead of one crease.
export const FINE_FLAG_FILM_SECONDS = 4;
const FINE_FLAG_SEGMENTS = 63;
const FINE_FLAG_BEND = 0.15;
// Creases stay: past 0.3 rad of bending the rest angle follows the cloth by a fifth of the excess a substep, so folds made in the fall are kept
// (without it the sheet pulls its folds flat again and ends as a smooth layer). Damping 3 calms the landing. Static friction holds a layer
// where it lies on the floor, and the pole lets go as it lands, so no corner stays pinned up like a tent and the heap is left to rest.
const FINE_FLAG_CREASE = { bendYield: 0.3, bendSet: 0.2, damping: 3, friction: 0.6, staticFriction: 1 };
const FINE_FLAG_LANDING_SECONDS = 0.8;
// The camera frames the fall from afar, then moves in over the landing so the heap fills the picture.
const FINE_FLAG_CAMERA_TRACKS = [
{ kind: 'camera', property: 'eye', interpolation: 'SMOOTH', keyframes: [{ time: 0, value: [1.5, 1.2, 3.6] }, { time: 0.7, value: [1.5, 1.2, 3.6] }, { time: 1.3, value: [0.85, 0.75, 1.55] }, { time: 4, value: [0.85, 0.75, 1.55] }] },
{ kind: 'camera', property: 'target', interpolation: 'SMOOTH', keyframes: [{ time: 0, value: [0, 0.9, 0] }, { time: 0.7, value: [0, 0.9, 0] }, { time: 1.3, value: [0, 0.03, 0] }, { time: 4, value: [0, 0.03, 0] }] },
];
// A deep red and cream striped cloth on a mid grey floor, lit by a grazing key from the side so every fold casts a shadow and bends the stripes.
const FLAG_LOOK = { lightDirection: [-0.9, 0.3, 0.45], keyIntensity: 1.5, fillIntensity: 0.12, ambientIntensity: 0.15 };
const FLAG_STRIPES = { type: 'graph', mapping: 'uv', resolution: 256, graph: { color: { layer: { base: [0.35, 0.015, 0.04], top: [0.85, 0.78, 0.62], mask: { wave: { frequency: 8, direction: 'v', shape: 'saw' } }, edge: 0.5, softness: 0.02 } } } };
/**
* A flag hung from a pole by its top edge. The pole swings from side to side while it falls, so the sheet ripples, lands on the floor and
* is let go there, so the cloth settles as a crumpled heap that stays put (fine only; the 38 by 38 film drags it into a ridge). The sheet sets thickness 3.5 mm, which also sets the self collision radius,
* so layers stack 6 mm apart instead of 3.7 cm.
*/
export function foldingFlagRecipe({ selfCollision = true, fine = false } = {}) {
const seconds = fine ? FINE_FLAG_FILM_SECONDS : FLAG_FILM_SECONDS;
const landing = POLE_KEYFRAMES.findIndex(keyframe => keyframe.time === FINE_FLAG_LANDING_SECONDS);
const keyframes = fine ? [...POLE_KEYFRAMES.slice(0, landing + 1), { time: seconds, value: POLE_KEYFRAMES[landing].value }] : POLE_KEYFRAMES;
const bending = fine ? { bendModel: 'dihedral', bend: FINE_FLAG_BEND, ...FINE_FLAG_CREASE } : { bend: 0.0002 };
return baseRecipe({
geometries: [{ id: 'flag', type: 'grid', segments: fine ? FINE_FLAG_SEGMENTS : 38 }],
materials: [{ id: 'fabric', color: [1, 1, 1], doubleSided: true, pattern: FLAG_STRIPES }],
nodes: [
{ id: 'flag', geometry: 'flag', material: 'fabric', translation: [0, 1.5, 0], scale: [1.6, 1, 1] },
{ id: 'pole', translation: [0, 2.0, 0] },
],
motion: { duration: seconds, loop: false, tracks: [{ kind: 'node', id: 'pole', property: 'translation', interpolation: 'LINEAR', keyframes }, ...(fine ? FINE_FLAG_CAMERA_TRACKS : [])] },
camera: fine ? { eye: [1.5, 1.2, 3.6], target: [0, 0.9, 0], fov: 42 } : { eye: [2.2, 1.7, 5.4], target: [0, 0.6, 0.8] },
floorColor: [0.28, 0.28, 0.3],
environment: FLAG_LOOK,
cloth: {
duration: seconds,
sheets: [{ node: 'flag', pin: ['topLeft', 'topRight'], pinTo: fine ? { node: 'pole', releaseAt: FINE_FLAG_LANDING_SECONDS } : { node: 'pole' }, selfCollision, stiffness: 0.6, damping: 1.5, friction: 0.4, ...bending, thickness: 0.002 }],
colliders: [{ node: 'ground', shape: 'box' }],
},
});
}
/**
* How far the sheet's triangles face different ways: 0 for a flat sheet, toward 1 as the normals scatter. A triangle's normal is
* taken up to its sign (a cloth has two faces), summed, and the length of that sum over the triangle count is taken from 1.
*/
export function normalSpread(vertices, indices) {
let sumX = 0;
let sumY = 0;
let sumZ = 0;
let counted = 0;
for (let corner = 0; corner < indices.length; corner += 3) {
const a = indices[corner] * 3;
const b = indices[corner + 1] * 3;
const thirdVertexOffset = indices[corner + 2] * 3;
const edgeOne = [vertices[b] - vertices[a], vertices[b + 1] - vertices[a + 1], vertices[b + 2] - vertices[a + 2]];
const edgeTwo = [vertices[thirdVertexOffset] - vertices[a], vertices[thirdVertexOffset + 1] - vertices[a + 1], vertices[thirdVertexOffset + 2] - vertices[a + 2]];
let normalX = edgeOne[1] * edgeTwo[2] - edgeOne[2] * edgeTwo[1];
let normalY = edgeOne[2] * edgeTwo[0] - edgeOne[0] * edgeTwo[2];
let normalZ = edgeOne[0] * edgeTwo[1] - edgeOne[1] * edgeTwo[0];
const length = Math.hypot(normalX, normalY, normalZ);
if (length < 1e-12) continue;
const sign = normalZ < 0 ? -1 / length : 1 / length;
normalX *= sign;
normalY *= sign;
normalZ *= sign;
sumX += normalX;
sumY += normalY;
sumZ += normalZ;
counted++;
}
return counted === 0 ? 0 : 1 - Math.hypot(sumX, sumY, sumZ) / counted;
}
/** The cloth node's vertices at `time` in world space (the recipe nodes use translation and scale only), as a copy. */
export function clothVertices(scene, node, time) {
scene.sampleMotion(time);
const local = scene.parts.find(part => part.name === node.id).geometry.positions;
const world = new Float32Array(local.length);
for (let index = 0; index < local.length; index++) {
world[index] = local[index] * node.scale[index % 3] + node.translation[index % 3];
}
return world;
}
/**
* Bakes a recipe and samples every frame. Returns the world vertex buffer of each frame, a hash of each frame, and
* the milliseconds of the whole bake (scene creation plus the first sample) and of every later sample, and the triangle indices of the
* cloth node so a caller does not bake the recipe again just to read them.
*/
export function recordFilm(recipe, nodeId, frameCount) {
const node = recipe.nodes.find(candidate => candidate.id === nodeId);
const started = performance.now();
const scene = createAgentScene(recipe);
const frames = [clothVertices(scene, node, 0)];
const bakeMilliseconds = performance.now() - started;
const sampleMilliseconds = [];
for (let frame = 1; frame < frameCount; frame++) {
const sampleStarted = performance.now();
frames.push(clothVertices(scene, node, frame / FILM_FRAMES_PER_SECOND));
sampleMilliseconds.push(performance.now() - sampleStarted);
}
const hashes = frames.map(frame => createHash('sha256').update(Buffer.from(frame.buffer)).digest('hex'));
const indices = scene.parts.find(part => part.name === node.id).geometry.indices;
return { frames, hashes, bakeMilliseconds, sampleMilliseconds, indices };
}
/** Lowest, highest and extent of a vertex buffer along one axis (0 x, 1 y, 2 z). */
export function axisRange(vertices, axis) {
let low = Infinity;
let high = -Infinity;
for (let index = axis; index < vertices.length; index += 3) {
low = Math.min(low, vertices[index]);
high = Math.max(high, vertices[index]);
}
return { low, high, extent: high - low };
}
/** The frame where the body first rests on the floor, with the dent measured from there on. */
export function measureLanding(frames, restHeight) {
const lowest = frame => axisRange(frame, 1).low;
const contact = frames.findIndex(frame => lowest(frame) <= FLOOR_THICKNESS + 1e-3);
if (contact === -1) {
throw new Error(`measureLanding: the body never reached the floor within ${frames.length} frames; pass a longer film or lower the drop.`);
}
let deepest = contact;
let deepestHeight = Infinity;
for (let frame = contact; frame < frames.length; frame++) {
const height = axisRange(frames[frame], 1).extent;
if (height < deepestHeight) {
deepestHeight = height;
deepest = frame;
}
}
return { contact, maxDentFrame: deepest, maxDentDepth: restHeight - deepestHeight, restHeight };
}
/**
* How often the sheet's height turns from rising to falling (or back) along the middle row and the middle column of its grid, ignoring
* wiggles under `deadband` metres: the number of folds a line across the cloth crosses.
*/
export function foldCrossings(vertices, side, deadband = 0.0005) {
const countAlong = line => {
let crossings = 0;
let direction = 0;
let anchor = vertices[line[0] * 3 + 1];
for (const vertex of line) {
const height = vertices[vertex * 3 + 1];
if (direction >= 0 && height < anchor - deadband) {
if (direction === 1) crossings++;
direction = -1;
anchor = height;
} else if (direction <= 0 && height > anchor + deadband) {
if (direction === -1) crossings++;
direction = 1;
anchor = height;
} else if ((direction >= 0 && height > anchor) || (direction <= 0 && height < anchor)) {
anchor = height;
}
}
return crossings;
};
const middle = Math.floor(side / 2);
return {
row: countAlong(Array.from({ length: side }, (_, column) => middle * side + column)),
column: countAlong(Array.from({ length: side }, (_, row) => row * side + middle)),
};
}
/** Smallest distance between two vertices that no triangle edge joins: the closest two layers of a fold come. */
export function unjoinedMinimumDistance(vertices, indices) {
const count = vertices.length / 3;
const joined = new Set();
for (let corner = 0; corner < indices.length; corner += 3) {
for (let side = 0; side < 3; side++) {
const first = indices[corner + side];
const second = indices[corner + (side + 1) % 3];
joined.add(Math.min(first, second) * count + Math.max(first, second));
}
}
let minimum = Infinity;
for (let first = 0; first < count; first++) {
for (let second = first + 1; second < count; second++) {
if (joined.has(first * count + second)) continue;
const distance = Math.hypot(vertices[first * 3] - vertices[second * 3], vertices[first * 3 + 1] - vertices[second * 3 + 1], vertices[first * 3 + 2] - vertices[second * 3 + 2]);
minimum = Math.min(minimum, distance);
}
}
return minimum;
}