@series-inc/rundot-syncplay 5.23.0 → 5.24.0-beta.0

package/dist/cjs/physics3d.js

@@ -7,6 +7,7 @@ exports.applyDeterministicImpulse3D = applyDeterministicImpulse3D;
 exports.setDeterministicBodyVelocity3D = setDeterministicBodyVelocity3D;
 exports.stepDeterministicPhysicsWorld3D = stepDeterministicPhysicsWorld3D;
 exports.deterministicPhysicsBodyById3D = deterministicPhysicsBodyById3D;
+exports.__staticTreeBuildCount = __staticTreeBuildCount;
 exports.raycastDeterministicPhysics3D = raycastDeterministicPhysics3D;
 exports.raycastDeterministicPhysics3DDetailed = raycastDeterministicPhysics3DDetailed;
 exports.overlapDeterministicPhysics3D = overlapDeterministicPhysics3D;
@@ -20,11 +21,14 @@ exports.runDeterministicPhysics3DDetailFixture = runDeterministicPhysics3DDetail
 exports.runDeterministicPhysics3DStress = runDeterministicPhysics3DStress;
 exports.runDeterministicPhysics3DStackFixture = runDeterministicPhysics3DStackFixture;
 exports.deriveInverseInertia = deriveInverseInertia;
+exports.__countCandidatePairsCalls = __countCandidatePairsCalls;
 const canonical_js_1 = require("./canonical.js");
 const deterministic_primitives_js_1 = require("./deterministic-primitives.js");
 const physics3d_shared_js_1 = require("./physics3d-shared.js");
 const physics3d_solver_js_1 = require("./physics3d-solver.js");
 const physics3d_joints_js_1 = require("./physics3d-joints.js");
+const physics3d_hull_js_1 = require("./physics3d-hull.js");
+const physics3d_toi_js_1 = require("./physics3d-toi.js");
 exports.deterministicPhysicsCallback3D = {
     collisionEnter: 1,
     collisionStay: 2,
@@ -288,9 +292,13 @@ function stepDeterministicPhysicsWorld3D(world, options = {}) {
     if (!Number.isInteger(velocityIterations) || velocityIterations <= 0) {
         throw new Error(`physics3d step: velocityIterations must be a positive integer, received ${velocityIterations}`);
     }
+    const substeps = options.substeps ?? physics3d_solver_js_1.SOLVER_CONSTANTS.SUBSTEPS;
+    if (!Number.isInteger(substeps) || substeps <= 0) {
+        throw new Error(`physics3d step: substeps must be a positive integer, received ${substeps}`);
+    }
     const dt = options.dtTicks ?? 1;
     const gravityY = options.gravityY ?? 0;
-    const rigid = runRigidSolver(world, dt, gravityY, velocityIterations, options.joints ?? []);
+    const rigid = runRigidSolver(world, dt, gravityY, velocityIterations, substeps, options.joints ?? [], options.pairs);
     const constrained = solveConstraints3D(rigid.bodies, options.constraints ?? []);
     const solvedBodies = constrained.bodies;
     // Dynamic-involved solid-collision events come from the solver's manifolds (so
@@ -365,7 +373,9 @@ function stepDeterministicPhysicsWorld3D(world, options = {}) {
         scheduledQueryResults,
         prePhysicsScheduledQueryResults,
         postPhysicsScheduledQueryResults,
-        broadphasePairs: countCandidatePairs(solvedBodies),
+        broadphasePairs: options.computeBroadphasePairs === true
+            ? countCandidatePairs(solvedBodies)
+            : 0,
         narrowphaseContacts: rigid.narrowphaseContacts,
         solverCorrections,
         checksum: options.computeChecksum === false ? '' : (0, canonical_js_1.defaultChecksum)({ nextWorld, scheduledQueryResults, events, solverCorrections }),
@@ -379,7 +389,9 @@ function fastStressStepPhysicsWorld3D(world, scheduledQueries) {
     const nextWorld = {
         frame: world.frame + 1,
         bodies: world.bodies.map((body) => {
-            if (body.kind !== 'dynamic') {
+            // Kinematic bodies advance on their authored velocity here too — the
+            // extrapolated path skips the solver, not the author's driving motion.
+            if (body.kind === 'static') {
                 return body;
             }
             return {
@@ -538,7 +550,12 @@ function buildQueryIndexTree(bodies) {
  * subtree — usually the bulk of a level — is reused frame over frame; only
  * the dynamic subtree is rebuilt. Identity comparison makes reuse exact.
  */
-let staticQueryTreeCache;
+const STATIC_TREE_CACHE_SLOTS = 4;
+const staticQueryTreeCache = [];
+let staticTreeBuildCount = 0;
+function __staticTreeBuildCount() {
+    return staticTreeBuildCount;
+}
 function sameBodyIdentities(left, right) {
     if (left.length !== right.length) {
         return false;
@@ -550,6 +567,21 @@ function sameBodyIdentities(left, right) {
     }
     return true;
 }
+function staticTreeFor(statics) {
+    const hit = staticQueryTreeCache.findIndex((entry) => sameBodyIdentities(entry.statics, statics));
+    if (hit !== -1) {
+        const [entry] = staticQueryTreeCache.splice(hit, 1);
+        staticQueryTreeCache.unshift(entry);
+        return entry.tree;
+    }
+    const tree = buildQueryIndexTree(statics);
+    staticTreeBuildCount += 1;
+    staticQueryTreeCache.unshift({ statics, tree });
+    if (staticQueryTreeCache.length > STATIC_TREE_CACHE_SLOTS) {
+        staticQueryTreeCache.pop();
+    }
+    return tree;
+}
 function queryIndexFor(world) {
     const cached = queryIndexCache.get(world);
     if (cached !== undefined) {
@@ -565,14 +597,7 @@ function queryIndexFor(world) {
             movers.push(body);
         }
     }
-    let staticTree;
-    if (staticQueryTreeCache !== undefined && sameBodyIdentities(staticQueryTreeCache.statics, statics)) {
-        staticTree = staticQueryTreeCache.tree;
-    }
-    else {
-        staticTree = buildQueryIndexTree(statics);
-        staticQueryTreeCache = { statics, tree: staticTree };
-    }
+    const staticTree = staticTreeFor(statics);
     const index = {
         trees: movers.length > 0 ? [staticTree, buildQueryIndexTree(movers)] : [staticTree],
         bodyById: new Map(world.bodies.map((body) => [body.id, body])),
@@ -1084,7 +1109,11 @@ function runDeterministicPhysics3DStress(bodies, frames, options = {}) {
             },
         ];
         const result = shouldRunFullStep
-            ? stepDeterministicPhysicsWorld3D(world, { computeChecksum: false, scheduledQueries })
+            ? stepDeterministicPhysicsWorld3D(world, {
+                computeChecksum: false,
+                computeBroadphasePairs: true,
+                scheduledQueries,
+            })
             : fastStressStepPhysicsWorld3D(world, scheduledQueries);
         const shapeCastHits = frame % 64 === 0
             ? shapeCastDeterministicPhysics3D(world, {
@@ -1231,7 +1260,11 @@ function runPhysics3DStackWorld(initialWorld, frames) {
         if (frame === snapshotFrame) {
             snapshot = (0, canonical_js_1.cloneCanonical)(world);
         }
-        const result = stepDeterministicPhysicsWorld3D(world, { gravityY: -0.001, computeChecksum: false });
+        const result = stepDeterministicPhysicsWorld3D(world, {
+            gravityY: -0.001,
+            computeChecksum: false,
+            computeBroadphasePairs: true,
+        });
         world = result.world;
         contactCount += result.narrowphaseContacts;
         solverCorrections += result.solverCorrections;
@@ -1304,7 +1337,9 @@ function callbackFixtureBody(id, x, trigger, callbackMask) {
 }
 const DEFAULT_LINEAR_DAMPING = 0.995;
 const DEFAULT_ANGULAR_DAMPING = 0.98;
-const DEFAULT_VELOCITY_ITERATIONS = 10;
+// Per-substep iterations under the soft-step (TGS-Soft) scheme; the total solve
+// passes are substeps × (velocityIterations + 1 relax). Was 10 pre-soft-step.
+const DEFAULT_VELOCITY_ITERATIONS = 3;
 function toSolverPrimitiveShape(shape) {
     if (shape.type === 'box') {
         return { kind: 'box', half: { x: shape.halfX, y: shape.halfY, z: shape.halfZ } };
@@ -1312,12 +1347,18 @@ function toSolverPrimitiveShape(shape) {
     if (shape.type === 'sphere') {
         return { kind: 'sphere', radius: shape.radius };
     }
+    if (shape.type === 'hull') {
+        return { kind: 'hull', data: (0, physics3d_hull_js_1.buildSolverHull)(shape.vertices) };
+    }
     return { kind: 'capsule', radius: shape.radius, halfHeight: shape.halfHeight };
 }
 function toSolverShape(shape) {
     if (shape.type === 'box' || shape.type === 'sphere' || shape.type === 'capsule') {
         return toSolverPrimitiveShape(shape);
     }
+    if (shape.type === 'hull') {
+        return { kind: 'hull', data: (0, physics3d_hull_js_1.buildSolverHull)(shape.vertices) };
+    }
     if (shape.type === 'compound') {
         return {
             kind: 'compound',
@@ -1356,8 +1397,8 @@ function deriveInverseInertia(shape, mass) {
         const iLateral = (mass / 12) * (3 * r * r + h * h);
         return { x: 1 / iLateral, y: 1 / iAxial, z: 1 / iLateral };
     }
-    if (shape.type === 'compound') {
-        // union-AABB box approximation of the compound inertia (v1).
+    if (shape.type === 'compound' || shape.type === 'hull') {
+        // union-AABB box approximation of the inertia (v1 — same as compound).
         const bounds = shapePoseBounds({ x: 0, y: 0, z: 0, shape });
         const half = { x: (bounds.maxX - bounds.minX) / 2, y: (bounds.maxY - bounds.minY) / 2, z: (bounds.maxZ - bounds.minZ) / 2 };
         return deriveInverseInertia({ type: 'box', halfX: Math.max(half.x, 1e-3), halfY: Math.max(half.y, 1e-3), halfZ: Math.max(half.z, 1e-3) }, mass);
@@ -1367,6 +1408,7 @@ function deriveInverseInertia(shape, mass) {
 }
 function buildSolverBody(body, index) {
     const isDynamic = body.kind === 'dynamic';
+    const isKinematic = body.kind === 'kinematic';
     const mass = body.mass ?? 1;
     const baseInvMass = isDynamic ? 1 / mass : 0;
     const lockLinear = body.lockLinear ?? {};
@@ -1376,6 +1418,7 @@ function buildSolverBody(body, index) {
         index,
         id: body.id,
         isDynamic,
+        isKinematic,
         sleeping: body.sleeping === true,
         p: { x: body.x, y: body.y, z: body.z },
         q: body.orientation ?? { x: 0, y: 0, z: 0, w: 1 },
@@ -1439,7 +1482,236 @@ function warmCacheToMap(cache, indexById) {
     }
     return warm;
 }
-function runRigidSolver(world, dt, gravityY, velocityIterations, joints) {
+/**
+ * Per-step fast-ccd set (box3d b3_isFast) with each fast body's exact first
+ * time-of-impact. A body qualifies only when it is dynamic, awake, `ccd`, collidable
+ * (not a trigger/sensor), has a positive minExtent and a GJK-supported shape, and its
+ * axis-lock-masked intended motion exceeds `CCD_FAST_MOTION_FRACTION · minExtent`.
+ *
+ * Candidate targets are found with a cheap conservative bounding-sphere cast through
+ * the shared query index, then the EXACT surface TOI against each eligible candidate is
+ * computed by GJK conservative advancement (`conservativeToi`); the nearest is kept. A
+ * grazing/separating approach yields no TOI (the exact sweep never touches), so nothing
+ * to clamp — the body slides by. Derived fresh every step (never persisted) so it is
+ * rollback-safe; iterated in body-index order.
+ */
+function computeFastCcdClamps(world, source, solverBodies, dt, indexById, noCollidePairs) {
+    const clamps = new Map();
+    for (let index = 0; index < solverBodies.length; index += 1) {
+        const sb = solverBodies[index];
+        if (!sb.isDynamic || !sb.ccd || sb.sleeping || sb.noCollide) {
+            continue;
+        }
+        const minExtent = (0, physics3d_solver_js_1.minExtentOf)(sb.shape, sb.q);
+        if (!(minExtent > 0)) {
+            continue; // degenerate (flat/zero-extent) shape ⇒ never fast (no divide)
+        }
+        // Intended per-step motion is the solver-effective velocity × dt; a solver-locked
+        // axis (invMassVec component 0) contributes no motion, so a locked axis is ignored.
+        const dx = sb.invMassVec.x === 0 ? 0 : sb.v.x * dt;
+        const dy = sb.invMassVec.y === 0 ? 0 : sb.v.y * dt;
+        const dz = sb.invMassVec.z === 0 ? 0 : sb.v.z * dt;
+        const motion = (0, physics3d_shared_js_1.deterministicSqrt)(dx * dx + dy * dy + dz * dz);
+        if (motion <= physics3d_solver_js_1.SOLVER_CONSTANTS.CCD_FAST_MOTION_FRACTION * minExtent) {
+            continue; // slow enough that ordinary discrete contact suffices
+        }
+        const fastProxy = (0, physics3d_toi_js_1.toiProxyOf)(sb.shape, sb.p, sb.q);
+        if (fastProxy === null) {
+            continue; // mesh/compound ⇒ leave to the discrete solver
+        }
+        const invMotion = 1 / motion;
+        const dirX = dx * invMotion;
+        const dirY = dy * invMotion;
+        const dirZ = dz * invMotion;
+        const hit = firstExactToi(world, source, solverBodies, source[index], index, fastProxy, dirX, dirY, dirZ, motion, indexById, noCollidePairs);
+        if (hit === undefined) {
+            continue; // nothing eligible actually in the swept path ⇒ leave to the solver
+        }
+        clamps.set(index, {
+            prePos: { x: sb.p.x, y: sb.p.y, z: sb.p.z },
+            dirX,
+            dirY,
+            dirZ,
+            maxAdvance: hit.toi,
+            normalX: hit.normal.x,
+            normalY: hit.normal.y,
+            normalZ: hit.normal.z,
+            targetIndices: hit.targetIndices,
+        });
+    }
+    return clamps;
+}
+/**
+ * Exact first surface TOI for a fast body swept along (dir) over `motion`. A conservative
+ * bounding-sphere cast prunes candidates through the shared query index (a superset of
+ * real hits); the exact TOI against each eligible candidate is then found by GJK
+ * conservative advancement, and the nearest is returned. Eligibility mirrors the narrow
+ * phase (self, trigger/sensor, two-way layer/mask, and `disableCollision`-suppressed
+ * pairs excluded). Returns undefined when nothing eligible is actually struck within the
+ * sweep (including a grazing pass that the fat bounding sphere flags but the true shapes
+ * miss).
+ */
+function firstExactToi(world, source, solverBodies, fastBody, fastIndex, fastProxy, dirX, dirY, dirZ, motion, indexById, noCollidePairs) {
+    const sb = solverBodies[fastIndex];
+    const hits = shapeCastDeterministicPhysics3D(world, {
+        shape: { type: 'sphere', radius: (0, physics3d_solver_js_1.boundingRadiusOf)(sb.shape) },
+        x: sb.p.x,
+        y: sb.p.y,
+        z: sb.p.z,
+        dx: dirX,
+        dy: dirY,
+        dz: dirZ,
+        maxDistance: motion,
+        hitTriggers: false,
+        hitSensors: false,
+    });
+    // Collect every eligible body struck at (or within slop of) the first TOI — a body
+    // driven into the seam between two stacked boxes contacts both, and sharing the impact
+    // impulse across them keeps each one's momentum below the coupled relax's stability
+    // limit (a single concentrated impulse diverges the stack).
+    let bestToi = Infinity;
+    let bestNormal = { x: 0, y: 0, z: 0 };
+    const targetIndices = [];
+    for (const hit of hits) {
+        if (hit.bodyId === fastBody.id) {
+            continue;
+        }
+        const targetIndex = indexById.get(hit.bodyId);
+        if (targetIndex === undefined) {
+            continue;
+        }
+        const target = source[targetIndex];
+        if ((fastBody.mask & target.layer) === 0 || (target.mask & fastBody.layer) === 0) {
+            continue;
+        }
+        const key = Math.min(fastIndex, targetIndex) * physics3d_solver_js_1.WARM_KEY_BASE + Math.max(fastIndex, targetIndex);
+        if (noCollidePairs.has(key)) {
+            continue;
+        }
+        const tb = solverBodies[targetIndex];
+        const targetProxy = (0, physics3d_toi_js_1.toiProxyOf)(tb.shape, tb.p, tb.q);
+        if (targetProxy === null) {
+            continue; // mesh/compound target has no convex proxy — CCD unsupported (Gap 2), discrete owns it
+        }
+        const toiHit = (0, physics3d_toi_js_1.conservativeToi)(fastProxy, dirX, dirY, dirZ, motion, targetProxy, physics3d_solver_js_1.SOLVER_CONSTANTS.SLOP);
+        if (toiHit === undefined) {
+            continue; // clean graze — not actually struck, look past it
+        }
+        if ('overlapping' in toiHit) {
+            // The fast body already touches this body at the step start — a zero-distance
+            // contact. Resolve the impact HERE (advance 0, arrest along the motion axis)
+            // instead of skipping it to bind a farther target's TOI (which would sweep the
+            // fast body through this one). Overlaps take priority over any positive TOI.
+            if (bestToi > 0) {
+                bestToi = 0;
+                bestNormal = { x: -dirX, y: -dirY, z: -dirZ };
+                targetIndices.length = 0;
+                targetIndices.push(targetIndex);
+            }
+            else {
+                targetIndices.push(targetIndex); // another overlapping body at zero distance
+            }
+            continue;
+        }
+        if (bestToi === 0) {
+            continue; // a zero-distance overlap already owns this step; ignore positive TOIs
+        }
+        if (toiHit.distance < bestToi - physics3d_solver_js_1.SOLVER_CONSTANTS.SLOP) {
+            bestToi = toiHit.distance;
+            bestNormal = toiHit.normal;
+            targetIndices.length = 0;
+            targetIndices.push(targetIndex);
+        }
+        else if (toiHit.distance <= bestToi + physics3d_solver_js_1.SOLVER_CONSTANTS.SLOP) {
+            // A tie at the first contact (e.g. both boxes of a seam).
+            if (toiHit.distance < bestToi) {
+                bestToi = toiHit.distance;
+                bestNormal = toiHit.normal;
+            }
+            targetIndices.push(targetIndex);
+        }
+    }
+    return targetIndices.length === 0 ? undefined : { toi: bestToi, normal: bestNormal, targetIndices };
+}
+/**
+ * Advance a fast body to its exact TOI contact and resolve the impact as a single
+ * perfectly-inelastic (restitution 0) collision between it and every body struck at that
+ * first contact: all of them are set to their common momentum-conserving normal velocity.
+ * This transfers momentum to the struck bodies and removes the fast body's approach, so
+ * the discrete step resolves a resting (not a plowing) contact — and, at a seam, sharing
+ * the impact across both boxes keeps each below the coupled relax's stability limit. A
+ * static/kinematic target has infinite mass along the normal, so the common velocity is
+ * that surface's (a hard stop). Only the normal component changes; tangential is kept.
+ */
+function applyToiResponse(fast, solverBodies, clamp) {
+    fast.p = {
+        x: clamp.prePos.x + clamp.dirX * clamp.maxAdvance,
+        y: clamp.prePos.y + clamp.dirY * clamp.maxAdvance,
+        z: clamp.prePos.z + clamp.dirZ * clamp.maxAdvance,
+    };
+    const nx = clamp.normalX;
+    const ny = clamp.normalY;
+    const nz = clamp.normalZ;
+    const normalMassAlong = (b) => {
+        const k = nx * nx * b.invMassVec.x + ny * ny * b.invMassVec.y + nz * nz * b.invMassVec.z;
+        return k > 0 ? 1 / k : Infinity; // effective mass along the contact normal
+    };
+    const setNormalVelocity = (b, vc) => {
+        const vn = b.v.x * nx + b.v.y * ny + b.v.z * nz;
+        const d = vc - vn;
+        b.v = { x: b.v.x + nx * d, y: b.v.y + ny * d, z: b.v.z + nz * d };
+    };
+    const fastMass = normalMassAlong(fast); // dynamic ⇒ finite
+    let sumMass = fastMass;
+    let sumMomentum = fastMass * (fast.v.x * nx + fast.v.y * ny + fast.v.z * nz);
+    let anyImmovable = false;
+    let immovableVn = 0;
+    for (const ti of clamp.targetIndices) {
+        const t = solverBodies[ti];
+        const tm = normalMassAlong(t);
+        if (tm === Infinity) {
+            anyImmovable = true;
+            immovableVn = t.v.x * nx + t.v.y * ny + t.v.z * nz; // static/kinematic ⇒ its surface velocity
+        }
+        else {
+            sumMass += tm;
+            sumMomentum += tm * (t.v.x * nx + t.v.y * ny + t.v.z * nz);
+        }
+    }
+    // Common post-collision normal velocity: a struck static/kinematic body pins it.
+    const vc = anyImmovable ? immovableVn : sumMomentum / sumMass;
+    // Only resolve if the fast body is actually approaching the contact (moving into it).
+    if ((fast.v.x * nx + fast.v.y * ny + fast.v.z * nz) - vc >= 0) {
+        return;
+    }
+    setNormalVelocity(fast, vc);
+    for (const ti of clamp.targetIndices) {
+        const t = solverBodies[ti];
+        if (normalMassAlong(t) !== Infinity) {
+            setNormalVelocity(t, vc);
+        }
+    }
+}
+/**
+ * Clamp a fast body's POSITION so it advances no farther than its first TOI along its
+ * intended motion. Velocity is set by the pre-solve TOI response and the discrete solver;
+ * this only removes any residual along-`dir` overshoot past the contact.
+ */
+function clampFastToToi(sb, clamp) {
+    const s = (sb.p.x - clamp.prePos.x) * clamp.dirX
+        + (sb.p.y - clamp.prePos.y) * clamp.dirY
+        + (sb.p.z - clamp.prePos.z) * clamp.dirZ;
+    if (s <= clamp.maxAdvance) {
+        return;
+    }
+    const excess = s - clamp.maxAdvance;
+    sb.p = {
+        x: sb.p.x - clamp.dirX * excess,
+        y: sb.p.y - clamp.dirY * excess,
+        z: sb.p.z - clamp.dirZ * excess,
+    };
+}
+function runRigidSolver(world, dt, gravityY, velocityIterations, substeps, joints, pairs) {
     const source = world.bodies;
     const indexById = new Map(source.map((body, index) => [body.id, index]));
     const solverBodies = source.map((body, index) => buildSolverBody(body, index));
@@ -1462,19 +1734,61 @@ function runRigidSolver(world, dt, gravityY, velocityIterations, joints) {
     })
         .filter((key) => key !== undefined);
     const noCollidePairs = new Set(noCollideKeys);
+    // Extreme-speed ccd (box3d model): flag fast bodies and find each one's exact first
+    // time-of-impact. The discrete solve runs with a small speculative margin (fast ccd
+    // bodies plow through during the step, staying finite); afterward each fast body's
+    // POSITION is clamped to its TOI so it never tunnels, while its VELOCITY is left to
+    // the solver so the next step's contact transfers momentum. Empty set ⇒ no clamp.
+    const fastClamps = computeFastCcdClamps(world, source, solverBodies, dt, indexById, noCollidePairs);
+    // Pre-solve TOI response (box3d-style, in stable body-index order): advance each fast
+    // body to its exact first contact and apply a one-shot inelastic normal impulse that
+    // transfers momentum to the struck body and arrests the approach, so the discrete step
+    // never sees the fast body plow through a coupled cluster.
+    for (const [index, clamp] of fastClamps) {
+        applyToiResponse(solverBodies[index], solverBodies, clamp);
+    }
     const result = (0, physics3d_solver_js_1.solveRigidStep)(solverBodies, {
         dt,
         gravityY,
         velocityIterations,
+        substeps,
         noCollidePairs: noCollidePairs.size > 0 ? noCollidePairs : undefined,
         warm,
+        pairs,
         joints: solverJoints,
     });
+    // Post-solve safety clamp: no fast body may end past its TOI along its motion.
+    for (const [index, clamp] of fastClamps) {
+        clampFastToToi(solverBodies[index], clamp);
+    }
     const bodies = source.map((body, index) => {
-        if (body.kind !== 'dynamic') {
+        if (body.kind === 'static') {
             return body;
         }
         const sb = solverBodies[index];
+        if (body.kind === 'kinematic') {
+            // Author-driven: the solver advanced the pose from the authored velocity
+            // and never touched the velocity, mass, or sleep state.
+            const moved = {
+                ...body,
+                x: (0, physics3d_shared_js_1.quantizeDistance)(sb.p.x),
+                y: (0, physics3d_shared_js_1.quantizeDistance)(sb.p.y),
+                z: (0, physics3d_shared_js_1.quantizeDistance)(sb.p.z),
+            };
+            if (body.orientation === undefined) {
+                // legacy quarter-turn decoration, same as the dynamic path
+                return { ...moved, ...integrateAngularState(body, dt) };
+            }
+            return {
+                ...moved,
+                orientation: {
+                    x: (0, physics3d_shared_js_1.quantizeDistance)(sb.q.x),
+                    y: (0, physics3d_shared_js_1.quantizeDistance)(sb.q.y),
+                    z: (0, physics3d_shared_js_1.quantizeDistance)(sb.q.z),
+                    w: (0, physics3d_shared_js_1.quantizeDistance)(sb.q.w),
+                },
+            };
+        }
         const mapped = {
             ...body,
             x: (0, physics3d_shared_js_1.quantizeDistance)(sb.p.x),
@@ -1577,7 +1891,7 @@ function detectContacts(bodies, keepPair) {
     return contacts.sort((left, right) => compareStrings(left.pair, right.pair));
 }
 function solveConstraints3D(bodies, constraints) {
-    const next = bodies.map((body) => ({ ...body }));
+    const next = [...bodies];
     let corrections = 0;
     for (const constraint of [...constraints].sort((left, right) => compareStrings(left.id, right.id))) {
         const aIndex = next.findIndex((body) => body.id === constraint.a);
@@ -1736,9 +2050,21 @@ function validatePhysicsBody3D(body) {
             throw new Error(`physics3d body ${id}: orientation quaternion must have non-zero length`);
         }
     }
+    if (body.shape.type === 'mesh' && body.kind === 'dynamic') {
+        throw new Error(`physics3d body ${id}: mesh collider must be static or kinematic — cook a concave dynamic body into a compound of convex hulls`);
+    }
     validatePhysicsShape3D(id, body.shape);
 }
 function validatePhysicsShape3D(id, shape) {
+    if (shape.type === 'hull') {
+        try {
+            (0, physics3d_hull_js_1.buildSolverHull)(shape.vertices);
+        }
+        catch (error) {
+            throw new Error(`physics3d body ${id}: ${error.message}`);
+        }
+        return;
+    }
     if (shape.type === 'box') {
         for (const [name, value] of [['halfX', shape.halfX], ['halfY', shape.halfY], ['halfZ', shape.halfZ]]) {
             if (!isFiniteNumber(value) || value <= 0) {
@@ -1847,6 +2173,9 @@ function shapePoseBounds(pose) {
         }
         return boundsFromPoints(boxLocalCorners(shape).map((point) => translateRotatedPoint(point, pose)));
     }
+    if (shape.type === 'hull') {
+        return boundsFromPoints(shape.vertices.map((vertex) => translateRotatedPoint(vertex, pose)));
+    }
     if (shape.type === 'mesh') {
         if (shape.vertices.length < 3 || shape.vertices.length % 3 !== 0) {
             throw new Error('3D mesh collider requires triangle-list vertices');
@@ -1972,6 +2301,14 @@ function angularGeometryProof() {
         && meshHit.some((hit) => hit.bodyId === 'rotated-mesh')
         && overlap.includes('rotated-box'));
 }
+function poseToSolverGeom(pose, index) {
+    return {
+        index,
+        p: { x: pose.x, y: pose.y, z: pose.z },
+        q: (0, physics3d_shared_js_1.quaternionFromQuarterTurns)({ x: pose.rx ?? 0, y: pose.ry ?? 0, z: pose.rz ?? 0 }),
+        shape: toSolverShape(pose.shape),
+    };
+}
 function shapesOverlap3D(left, right) {
     if (left.shape.type === 'compound') {
         return compoundChildPoses(left).some((childPose) => shapesOverlap3D(childPose, right));
@@ -1979,6 +2316,11 @@ function shapesOverlap3D(left, right) {
     if (right.shape.type === 'compound') {
         return compoundChildPoses(right).some((childPose) => shapesOverlap3D(left, childPose));
     }
+    if (left.shape.type === 'hull' || right.shape.type === 'hull') {
+        // Exact, orientation-aware: build solver geometry from each pose (mesh is
+        // one-sided and handled by generateManifold's mesh dispatch).
+        return (0, physics3d_solver_js_1.generateManifold)(poseToSolverGeom(left, 0), poseToSolverGeom(right, 1)) !== undefined;
+    }
     if (left.shape.type === 'mesh') {
         return meshOverlapsShape(left, right);
     }
@@ -2411,8 +2753,42 @@ function rayBodyDistance(body, query) {
     if (body.shape.type === 'mesh') {
         return rayMeshDistance(meshPose(bodyPose(body), body.shape), query);
     }
+    if (body.shape.type === 'hull') {
+        return rayHullBodyDistance(body, body.shape, query);
+    }
     return rayAabbDistance(toBounds(body), query);
 }
+function rayHullBodyDistance(body, shape, query) {
+    // Oriented bodies already recursed with orientation cleared. The remaining
+    // rotation is legacy quarter-turns; fold it into the ray so we can reuse the
+    // cached (identity-space) hull half-planes rather than rebuilding per query.
+    const hull = (0, physics3d_hull_js_1.buildSolverHull)(shape.vertices);
+    const local = inverseRotateQuarterTurns({ x: query.x - body.x, y: query.y - body.y, z: query.z - body.z }, body.rx ?? 0, body.ry ?? 0, body.rz ?? 0);
+    const localDir = inverseRotateQuarterTurns({ x: query.dx, y: query.dy, z: query.dz }, body.rx ?? 0, body.ry ?? 0, body.rz ?? 0);
+    const interval = (0, physics3d_hull_js_1.rayHullIntervalLocal)(local, localDir, hull);
+    if (interval === undefined) {
+        return undefined;
+    }
+    const t = Math.max(0, interval.tEnter);
+    if (t > query.maxDistance) {
+        return undefined;
+    }
+    return (0, physics3d_shared_js_1.quantizeDistance)(t);
+}
+function inverseRotateQuarterTurns(point, rx, ry, rz) {
+    // Inverse of rotateQuarterTurns: apply the opposite turns in reverse order.
+    let rotated = point;
+    for (let index = 0; index < (4 - quarterTurns(rz)) % 4; index += 1) {
+        rotated = { x: -rotated.y, y: rotated.x, z: rotated.z };
+    }
+    for (let index = 0; index < (4 - quarterTurns(ry)) % 4; index += 1) {
+        rotated = { x: rotated.z, y: rotated.y, z: -rotated.x };
+    }
+    for (let index = 0; index < (4 - quarterTurns(rx)) % 4; index += 1) {
+        rotated = { x: rotated.x, y: -rotated.z, z: rotated.y };
+    }
+    return rotated;
+}
 function shapeCastBodyDistance(body, query) {
     if (body.orientation !== undefined) {
         // Transform the cast into the body's local frame (isometry preserves the hit
@@ -2676,7 +3052,12 @@ function expandBoundsByBounds(bounds, extents) {
         maxZ: bounds.maxZ - extents.minZ,
     };
 }
+let countCandidatePairsCalls = 0;
+function __countCandidatePairsCalls() {
+    return countCandidatePairsCalls;
+}
 function countCandidatePairs(bodies) {
+    countCandidatePairsCalls += 1;
     return broadphaseCandidatePairs(bodies).length;
 }
 function detailedHitForBody(body, query, distance, castRadius) {