Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.js
new file mode 100644
index 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)`);
+});