3D engine that AI agents drive
Make the Jolt docs say what was measured (#771)
Nguyen Xuan An06ae64b37ef4
diff --git a/docs/physics-runtime.md b/docs/physics-runtime.mdindex fd1ef73d..58adb186 100644--- a/docs/physics-runtime.md+++ b/docs/physics-runtime.md@@ -90,7 +90,7 @@ import { joltAdapter } from '67js/addons/physics-jolt';const physics = await createPhysicsSystem(definition, { adapter: joltAdapter });```-`jolt-physics` (JoltPhysics built to wasm, MIT, install it with `npm install jolt-physics`) is an optional peer dependency of the `physics-jolt` addon; the core and the other addons never import it. The adapter covers bodies, sensors, collision groups and masks, kinematic control, force fields, ray, shape-cast and overlap queries, and the same contact and sensor events as Rapier. What it does not cover yet throws an error that names the fix: joints, `cone` and `trimesh` colliders, and more than one collider per body. It also limits a scene to 256 distinct group and mask pairs. Engines differ in friction and restitution combining and in solver details, so a settled pose can differ by a few centimetres between engines. Jolt reports a contact as ended when a body falls asleep; the adapter hides that, so a sleeping box keeps its contact.+`jolt-physics` (JoltPhysics built to wasm, MIT, install it with `npm install jolt-physics`) is an optional peer dependency of the `physics-jolt` addon; the core and the other addons never import it. The adapter covers bodies, sensors, collision groups and masks, kinematic control, force fields, ray, shape-cast and overlap queries, and contact and sensor events. What it does not cover yet throws an error that names the fix: joints, `cone` and `trimesh` colliders, and more than one collider per body. It also limits a scene to 256 distinct group and mask pairs. Engines differ in friction and restitution combining and in solver details, so a settled pose can differ between engines: a box that falls straight down settles within a few centimetres, but an offset cuboid rested at y 0.5 on one engine and 0.48 on the other, and a cylinder came to rest in different poses (Rapier tips and rolls it). Events are shown to match only for a dynamic box falling through a fixed sensor. For a kinematic body moving through a fixed sensor, Rapier gave no sensor events and Jolt did, so do not rely on kinematic-versus-fixed sensor events being the same on both engines. Jolt reports a contact as ended when a body falls asleep; the adapter hides that, so a sleeping box keeps its contact.## Limits@@ -98,4 +98,4 @@ At most 64 listeners per kind, 4096 bound parts, 1024 overlap results and a querAfter every step the system checks each pose like the bake does: a non-finite position or a quaternion that is not unit length throws a `RangeError` naming the body and the step, so a bad pose never reaches a bound part. If setup throws (an unknown body in `bindings`, say), the engine world is freed before the error propagates.-Steps for 500 dynamic boxes settling on a floor, 240 steps after 10 warm-up steps, three runs on one machine under load from other jobs (Node 24, wasm builds of both engines): Rapier 0.81 to 1.19 ms, Jolt 0.76 to 0.87 ms. `tests/physics-jolt.test.js` prints the figures and asserts only that they are finite. The same file replays one scene on both engines (a box falls on a floor, is pushed through a sensor zone and leaves it) and asserts the same contact and sensor events in the same order, each within 3 steps of the other engine's step, and the final box position within 0.2 m. In the recorded run the events fired on identical steps: contact start at step 34, sensor start at 83, sensor stop at 121 on both, and the box stopped at x 6.499 on Rapier and 6.457 on Jolt.+Steps for 500 dynamic boxes settling on a floor, 120 steps after 10 warm-up steps, on one machine under load from other jobs (Node 24, wasm builds of both engines). The two engines are about equal on this scene: one loaded run gave Rapier 1.872 ms and Jolt 1.846 ms per step, and other runs swapped the order, so these figures show no winner. `tests/physics-jolt.test.js` prints the figures and asserts only that they are finite. The same file replays one scene on both engines (a box falls on a floor, is pushed through a sensor zone and leaves it) and asserts the same contact and sensor events in the same order, each within 3 steps of the other engine's step, and the final box position within 0.2 m. In the recorded run the events fired on identical steps: contact start at step 34, sensor start at 83, sensor stop at 121 on both, and the box stopped at x 6.499 on Rapier and 6.457 on Jolt.diff --git a/tests/physics-jolt.test.js b/tests/physics-jolt.test.jsindex 53a6bb8e..87099780 100644--- a/tests/physics-jolt.test.js+++ b/tests/physics-jolt.test.js@@ -225,6 +225,25 @@ test('a convex hull rests on the floor under jolt, with and without a collider o}});+test('a capsule with a rotated collider offset comes to rest on the floor under jolt', async () => {+ const quarterTurnAroundZ = [0, 0, Math.SQRT1_2, Math.SQRT1_2];+ const definition = {+ bodies: [+ { name: 'floor', type: 'fixed', translation: [0, -0.5, 0] },+ { name: 'pill', translation: [0, 0.6, 0] },+ ],+ colliders: [+ { name: 'ground', body: 'floor', shape: 'cuboid', halfExtents: [10, 0.5, 10] },+ { name: 'capsule', body: 'pill', shape: 'capsule', halfHeight: 0.5, radius: 0.25, mass: 1, translation: [0.3, 0, 0], rotation: quarterTurnAroundZ },+ ],+ };+ const physics = await createPhysicsSystem(definition, { adapter: joltAdapter });+ stepMany(physics, 180);+ const height = physics.getPose('pill').translation[1];+ assert.ok(Math.abs(height - 0.25) < POSE_TOLERANCE, `the lying capsule rests with its axis on the floor at y 0.25, got y ${height}`);+ physics.dispose();+});+test('a collinear convex hull fails with a RangeError that names the collider', async () => {await assert.rejects(createPhysicsSystem(hullDefinition(COLLINEAR_POINTS, [0, 0, 0], undefined), { adapter: joltAdapter }), error => {assert.ok(error instanceof RangeError);