Skip to content

armgit / 67.js

Public Imported from GitHub
0

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