3D engine that AI agents drive
Float on the drawn sea by default and warn when the level disagrees (#982)
Nguyen Xuan Anf7e5fccb293c
diff --git a/changes/982.md b/changes/982.mdindex 3232e44d..b4fe68bd 100644--- a/changes/982.md+++ b/changes/982.md@@ -1,2 +1,2 @@-- Rigid bodies float on the ocean: `physics.ocean` and a body `float` field make crates and hulls bob, roll and settle on the drawn waves (#982)+- Rigid bodies float on the ocean: `physics.ocean` and a body `float` field make crates and hulls bob, roll and settle on the drawn waves, at the height of the drawn sea (#982)media: https://raw.githubusercontent.com/codepawl/67.js/982-buoyancy/docs/buoyancy-still.jpg Crates and a boat riding ocean wavesdiff --git a/docs/physics.md b/docs/physics.mdindex acfdef88..5a155498 100644--- a/docs/physics.md+++ b/docs/physics.md@@ -396,7 +396,7 @@ A crate or a boat can float on the sea that the `ocean` mesh edit draws. Give th```json"physics": {"duration": 8,- "ocean": { "geometry": "sea", "level": 0, "waterDensity": 1000 },+ "ocean": { "geometry": "sea", "waterDensity": 1000 },"bodies": [{ "node": "crate", "density": 500, "float": { "drag": 2, "angularDrag": 2 } },{ "node": "boat", "shape": "convex", "density": 300, "float": { "points": [[-1.5, 0, -0.6], [1.5, 0, -0.6], [-1.5, 0, 0.6], [1.5, 0, 0.6]] } }@@ -404,7 +404,7 @@ A crate or a boat can float on the sea that the `ocean` mesh edit draws. Give th}```-`ocean.geometry` names a mesh geometry whose stack has an `ocean` node with axis `y`. The body floats on that node's waves (`windSpeed`, `direction`, `choppiness`, `size`, `seed`, `resolution`), read through the same function that moves the drawn vertices, so what the body rides is what the camera sees. The sea clock at physics time 0 is the node's `time`; drive an `oceanTime` track at one second per second to keep the drawn sea in step. `level` is the world height of the calm sea and `waterDensity` is in kg/m3.+`ocean.geometry` names a mesh geometry whose stack has an `ocean` node with axis `y`. The body floats on that node's waves (`windSpeed`, `direction`, `choppiness`, `size`, `seed`, `resolution`), read through the same function that moves the drawn vertices, so what the body rides is what the camera sees. The sea clock at physics time 0 is the node's `time`; drive an `oceanTime` track at one second per second to keep the drawn sea in step. `level` is the world height of the calm sea. Leave it out: it then follows the sea as drawn (the node's translation plus its y scale times the mean height of the sheet, so a sheet cut from the top of a unit box drawn at y 2 floats bodies at 2.5). A `level` that differs from the drawn sea by more than 0.05 m is used as given, and `scene_inspect` returns a `warnings` entry in the physics report that names both heights. `waterDensity` is in kg/m3.Each `float` body carries sample points in body space, 16 at most. Without `points` it gets four, in a 2 x 2 grid across the collider bounds at mid height. Every point owns an equal share of the body's volume as a column as tall as the body. Where the surface stands above the point, the column is submerged by a fraction and the water pushes up at that point with `waterDensity x gravity x volume / points x fraction`. A body lighter than water bobs and rolls; a box of density 500 sinks to half its height. Spread the points over the hull, wide for roll and long for pitch, so the body rights itself when a wave tips it. `drag` and `angularDrag` (1/s, 0 to 100, default 2) damp the linear and angular velocity in proportion to the mean submerged fraction. Only dynamic bodies float, and a float body needs a volume, so trimesh does not work.diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 16117600..8c560a34 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -635,7 +635,7 @@ const physics = z.strictObject({gravity: vector3.optional().describe('Defaults to [0, -9.81, 0].'),bodies: z.array(physicsBody).min(1).max(64),joints: z.array(physicsJoint).max(64).optional().describe('Joint bodies are the node IDs of physics bodies.'),- ocean: z.record(z.string(), z.unknown()).optional().describe('Sea for floating bodies: geometry is a mesh geometry whose stack has an ocean node (axis y) whose waves they ride; level 0 is the world height of the calm sea; waterDensity 1000 kg/m3. The sea clock at physics time 0 is the ocean node time, so drive an oceanTime track at 1 s per s to keep the drawn sea in step.'),+ ocean: z.record(z.string(), z.unknown()).optional().describe('Sea for floating bodies: geometry is a mesh geometry whose stack has an ocean node (axis y) whose waves they ride; level is the world height of the calm sea (leave it out to follow the drawn sea; a different value adds a warning to the scene_inspect physics report); waterDensity 1000 kg/m3. The sea clock at physics time 0 is the ocean node time, so drive an oceanTime track at 1 s per s to keep the drawn sea in step.'),}).describe('Rigid bodies recorded offline with Rapier (optional peer) at 60 fps and seeked by motionTime. scene_inspect reports contacts and resting state. A node cannot have a body and a motion translation or rotation track.');const looseRecord = z.record(z.string(), z.unknown()).meta({ id: 'LooseRecord' });const clothSheet = z.strictObject({diff --git a/scripts/render-buoyancy-film.mjs b/scripts/render-buoyancy-film.mjsindex 4ab1dd29..4a59725b 100644--- a/scripts/render-buoyancy-film.mjs+++ b/scripts/render-buoyancy-film.mjs@@ -87,8 +87,7 @@ function buildRecipe(boatAssetId) {motion: { duration, tracks: [{ kind: 'geometry', id: 'sea', property: 'oceanTime', interpolation: 'LINEAR', keyframes: [{ time: 0, value: 0 }, { time: duration, value: duration }] }] },physics: {duration,- // The sheet is the top of a unit box, so it draws at y = 0.5.- ocean: { geometry: 'sea', level: 0.5 },+ ocean: { geometry: 'sea' },bodies: [...crates.map(entry => entry.body),{ node: 'hull', density: 300, float: { drag: 1.5, angularDrag: 1.5, points: [[-0.6, 0, -1.4], [0.6, 0, -1.4], [-0.6, 0, 1.4], [0.6, 0, 1.4]] } },diff --git a/src/agent-physics.js b/src/agent-physics.jsindex 2a31f76f..659f9c4f 100644--- a/src/agent-physics.js+++ b/src/agent-physics.js@@ -384,12 +384,33 @@ function normalizeOceanReference(input, recipe) {return ocean;}-/** The sea of the definition: the wave fields of the referenced ocean node plus the level and water density. */-function oceanDefinition(oceanReference, recipe) {+const SEA_LEVEL_TOLERANCE = 0.05;++/**+ * World height of the sea as drawn: the first node showing the ocean geometry, at its translation plus its y scale times the+ * mean height of the geometry (waves average out to the calm surface). Null when no node shows it. Rotation and parents are ignored.+ */+function drawnSeaLevel(oceanReference, recipe, geometries) {+ const node = recipe.nodes.find(candidate => candidate.geometry === oceanReference.geometry);+ const positions = geometries.get(oceanReference.geometry)?.positions;+ if (!node || !positions?.length) return null;+ let heightTotal = 0;+ for (let index = 1; index < positions.length; index += 3) heightTotal += positions[index];+ return node.translation[1] + node.scale[1] * heightTotal / (positions.length / 3);+}++/** A warning when the level the recipe gives differs from the drawn sea, which makes floating bodies sink out of view; else null. */+function seaLevelWarning(oceanReference, drawnLevel) {+ if (oceanReference.level === undefined || drawnLevel === null || Math.abs(oceanReference.level - drawnLevel) <= SEA_LEVEL_TOLERANCE) return null;+ return `physics.ocean.level is ${oceanReference.level} but the sea geometry "${oceanReference.geometry}" is drawn at height ${Number(drawnLevel.toFixed(3))}; bodies float on the level, so they sit ${Number(Math.abs(oceanReference.level - drawnLevel).toFixed(3))} m ${oceanReference.level < drawnLevel ? 'below' : 'above'} the visible water. Leave level out to follow the drawn sea.`;+}++/** The sea of the definition: the wave fields of the referenced ocean node, the level (default: the drawn sea) and the water density. */+function oceanDefinition(oceanReference, recipe, drawnLevel) {const node = oceanNodeOf(oceanReference.geometry, recipe);const waves = Object.fromEntries(OCEAN_WAVE_KEYS.filter(key => node[key] !== undefined).map(key => [key, node[key]]));const { geometry, ...water } = oceanReference;- return { ...waves, ...water };+ return { ...waves, level: drawnLevel ?? 0, ...water };}function scaledBounds(positions, scale) {@@ -518,7 +539,7 @@ function physicsDefinition(physics, recipe, geometries, ragdoll) {(physics.joints ?? []).forEach((joint, index) => definition.joints.push({ name: joint.name ?? `joint-${index}`, ...joint }));if (physics.events) definition.events = physics.events;if (physics.fields) definition.fields = physics.fields;- if (physics.ocean) definition.ocean = oceanDefinition(physics.ocean, recipe);+ if (physics.ocean) definition.ocean = oceanDefinition(physics.ocean, recipe, drawnSeaLevel(physics.ocean, recipe, geometries));for (const body of physics.bodies) {if (body.float) definition.bodies.find(candidate => candidate.name === body.node).float = body.float;}@@ -594,6 +615,7 @@ export function bakeAgentPhysics(physics, recipe, geometries) {const offset = scene.bodyIndex(nodeId) * 7;return { translation: pose.subarray(offset, offset + 3), rotation: pose.subarray(offset + 3, offset + 7) };};+ const seaWarning = physics.ocean ? seaLevelWarning(physics.ocean, drawnSeaLevel(physics.ocean, recipe, geometries)) : null;let reportCache = null;return Object.freeze({duration: physics.duration,@@ -614,6 +636,7 @@ export function bakeAgentPhysics(physics, recipe, geometries) {duration: physics.duration, frames: scene.frameCount, gravity: physics.gravity ?? [0, -9.81, 0],bodies: bodyReport(scene, physics), ...contactReport(scene, physics),eventsTruncated: scene.contactEventsTruncated,+ ...(seaWarning ? { warnings: [seaWarning] } : {}),...(scene.jointBreaks.length ? { jointBreaks: scene.jointBreaks.slice(0, MAX_REPORTED_CONTACTS).map(({ frame, joint, impulse }) => ({ joint, time: roundedTime(frame, scene.timestep), impulse: Number(impulse.toFixed(3)) })) } : {}),...(ragdoll ? { ragdoll: ragdollReport(ragdoll, scene) } : {}),};diff --git a/tests/physics-buoyancy-drawn-level.test.js b/tests/physics-buoyancy-drawn-level.test.jsnew file mode 100644index 00000000..a993a130--- /dev/null+++ b/tests/physics-buoyancy-drawn-level.test.js@@ -0,0 +1,52 @@+import './support/load-agent-scene-modules.mjs';+import test from 'node:test';+import assert from 'node:assert/strict';+import { createAgentScene, loadPhysicsEngine } from '../src/agent-scene.js';++await loadPhysicsEngine({ buoyancy: true });++const SEA_NODE_HEIGHT = 2;+const SHEET_TOP = 0.5;++// A sheet made of the top face of a unit box, so it draws half a metre above its node.+function seaRecipe(ocean) {+ return {+ format: '67js.scene', schemaVersion: 1,+ geometries: [+ { id: 'cube', type: 'box' },+ {+ id: 'sea', type: 'mesh', base: { type: 'box', bevel: 0 },+ edits: [+ { op: 'delete', select: { not: { normal: [0, 1, 0], maxAngle: 10 } } },+ { op: 'subdivide_edges', edges: { all: true }, cuts: 8 },+ { op: 'set_position', position: { mul: [{ attr: 'position' }, [20, 1, 20]] } },+ ],+ stack: [{ op: 'ocean', windSpeed: 0.5, size: 50, seed: 4 }],+ },+ ],+ materials: [{ id: 'paint', color: [0.6, 0.5, 0.4] }],+ nodes: [+ { id: 'sea', geometry: 'sea', material: 'paint', translation: [0, SEA_NODE_HEIGHT, 0] },+ { id: 'crate', geometry: 'cube', material: 'paint', translation: [0, SEA_NODE_HEIGHT + SHEET_TOP + 0.4, 0] },+ ],+ physics: { duration: 10, ocean, bodies: [{ node: 'crate', density: 500, float: {} }] },+ };+}++test('without a level the sea follows its drawn surface: a crate on a sea node at y 2 settles near 2.5', () => {+ const scene = createAgentScene(seaRecipe({ geometry: 'sea' }));+ scene.sampleMotion(10);+ const crate = scene.parts.find(part => part.node === 'crate' || part.id === 'crate') ?? scene.parts[1];+ const settledHeight = crate.matrix[13];+ assert.ok(Math.abs(settledHeight - (SEA_NODE_HEIGHT + SHEET_TOP)) < 0.05, `crate centre ${settledHeight}`);+ assert.equal(scene.inspect({}).physics.warnings, undefined);+});++test('a level far from the drawn sea returns a warning naming both heights', () => {+ const scene = createAgentScene(seaRecipe({ geometry: 'sea', level: 0 }));+ const { warnings } = scene.inspect({}).physics;+ assert.equal(warnings.length, 1);+ assert.match(warnings[0], /physics\.ocean\.level is 0 .* "sea" is drawn at height 2\.5/);+ const close = createAgentScene(seaRecipe({ geometry: 'sea', level: SEA_NODE_HEIGHT + SHEET_TOP + 0.02 }));+ assert.equal(close.inspect({}).physics.warnings, undefined);+});