Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
index 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 waves
diff --git a/docs/physics.md b/docs/physics.md
index 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.mjs
index 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.mjs
index 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.js
index 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.js
new file mode 100644
index 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);
+});