3D engine that AI agents drive
Pick three clearly stepped jelly presets, label the preview and keep the soft one fold free (#852)
Nguyen Xuan Anbc0933a28974
diff --git a/docs/physics.md b/docs/physics.mdindex 2a2c2111..3df727a4 100644--- a/docs/physics.md+++ b/docs/physics.md@@ -450,7 +450,17 @@ Jelly feel (`tests/soft-body-bounce.test.js`, measured): the 0.5 m rounded cube| 0.02 | 0.9 | 0.065 m | 0.000 m | 0.093 m | 0.441 m || 0.02 | 0.1 | 0.099 m | 0.000 m | 0.100 m | 0.447 m |-Before `bounce` existed, `shape` and `damping` were the only knobs that changed the rebound, and none gave a controlled one. Lowering `shape` or `stiffness` gives a dent up to 3.8 times deeper (0.026 to 0.099 m), so softness needed no new field. With `damping: 0` and the default shape, `bounce` 1 sends the cube back to 1.85 m of its 1.95 m drop.+Before `bounce` existed, `shape` and `damping` were the only knobs that changed the rebound, and none gave a controlled one. Lowering `shape` or `stiffness` deepens the dent (0.026 to 0.099 m), so softness needed no new field. A very low `shape` has a price: with `shape` 0.02 and `stiffness` 0.1, 132 of the cube's 588 triangles turn inside out in the worst frame and the dent shows ragged, doubled edges. It is a real surface fold, not shading, and `selfCollision`, `bend`, more solver iterations and a gentler volume step do not remove it (measured). Keep `shape` at 0.15 or more for a jelly that has to look clean.++Three presets that step clearly (`JELLY_PRESETS` in `tests/support/jelly-cube.mjs`, previewed by `scripts/render-jelly-bounce.mjs` and labelled by `scripts/label-jelly-bounce.py`; no triangle folds in the test):++| Preset (cube colour in the preview) | `shape` | `stiffness` | `bounce` | Dent | Rebound |+| --- | --- | --- | --- | --- | --- |+| firm (blue) | 1 | 0.9 | 0 | 0.026 m | 0.102 m |+| medium (amber) | 0.3 | 0.2 | 0.6 | 0.042 m | 0.216 m |+| soft (pink) | 0.15 | 0.05 | 1 | 0.052 m | 0.464 m |++With `damping: 0` and the default shape, `bounce` 1 sends the cube back to 1.85 m of its 1.95 m drop.Blender comparison (`scripts/blender-cloth.py`, Blender 5.2.2, default stiffness, mass set from the same kg/m2; `tests/cloth-blender.test.js`):diff --git a/scripts/label-jelly-bounce.py b/scripts/label-jelly-bounce.pynew file mode 100644index 00000000..693316de--- /dev/null+++ b/scripts/label-jelly-bounce.py@@ -0,0 +1,99 @@+"""Labels the jelly bounce preview and builds its contact sheet.++Usage: uv run --no-project --with pillow python scripts/label-jelly-bounce.py <output directory>+Reads jelly-bounce.mp4, the stills and jelly-bounce.json written by render-jelly-bounce.mjs, burns a label under each cube+(its name, named colour and measured dent and rebound), relabels the stills, writes soft-dent-full.png and sheet.jpg+(three columns by two rows of frames with frame numbers and which colour is which cube).+"""+import json+import subprocess+import sys+from pathlib import Path++from PIL import Image, ImageDraw, ImageFont++WIDTH, HEIGHT = 960, 540+COLUMN_CENTERS = {"firm": 239, "medium": 480, "soft": 721}+CHIP_COLORS = {"blue": (38, 115, 242), "amber": (250, 178, 26), "pink": (242, 77, 153)}+FONT_PATH = "C:/Windows/Fonts/segoeuib.ttf"+++def font(size):+ return ImageFont.truetype(FONT_PATH, size)+++def build_overlay(summary):+ overlay = Image.new("RGBA", (WIDTH, HEIGHT), (0, 0, 0, 0))+ draw = ImageDraw.Draw(overlay)+ for cube_id, center in COLUMN_CENTERS.items():+ cube = summary["cubes"][cube_id]+ title = f"{cube_id.upper()}"+ lines = [f"{cube['colorName']} cube", f"dent {cube['dentMeters'] * 100:.1f} cm", f"rebound {cube['reboundMeters'] * 100:.0f} cm"]+ left, right = center - 100, center + 100+ draw.rounded_rectangle([left, 410, right, 516], radius=10, fill=(20, 24, 32, 215))+ draw.ellipse([left + 12, 421, left + 30, 439], fill=CHIP_COLORS[cube["colorName"]] + (255,))+ draw.text((left + 40, 414), title, font=font(26), fill=(255, 255, 255, 255))+ for index, line in enumerate(lines):+ draw.text((left + 14, 446 + index * 22), line, font=font(18), fill=(215, 220, 230, 255))+ return overlay+++def run(command):+ subprocess.run(command, check=True, capture_output=True)+++def main():+ output = Path(sys.argv[1])+ summary = json.loads((output / "jelly-bounce.json").read_text())+ overlay_path = output / "labels-overlay.png"+ overlay = build_overlay(summary)+ overlay.save(overlay_path)+ raw_video = output / "jelly-bounce-raw.mp4"+ labelled_video = output / "jelly-bounce.mp4"+ labelled_video.replace(raw_video)+ run(["ffmpeg", "-y", "-i", str(raw_video), "-i", str(overlay_path), "-filter_complex", "overlay=0:0", "-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", "18", "-r", "60", str(labelled_video)])+ for name in summary["files"].values():+ if name.endswith(".png"):+ still = Image.open(output / name).convert("RGBA")+ still.alpha_composite(overlay)+ still.convert("RGB").save(output / name)+ cubes = summary["cubes"]+ picks = [+ ("falling", 30),+ ("contact", cubes["soft"]["contactStep"]),+ ("deepest dent (soft)", cubes["soft"]["deepestDentStep"]),+ ("firm rebound top", cubes["firm"]["reboundTopStep"]),+ ("soft rebound top", cubes["soft"]["reboundTopStep"]),+ ("end", 149),+ ]+ frames = []+ for label, step in picks:+ frame_path = output / f"sheet-frame-{step}.png"+ run(["ffmpeg", "-y", "-i", str(labelled_video), "-vf", f"select=eq(n\\,{step})", "-vframes", "1", str(frame_path)])+ image = Image.open(frame_path).convert("RGB")+ image.load()+ frames.append((label, step, image))+ if label.startswith("deepest"):+ image.save(output / "soft-dent-full.png")+ frame_path.unlink()+ cell_width, cell_height, header = 640, 360, 96+ sheet = Image.new("RGB", (cell_width * 3, (cell_height + 34) * 2 + header), (18, 20, 26))+ draw = ImageDraw.Draw(sheet)+ draw.text((16, 10), "Jelly bounce, 960x540 60 fps. Same drop from 1.95 m. Frame number = step at 60 per second.", font=font(24), fill=(255, 255, 255))+ key_x = 16+ for cube_id in ("firm", "medium", "soft"):+ cube = cubes[cube_id]+ draw.ellipse([key_x, 54, key_x + 22, 76], fill=CHIP_COLORS[cube["colorName"]])+ text = f"{cube['colorName']} = {cube_id}: shape {cube['shape']}, bounce {cube['bounce']}, stiffness {cube.get('stiffness', 0.9)}"+ draw.text((key_x + 30, 52), text, font=font(20), fill=(230, 232, 238))+ key_x += 30 + int(draw.textlength(text, font=font(20))) + 40+ for index, (label, step, image) in enumerate(frames):+ column, row = index % 3, index // 3+ left, top = column * cell_width, header + row * (cell_height + 34)+ sheet.paste(image.resize((cell_width, cell_height), Image.LANCZOS), (left, top + 34))+ draw.text((left + 10, top + 4), f"frame {step}: {label}", font=font(22), fill=(255, 220, 120))+ sheet.save(output / "sheet.jpg", quality=88)+ print("sheet", output / "sheet.jpg")+++main()diff --git a/scripts/render-jelly-bounce.mjs b/scripts/render-jelly-bounce.mjsindex 1b951f4e..ec96bfc3 100644--- a/scripts/render-jelly-bounce.mjs+++ b/scripts/render-jelly-bounce.mjs@@ -11,17 +11,16 @@ import { Client } from '@modelcontextprotocol/client';import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';import '../tests/support/load-agent-scene-modules.mjs';import { createAgentScene } from '../src/agent-scene.js';-import { JELLY_FRAMES_PER_SECOND, jellyCubeRecipe, measureBounce } from '../tests/support/jelly-cube.mjs';+import { JELLY_FRAMES_PER_SECOND, JELLY_PRESETS, jellyCubeRecipe, measureBounce } from '../tests/support/jelly-cube.mjs';const PREVIEW = { width: 960, height: 540, fps: JELLY_FRAMES_PER_SECOND };const FRAME_COUNT = 150;const serverEntry = new URL('../bin/67js-mcp.mjs', import.meta.url).pathname.replace(/^\/(\w:)/, '$1');-const CUBES = [- { id: 'firm', x: -1.2, color: [0.2, 0.55, 0.95], softBody: { shape: 1, bounce: 0.1 }, sheet: {} },- { id: 'medium', x: 0, color: [0.25, 0.85, 0.45], softBody: { shape: 0.15, bounce: 0.5 }, sheet: {} },- { id: 'soft', x: 1.2, color: [0.95, 0.35, 0.55], softBody: { shape: 0.02, bounce: 1 }, sheet: { stiffness: 0.1 } },-];+// The presets are shared with the test (tests/support/jelly-cube.mjs). Colours are named so the labels and the docs agree:+// blue is firm, amber is medium, pink is soft.+const POSITIONS = { firm: { x: -1.2, color: [0.15, 0.45, 0.95] }, medium: { x: 0, color: [0.98, 0.7, 0.1] }, soft: { x: 1.2, color: [0.95, 0.3, 0.6] } };+const CUBES = JELLY_PRESETS.map(preset => ({ ...preset, ...POSITIONS[preset.id] }));function threeCubeRecipe() {const single = jellyCubeRecipe({ duration: FRAME_COUNT / JELLY_FRAMES_PER_SECOND });@@ -78,7 +77,7 @@ async function main() {const stillTimes = {};for (const [id, frames] of cubeFrames(recipe)) {const bounce = measureBounce(frames);- measured[id] = { ...CUBES.find(cube => cube.id === id).softBody, ...CUBES.find(cube => cube.id === id).sheet, contactStep: bounce.contact, deepestDentStep: bounce.deepestFrame, reboundTopStep: bounce.topFrame, dentMeters: Number(bounce.dent.toFixed(4)), reboundMeters: Number(bounce.reboundHeight.toFixed(4)) };+ measured[id] = { colorName: CUBES.find(cube => cube.id === id).colorName, ...CUBES.find(cube => cube.id === id).softBody, ...CUBES.find(cube => cube.id === id).sheet, contactStep: bounce.contact, deepestDentStep: bounce.deepestFrame, reboundTopStep: bounce.topFrame, dentMeters: Number(bounce.dent.toFixed(4)), reboundMeters: Number(bounce.reboundHeight.toFixed(4)) };stillTimes[`${id}-contact`] = bounce.contact / JELLY_FRAMES_PER_SECOND;stillTimes[`${id}-deepest-dent`] = bounce.deepestFrame / JELLY_FRAMES_PER_SECOND;stillTimes[`${id}-rebound-top`] = bounce.topFrame / JELLY_FRAMES_PER_SECOND;diff --git a/tests/soft-body-bounce.test.js b/tests/soft-body-bounce.test.jsindex 483f8267..32074971 100644--- a/tests/soft-body-bounce.test.js+++ b/tests/soft-body-bounce.test.js@@ -2,7 +2,7 @@ import test from 'node:test';import { createHash } from 'node:crypto';import assert from 'node:assert/strict';import { createCloth } from '../src/cloth.js';-import { frameHashes, jellyCubeRecipe, measureBounce, recordJelly } from './support/jelly-cube.mjs';+import { foldedTriangles, frameHashes, JELLY_PRESETS, jellyCubeRecipe, measureBounce, recordJelly } from './support/jelly-cube.mjs';const FRAME_COUNT = 110;@@ -76,3 +76,21 @@ test('a recipe sheet rejects a bad bounce at the boundary', async () => {const { createAgentScene } = await import('../src/agent-scene.js');assert.throws(() => createAgentScene(jellyCubeRecipe({ softBody: { bounce: 2 } })), /softBody\.bounce.*0.*1/s);});++// The preview's three presets (`JELLY_PRESETS`): each step must be clearly visible, and the surface must not fold.+test('the firm, medium and soft presets step clearly in dent and rebound without folding', () => {+ const results = JELLY_PRESETS.map(preset => measure(preset.softBody, preset.sheet));+ const [firm, medium, soft] = results;+ assert.ok(medium.dent > firm.dent * 1.4 && soft.dent > medium.dent * 1.1, `dents ${results.map(result => result.dent.toFixed(3)).join(', ')}`);+ assert.ok(medium.reboundHeight > firm.reboundHeight * 1.8 && soft.reboundHeight > medium.reboundHeight * 1.8, `rebounds ${results.map(result => result.reboundHeight.toFixed(3)).join(', ')}`);+ assert.ok(soft.dent > 0.045 && soft.reboundHeight > 0.4, `soft dent ${soft.dent}, rebound ${soft.reboundHeight}`);+ for (const preset of JELLY_PRESETS) {+ const folded = foldedTriangles(jellyCubeRecipe({ softBody: preset.softBody, sheet: preset.sheet }), FRAME_COUNT);+ assert.ok(folded <= 8, `${preset.id} folded ${folded} of 588 triangles in one frame`);+ }+});++test('a near-zero shape folds the surface on impact, which is why the soft preset keeps 0.15', () => {+ const folded = foldedTriangles(jellyCubeRecipe({ softBody: { shape: 0.02, bounce: 1 }, sheet: { stiffness: 0.1 } }), FRAME_COUNT);+ assert.ok(folded > 50, `shape 0.02 should fold more than 50 triangles, got ${folded}`);+});diff --git a/tests/support/jelly-cube.mjs b/tests/support/jelly-cube.mjsindex 2b85fa7a..cdcca8ae 100644--- a/tests/support/jelly-cube.mjs+++ b/tests/support/jelly-cube.mjs@@ -78,3 +78,42 @@ export function measureBounce(frames) {const reboundHeight = liftOff >= frames.length ? 0 : ranges[topFrame].low - FLOOR_THICKNESS;return { restHeight, contact, deepestFrame, topFrame: Math.min(topFrame, frames.length - 1), dent: restHeight - ranges[deepestFrame].extent, reboundHeight };}++/**+ * The three jellies of the preview, from firm to soft. The soft one keeps `shape` at 0.15: below about 0.1 the surface+ * folds over itself on impact (see `foldedTriangles`), which is how a deeper dent was paid for before.+ */+export const JELLY_PRESETS = [+ { id: 'firm', colorName: 'blue', softBody: { shape: 1, bounce: 0 }, sheet: {} },+ { id: 'medium', colorName: 'amber', softBody: { shape: 0.3, bounce: 0.6 }, sheet: { stiffness: 0.2 } },+ { id: 'soft', colorName: 'pink', softBody: { shape: 0.15, bounce: 1 }, sheet: { stiffness: 0.05 } },+];++/**+ * Most triangles facing toward the body's centre in any one frame. A closed convex-ish jelly keeps every triangle facing+ * out, so a count above zero means the surface folded over itself (a fold shows as ragged doubled edges).+ */+export function foldedTriangles(recipe, frameCount) {+ const scene = createAgentScene(recipe);+ let worst = 0;+ for (let frame = 0; frame < frameCount; frame++) {+ scene.sampleMotion(frame / JELLY_FRAMES_PER_SECOND);+ const { positions, indices } = scene.parts.find(part => part.name === 'cube').geometry;+ const center = [0, 0, 0];+ for (let index = 0; index < positions.length; index++) center[index % 3] += positions[index] / (positions.length / 3);+ let folded = 0;+ for (let corner = 0; corner < indices.length; corner += 3) {+ const a = indices[corner] * 3;+ const b = indices[corner + 1] * 3;+ const c = indices[corner + 2] * 3;+ const edgeOne = [positions[b] - positions[a], positions[b + 1] - positions[a + 1], positions[b + 2] - positions[a + 2]];+ const edgeTwo = [positions[c] - positions[a], positions[c + 1] - positions[a + 1], positions[c + 2] - positions[a + 2]];+ const facing = (edgeOne[1] * edgeTwo[2] - edgeOne[2] * edgeTwo[1]) * (positions[a] - center[0])+ + (edgeOne[2] * edgeTwo[0] - edgeOne[0] * edgeTwo[2]) * (positions[a + 1] - center[1])+ + (edgeOne[0] * edgeTwo[1] - edgeOne[1] * edgeTwo[0]) * (positions[a + 2] - center[2]);+ if (facing <= 0) folded++;+ }+ worst = Math.max(worst, folded);+ }+ return worst;+}