3D engine that AI agents drive
Soft body films: jelly cube landing and folding flag as deterministic film tests with frame times (part of #696)
Nguyen Xuan An660e9808d52e
diff --git a/docs/physics.md b/docs/physics.mdindex 061eb0b6..f50092fc 100644--- a/docs/physics.md+++ b/docs/physics.md@@ -440,6 +440,14 @@ A recipe `cloth` section records deformable sheets with a position-based solver- A seek replaces the sheet's part, so the renderer sees a topology change (`topologyRevision`); the MCP preview uses `replaceParts` and `scene_look` with `motionTime` repeats the same PNG bytes (`npm run smoke:agent-cloth`).- `scene_inspect` returns a `cloth` report: particles, triangles, pinned count and the final bounds of each sheet.+Soft body films (`scripts/soft-body-film.mjs`, `tests/soft-body-film.test.js`): a jelly cube landing and a flag lowered into folds on itself, each one recipe that the test bakes twice and the preview script renders.++- Jelly cube: a rounded box 0.5 m across (384 particles) dropped from 1.95 m, `softBody { shape: 0.15, pressure: 1 }`. It first rests on the floor at frame 48 (0.8 s) and is dented 0.0503 m (10 percent of its height) at frame 49, one step later, while its width grows from 0.5 m to 0.547 m; the frame before contact has no dent.+- Flag: a 24 by 24 grid, 1 m tall, hung by its top edge from a pole (`pinTo`) that drops 2.35 m, so the cloth piles on the floor with `selfCollision: true`. The pile is 0.547 m tall. The closest pair of particles not joined by an edge ends 7.9 mm apart; the same film without self collision ends 0.5 mm apart (layers merged).+- Both films bake to the same bytes in every frame across two runs; the test compares every frame's vertex buffer.+- Frame time, in milliseconds per solver step (the bake is one call, so this is its total over the steps, on a machine shared with other sessions, so read it as a range): jelly 2.5 to 6.8 ms a step over 120 steps, flag 20 to 37 ms a step over 150 steps (5.5 ms a step without self collision, 625 particles). Sampling a recorded frame for playback costs about 1 to 1.5 ms.+- `node scripts/render-soft-body-film.mjs <folder>` (run it through gpu-lock) writes a 480 by 270 preview MP4 of each film, stills at contact and at the deepest dent, and `soft-body-film.json` with the same numbers. It needs `npm run build:lib` first. No default changes.+Blender comparison (`scripts/blender-cloth.py`, Blender 5.2.2, default stiffness, mass set from the same kg/m2; `tests/cloth-blender.test.js`):| Case | Result |diff --git a/scripts/render-soft-body-film.mjs b/scripts/render-soft-body-film.mjsnew file mode 100644index 00000000..da5d96d7--- /dev/null+++ b/scripts/render-soft-body-film.mjs@@ -0,0 +1,104 @@+// Renders a low-resolution preview MP4 of each soft body film, stills at contact and at the deepest dent, and one JSON of+// the measured numbers. Usage: node scripts/render-soft-body-film.mjs <output directory>+// Run it through gpu-lock on a shared machine. It needs `npm run build:lib` first.+import { copyFile, mkdir, writeFile } from 'node:fs/promises';+import { existsSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';+import { setTimeout as delay } from 'node:timers/promises';+import { Client } from '@modelcontextprotocol/client';+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';+import { FILM_FRAMES_PER_SECOND, axisRange, foldingFlagRecipe, jellyCubeRecipe, measureLanding, recordFilm } from './soft-body-film.mjs';++const PREVIEW = { width: 480, height: 270, fps: 30 };+const serverEntry = new URL('../bin/67js-mcp.mjs', import.meta.url).pathname.replace(/^\/(\w:)/, '$1');++async function renderJob(call, sessionId, settings) {+ const submitted = await call('scene_render_submit', { sessionId, expectedRevision: 0, settings });+ if (submitted.isError) throw new Error(submitted.content?.[0]?.text);+ const { jobId } = submitted.structuredContent;+ for (;;) {+ const record = (await call('scene_render_status', { jobId })).structuredContent;+ if (record.state === 'completed') break;+ if (['cancelled', 'failed'].includes(record.state)) throw new Error(`Render job ${record.state}: ${record.error}`);+ await delay(250);+ }+ const result = (await call('scene_render_result', { jobId })).structuredContent;+ return { jobId, artifact: result.artifacts[0].path, metrics: result.metrics };+}++async function renderFilm(call, outputDirectory, { name, recipe, nodeId, frameCount, stillTimes, videoSeconds }) {+ const createResult = await call('scene_create', { recipe });+ if (createResult.isError) throw new Error(createResult.content?.[0]?.text);+ const created = createResult.structuredContent;+ const files = {};+ for (const [label, time] of Object.entries(stillTimes)) {+ const { artifact } = await renderJob(call, created.sessionId, { kind: 'image', width: PREVIEW.width, height: PREVIEW.height, motion: { start: time } });+ files[label] = `${name}-${label}.png`;+ await copyFile(artifact, join(outputDirectory, files[label]));+ }+ const video = await renderJob(call, created.sessionId, { kind: 'video', ...PREVIEW, duration: videoSeconds, motion: { start: 0 } });+ files.video = `${name}.mp4`;+ await copyFile(video.artifact, join(outputDirectory, files.video));+ const disposed = await call('scene_dispose', { sessionId: created.sessionId });+ if (disposed.isError) throw new Error(disposed.content?.[0]?.text);+ return { files, frameCount, nodeId };+}++function filmNumbers(film, nodeId, frameCount) {+ const record = recordFilm(film, nodeId, frameCount);+ const milliseconds = value => Number(value.toFixed(2));+ return {+ record,+ frameTimes: {+ stepsPerSecond: FILM_FRAMES_PER_SECOND,+ bakeMilliseconds: milliseconds(record.bakeMilliseconds),+ millisecondsPerStep: milliseconds(record.bakeMilliseconds / frameCount),+ playbackSampleMilliseconds: { mean: milliseconds(record.sampleMilliseconds.reduce((a, b) => a + b, 0) / record.sampleMilliseconds.length), max: milliseconds(Math.max(...record.sampleMilliseconds)) },+ },+ };+}++async function main() {+ if (!existsSync(new URL('../build/mcp/server.mjs', import.meta.url))) throw new Error('Run npm run build:lib first: the MCP server is not built.');+ const outputDirectory = resolve(process.argv[2] ?? '');+ if (!process.argv[2]) throw new Error('Pass the output directory: node scripts/render-soft-body-film.mjs <directory>');+ await mkdir(outputDirectory, { recursive: true });++ const jellyFrames = 120;+ const flagFrames = 150;+ const jelly = filmNumbers(jellyCubeRecipe(), 'cube', jellyFrames);+ const landing = measureLanding(jelly.record.frames, axisRange(jelly.record.frames[0], 1).extent);+ const flag = filmNumbers(foldingFlagRecipe(), 'flag', flagFrames);+ const flagHash = flag.record.hashes[flagFrames - 1];++ const jobsDirectory = join(tmpdir(), `67js-soft-body-film-${process.pid}`);+ const transport = new StdioClientTransport({ command: process.execPath, args: [serverEntry, '--jobs', jobsDirectory], stderr: 'ignore' });+ const client = new Client({ name: 'soft-body-film', version: '1.0.0' });+ await client.connect(transport);+ try {+ const call = (name, toolArguments) => client.callTool({ name, arguments: toolArguments }, { timeout: 300000 });+ const jellyFiles = await renderFilm(call, outputDirectory, {+ name: 'jelly-cube', recipe: jellyCubeRecipe(), nodeId: 'cube', frameCount: jellyFrames, videoSeconds: jellyFrames / FILM_FRAMES_PER_SECOND,+ stillTimes: { contact: landing.contact / FILM_FRAMES_PER_SECOND, 'max-dent': landing.maxDentFrame / FILM_FRAMES_PER_SECOND },+ });+ const flagFiles = await renderFilm(call, outputDirectory, {+ name: 'folding-flag', recipe: foldingFlagRecipe(), nodeId: 'flag', frameCount: flagFrames, videoSeconds: flagFrames / FILM_FRAMES_PER_SECOND,+ stillTimes: { folded: (flagFrames - 1) / FILM_FRAMES_PER_SECOND },+ });+ const summary = {+ preview: PREVIEW,+ jellyCube: { steps: jellyFrames, contactFrame: landing.contact, contactSeconds: landing.contact / FILM_FRAMES_PER_SECOND, maxDentFrame: landing.maxDentFrame, maxDentDepthMeters: Number(landing.maxDentDepth.toFixed(4)), restHeightMeters: Number(landing.restHeight.toFixed(4)), frameTimes: jelly.frameTimes, files: jellyFiles.files },+ foldingFlag: { steps: flagFrames, finalFrameSha256: flagHash, frameTimes: flag.frameTimes, files: flagFiles.files },+ };+ await writeFile(join(outputDirectory, 'soft-body-film.json'), `${JSON.stringify(summary, null, 2)}\n`);+ console.log(JSON.stringify(summary, null, 2));+ } finally {+ await client.close();+ }+}++main().catch(error => {+ console.error(error.message);+ process.exitCode = 1;+});diff --git a/scripts/soft-body-film.mjs b/scripts/soft-body-film.mjsnew file mode 100644index 00000000..db814fcd--- /dev/null+++ b/scripts/soft-body-film.mjs@@ -0,0 +1,119 @@+// 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 }) {+ return {+ format: '67js.scene', schemaVersion: 1,+ geometries: [...geometries, { id: 'floor', type: 'box', bevel: 0 }],+ materials: [...materials, { id: 'stone', color: [0.55, 0.55, 0.58] }],+ nodes: [...nodes, GROUND_NODE],+ camera: { ...CAMERA, ...camera },+ motion,+ cloth,+ };+}++/** 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: [1.2, 0.5, 1.7], target: [0, 0.35, 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' }],+ },+ });+}++/** A flag hung from a pole by its top edge; the pole drops 2.35 m so the cloth piles into folds on the floor. */+export function foldingFlagRecipe({ selfCollision = true } = {}) {+ return baseRecipe({+ geometries: [{ id: 'flag', type: 'grid', segments: 24 }],+ materials: [{ id: 'fabric', color: [0.9, 0.2, 0.2], doubleSided: true }],+ nodes: [+ { id: 'flag', geometry: 'flag', material: 'fabric', translation: [0, 2.1, 0], scale: [1.6, 1, 1] },+ { id: 'pole', translation: [0, 2.6, 0] },+ ],+ motion: { duration: 3, loop: false, tracks: [{ kind: 'node', id: 'pole', property: 'translation', interpolation: 'LINEAR', keyframes: [{ time: 0, value: [0, 2.6, 0] }, { time: 0.3, value: [0, 2.6, 0] }, { time: 1.6, value: [0, 0.25, 0] }, { time: 3, value: [0, 0.25, 0] }] }] },+ camera: { eye: [0.4, 1.4, 4.2], target: [0, 1.1, 0] },+ cloth: {+ duration: 3,+ sheets: [{ node: 'flag', pin: ['top'], pinTo: { node: 'pole' }, selfCollision, stiffness: 0.9, bend: 0.2, damping: 1 }],+ colliders: [{ node: 'ground', shape: 'box' }],+ },+ });+}++/** 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.+ */+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'));+ return { frames, hashes, bakeMilliseconds, sampleMilliseconds };+}++/** 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);+ 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 };+}diff --git a/tests/soft-body-film.test.js b/tests/soft-body-film.test.jsnew file mode 100644index 00000000..52b4fbcb--- /dev/null+++ b/tests/soft-body-film.test.js@@ -0,0 +1,74 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { createAgentScene } from '../src/agent-scene.js';+import { FILM_FRAMES_PER_SECOND, axisRange, foldingFlagRecipe, jellyCubeRecipe, measureLanding, recordFilm } from '../scripts/soft-body-film.mjs';++// Film tests for #696: each film is one recipe baked twice. The frames must match byte for byte, and the numbers a viewer+// would see (the landing, the dent, the layers of the fold) are measured from the baked vertices, not read off a picture.+const JELLY_FRAMES = 120;+const FLAG_FRAMES = 150;+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;+ minimum = Math.min(minimum, Math.hypot(vertices[first * 3] - vertices[second * 3], vertices[first * 3 + 1] - vertices[second * 3 + 1], vertices[first * 3 + 2] - vertices[second * 3 + 2]));+ }+ }+ return minimum;+}++function milliseconds(value) {+ return Number(value.toFixed(2));+}++test('a jelly cube landing is byte-identical across two bakes and dents on contact', context => {+ const first = recordFilm(jellyCubeRecipe(), 'cube', JELLY_FRAMES);+ const second = recordFilm(jellyCubeRecipe(), 'cube', JELLY_FRAMES);+ assert.deepEqual(first.hashes, second.hashes, 'two bakes of the same recipe give the same bytes in every frame');+ for (let frame = 0; frame < JELLY_FRAMES; frame++) assert.ok(Buffer.from(first.frames[frame].buffer).equals(Buffer.from(second.frames[frame].buffer)));++ const restHeight = axisRange(first.frames[0], 1).extent;+ const landing = measureLanding(first.frames, restHeight);+ assert.ok(landing.contact > 40 && landing.contact < 55, `free fall from 1.95 m reaches the floor near frame 48, got ${landing.contact}`);+ assert.ok(axisRange(first.frames[landing.contact - 1], 1).extent > restHeight * 0.999, 'the cube is not dented in the frame before contact');+ assert.ok(landing.maxDentFrame - landing.contact <= 4, `the dent is deepest within 4 frames of contact, got ${landing.maxDentFrame - landing.contact}`);+ assert.ok(landing.maxDentDepth > 0.03, `the cube dents ${landing.maxDentDepth} m on landing, more than 3 cm`);+ const widest = axisRange(first.frames[landing.maxDentFrame], 0).extent;+ assert.ok(widest > restHeight * 1.04, `the squashed cube bulges sideways to ${widest} m`);++ const bake = first.bakeMilliseconds;+ context.diagnostic(`jelly cube: contact frame ${landing.contact}, max dent ${landing.maxDentDepth.toFixed(4)} m at frame ${landing.maxDentFrame}`);+ context.diagnostic(`jelly cube: bake ${milliseconds(bake)} ms for ${JELLY_FRAMES} steps (${milliseconds(bake / JELLY_FRAMES)} ms a step, ${FILM_FRAMES_PER_SECOND} steps a second)`);+});++test('a flag lowered into folds is byte-identical across two bakes and keeps its layers apart', context => {+ const first = recordFilm(foldingFlagRecipe(), 'flag', FLAG_FRAMES);+ const second = recordFilm(foldingFlagRecipe(), 'flag', FLAG_FRAMES);+ assert.deepEqual(first.hashes, second.hashes, 'two bakes of the same recipe give the same bytes in every frame');+ const last = FLAG_FRAMES - 1;+ assert.ok(Buffer.from(first.frames[last].buffer).equals(Buffer.from(second.frames[last].buffer)));++ const indices = createAgentScene(foldingFlagRecipe()).parts.find(part => part.name === 'flag').geometry.indices;+ const restHeight = axisRange(first.frames[0], 1).extent;+ const pileHeight = axisRange(first.frames[last], 1).extent;+ assert.ok(pileHeight < restHeight * 0.6, `the flag folds from ${restHeight} m to a pile ${pileHeight} m tall`);+ const without = recordFilm(foldingFlagRecipe({ selfCollision: false }), 'flag', FLAG_FRAMES);+ const gap = unjoinedMinimumDistance(first.frames[last], indices);+ const gapWithout = unjoinedMinimumDistance(without.frames[last], indices);+ assert.ok(gap > gapWithout * 5, `layers stay apart with self collision (${gap} m) and merge without it (${gapWithout} m)`);+ assert.ok(gap > 0.005, `the closest unjoined pair is ${gap} m apart`);++ const bake = first.bakeMilliseconds;+ context.diagnostic(`flag: pile ${pileHeight.toFixed(3)} m from ${restHeight.toFixed(3)} m, closest unjoined pair ${gap.toFixed(4)} m (${gapWithout.toFixed(4)} m without self collision)`);+ context.diagnostic(`flag: bake ${milliseconds(bake)} ms for ${FLAG_FRAMES} steps (${milliseconds(bake / FLAG_FRAMES)} ms a step with self collision, ${milliseconds(without.bakeMilliseconds / FLAG_FRAMES)} ms without)`);+});