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

package/dist/cjs/physics3d-joints.js

@@ -14,7 +14,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSolverJoints = createSolverJoints;
 const physics3d_shared_js_1 = require("./physics3d-shared.js");
+const math_js_1 = require("./math.js");
 const JOINT_BAUMGARTE = 0.2;
+const TWO_PI = 6.283185307179586;
+// Module-level deterministic math for cone-twist cosine (vehicle precedent); the
+// generator is pure and the tables are read-only, so no cross-frame state leaks.
+const jointMath = (0, math_js_1.createDeterministicMath)();
 function requireIndex(id, jointId, indexById) {
     const index = indexById.get(id);
     if (index === undefined) {
@@ -42,13 +47,37 @@ function ballJoint(joint, aIndex, bIndex, warm, weld) {
     const state = {
         impulse: warm ? { x: warm.impulseX, y: warm.impulseY, z: warm.impulseZ } : { x: 0, y: 0, z: 0 },
         axialImpulse: 0,
-        hingeAngle: 0,
+        hingeAngle: warm?.hingeAngle ?? 0,
+        stepImpulse: { x: 0, y: 0, z: 0 },
+        stepAxial: 0,
     };
+    // Cone-twist limits (ball only). coneCos is the cosine of the swing half-angle;
+    // twist limits are stored in radians. axisA/axisB are the local twist axes.
+    const coneTwist = !weld && joint.type === 'ball'
+        && (joint.coneLimitTurns !== undefined || joint.twistMinTurns !== undefined || joint.twistMaxTurns !== undefined)
+        ? {
+            localAxisA: joint.axisA,
+            localAxisB: (joint.axisB ?? joint.axisA),
+            coneCos: joint.coneLimitTurns !== undefined
+                ? jointMath.cosTurns(Math.round(joint.coneLimitTurns * jointMath.fixedScale)) / jointMath.fixedScale
+                : undefined,
+            twistMin: joint.twistMinTurns !== undefined ? joint.twistMinTurns * TWO_PI : undefined,
+            twistMax: joint.twistMaxTurns !== undefined ? joint.twistMaxTurns * TWO_PI : undefined,
+        }
+        : undefined;
     let rA = { x: 0, y: 0, z: 0 };
     let rB = { x: 0, y: 0, z: 0 };
     let kInv = [0, 0, 0, 0, 0, 0, 0, 0, 0];
     let biasTarget = { x: 0, y: 0, z: 0 };
     let angKInv = [0, 0, 0, 0, 0, 0, 0, 0, 0];
+    let twistAxis = { x: 0, y: 1, z: 0 };
+    let swingV = { x: 0, y: 1, z: 0 };
+    let coneImpulse = 0;
+    let twistImpulse = 0;
+    const angularMassAlong = (ctx, axis) => {
+        const denom = (0, physics3d_shared_js_1.dotVec3)(axis, (0, physics3d_shared_js_1.mulMat3Vec)(ctx.invInertia[aIndex], axis)) + (0, physics3d_shared_js_1.dotVec3)(axis, (0, physics3d_shared_js_1.mulMat3Vec)(ctx.invInertia[bIndex], axis));
+        return denom === 0 ? 0 : 1 / denom;
+    };
     return {
         bodyIndices: [aIndex, bIndex],
         prepare(ctx) {
@@ -64,6 +93,12 @@ function ballJoint(joint, aIndex, bIndex, warm, weld) {
             if (weld) {
                 angKInv = (0, physics3d_shared_js_1.invertMat3)((0, physics3d_shared_js_1.mat3Sub)((0, physics3d_shared_js_1.mat3Sub)((0, physics3d_shared_js_1.mat3FromDiag)({ x: 0, y: 0, z: 0 }), scaleMat3(ctx.invInertia[aIndex], -1)), scaleMat3(ctx.invInertia[bIndex], -1)));
             }
+            if (coneTwist !== undefined) {
+                twistAxis = unit((0, physics3d_shared_js_1.rotatePointByQuat)(A.q, coneTwist.localAxisA));
+                swingV = unit((0, physics3d_shared_js_1.rotatePointByQuat)(B.q, coneTwist.localAxisB));
+                coneImpulse = 0;
+                twistImpulse = 0;
+            }
             ctx.apply(aIndex, bIndex, rA, rB, state.impulse);
         },
         iterate(ctx) {
@@ -78,16 +113,63 @@ function ballJoint(joint, aIndex, bIndex, warm, weld) {
                 const angImpulse = (0, physics3d_shared_js_1.scaleVec3)((0, physics3d_shared_js_1.mulMat3Vec)(angKInv, relOmega), -1);
                 ctx.applyAngular(aIndex, bIndex, angImpulse);
             }
+            if (coneTwist !== undefined) {
+                // Swing cone: one-sided limit on the angle between the two twist axes.
+                if (coneTwist.coneCos !== undefined) {
+                    const cosAngle = (0, physics3d_shared_js_1.dotVec3)(twistAxis, swingV);
+                    if (cosAngle < coneTwist.coneCos) {
+                        const rawAxis = (0, physics3d_shared_js_1.crossVec3)(swingV, twistAxis);
+                        const len = (0, physics3d_shared_js_1.solverSqrt)((0, physics3d_shared_js_1.dotVec3)(rawAxis, rawAxis));
+                        if (len > 1e-9) {
+                            const axis = (0, physics3d_shared_js_1.scaleVec3)(rawAxis, 1 / len);
+                            const relW = (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(B.w, A.w), axis);
+                            const mass = angularMassAlong(ctx, axis);
+                            let dCone = mass * (-relW + (JOINT_BAUMGARTE / ctx.dt) * (coneTwist.coneCos - cosAngle));
+                            const newAcc = Math.max(0, coneImpulse + dCone);
+                            dCone = newAcc - coneImpulse;
+                            coneImpulse = newAcc;
+                            ctx.applyAngular(aIndex, bIndex, (0, physics3d_shared_js_1.scaleVec3)(axis, dCone));
+                        }
+                    }
+                }
+                // Twist: min/max inequality rows about the shared twist axis (mirrors hinge).
+                if (coneTwist.twistMin !== undefined && state.hingeAngle <= coneTwist.twistMin) {
+                    const overshoot = coneTwist.twistMin - state.hingeAngle;
+                    const relW = (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(B.w, A.w), twistAxis);
+                    const mass = angularMassAlong(ctx, twistAxis);
+                    let dTwist = mass * (-relW + (JOINT_BAUMGARTE / ctx.dt) * overshoot);
+                    const newAcc = Math.max(0, twistImpulse + dTwist);
+                    dTwist = newAcc - twistImpulse;
+                    twistImpulse = newAcc;
+                    ctx.applyAngular(aIndex, bIndex, (0, physics3d_shared_js_1.scaleVec3)(twistAxis, dTwist));
+                }
+                else if (coneTwist.twistMax !== undefined && state.hingeAngle >= coneTwist.twistMax) {
+                    const overshoot = state.hingeAngle - coneTwist.twistMax;
+                    const relW = (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(B.w, A.w), twistAxis);
+                    const mass = angularMassAlong(ctx, twistAxis);
+                    let dTwist = mass * (-relW - (JOINT_BAUMGARTE / ctx.dt) * overshoot);
+                    const newAcc = Math.min(0, twistImpulse + dTwist);
+                    dTwist = newAcc - twistImpulse;
+                    twistImpulse = newAcc;
+                    ctx.applyAngular(aIndex, bIndex, (0, physics3d_shared_js_1.scaleVec3)(twistAxis, dTwist));
+                }
+            }
             // position correction on pseudo-velocities
             const relBias = ctx.biasRelativeVelocity(aIndex, bIndex, rA, rB);
             const dBias = (0, physics3d_shared_js_1.mulMat3Vec)(kInv, (0, physics3d_shared_js_1.subVec3)(biasTarget, relBias));
             ctx.applyBias(aIndex, bIndex, rA, rB, dBias);
         },
+        postSubstep(ctx) {
+            state.stepImpulse = (0, physics3d_shared_js_1.addVec3)(state.stepImpulse, state.impulse);
+            if (coneTwist !== undefined) {
+                state.hingeAngle += (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(ctx.bodies[bIndex].w, ctx.bodies[aIndex].w), twistAxis) * ctx.dt;
+            }
+        },
         emitCache() {
-            const reaction2 = (0, physics3d_shared_js_1.dotVec3)(state.impulse, state.impulse);
+            const reaction2 = (0, physics3d_shared_js_1.dotVec3)(state.stepImpulse, state.stepImpulse);
             const broken = joint.breakImpulse !== undefined && reaction2 > joint.breakImpulse * joint.breakImpulse;
             return {
-                jointId: joint.id, impulseX: state.impulse.x, impulseY: state.impulse.y, impulseZ: state.impulse.z, axialImpulse: 0, hingeAngle: 0,
+                jointId: joint.id, impulseX: state.impulse.x, impulseY: state.impulse.y, impulseZ: state.impulse.z, axialImpulse: 0, hingeAngle: coneTwist !== undefined ? state.hingeAngle : 0,
                 ...(broken ? { broken: true } : {}),
             };
         },
@@ -101,6 +183,8 @@ function hingeJoint(joint, aIndex, bIndex, warm) {
         impulse: warm ? { x: warm.impulseX, y: warm.impulseY, z: warm.impulseZ } : { x: 0, y: 0, z: 0 },
         axialImpulse: warm?.axialImpulse ?? 0,
         hingeAngle: warm?.hingeAngle ?? 0,
+        stepImpulse: { x: 0, y: 0, z: 0 },
+        stepAxial: 0,
     };
     let rA = { x: 0, y: 0, z: 0 };
     let rB = { x: 0, y: 0, z: 0 };
@@ -113,7 +197,6 @@ function hingeJoint(joint, aIndex, bIndex, warm) {
     let angMassT1 = 0;
     let angMassT2 = 0;
     let limitImpulse = 0;
-    let ctxRef;
     const angularMass = (ctx, t) => {
         const denom = (0, physics3d_shared_js_1.dotVec3)(t, (0, physics3d_shared_js_1.mulMat3Vec)(ctx.invInertia[aIndex], t)) + (0, physics3d_shared_js_1.dotVec3)(t, (0, physics3d_shared_js_1.mulMat3Vec)(ctx.invInertia[bIndex], t));
         /* istanbul ignore next -- a hinge with a real dynamic body has non-zero inverse inertia along the axis; the zero guard is defensive. */
@@ -139,7 +222,6 @@ function hingeJoint(joint, aIndex, bIndex, warm) {
             angMassT1 = angularMass(ctx, t1);
             angMassT2 = angularMass(ctx, t2);
             limitImpulse = 0;
-            ctxRef = ctx;
             ctx.apply(aIndex, bIndex, rA, rB, state.impulse);
             if (state.axialImpulse !== 0) {
                 ctx.applyAngular(aIndex, bIndex, (0, physics3d_shared_js_1.scaleVec3)(axis, state.axialImpulse));
@@ -193,14 +275,14 @@ function hingeJoint(joint, aIndex, bIndex, warm) {
                 ctx.applyAngular(aIndex, bIndex, (0, physics3d_shared_js_1.scaleVec3)(axis, dImpulse));
             }
         },
-        emitCache() {
+        postSubstep(ctx) {
             // integrate the hinge angle from the post-solve relative axial velocity
-            /* istanbul ignore else -- prepare() always runs before emitCache(), so ctxRef is defined. */
-            if (ctxRef !== undefined) {
-                const relAxial = (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(ctxRef.bodies[bIndex].w, ctxRef.bodies[aIndex].w), axis);
-                state.hingeAngle += relAxial * ctxRef.dt;
-            }
-            const reaction2 = (0, physics3d_shared_js_1.dotVec3)(state.impulse, state.impulse);
+            const relAxial = (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(ctx.bodies[bIndex].w, ctx.bodies[aIndex].w), axis);
+            state.hingeAngle += relAxial * ctx.dt;
+            state.stepImpulse = (0, physics3d_shared_js_1.addVec3)(state.stepImpulse, state.impulse);
+        },
+        emitCache() {
+            const reaction2 = (0, physics3d_shared_js_1.dotVec3)(state.stepImpulse, state.stepImpulse);
             const broken = joint.breakImpulse !== undefined && reaction2 > joint.breakImpulse * joint.breakImpulse;
             return {
                 jointId: joint.id,
@@ -224,6 +306,8 @@ function distanceJoint(joint, aIndex, bIndex, warm) {
         impulse: { x: warm?.axialImpulse ?? 0, y: 0, z: 0 },
         axialImpulse: warm?.axialImpulse ?? 0,
         hingeAngle: 0,
+        stepImpulse: { x: 0, y: 0, z: 0 },
+        stepAxial: 0,
     };
     let rA = { x: 0, y: 0, z: 0 };
     let rB = { x: 0, y: 0, z: 0 };
@@ -248,7 +332,10 @@ function distanceJoint(joint, aIndex, bIndex, warm) {
             const denom = linear + (0, physics3d_shared_js_1.dotVec3)(raxn, (0, physics3d_shared_js_1.mulMat3Vec)(ctx.invInertia[aIndex], raxn)) + (0, physics3d_shared_js_1.dotVec3)(rbxn, (0, physics3d_shared_js_1.mulMat3Vec)(ctx.invInertia[bIndex], rbxn));
             /* istanbul ignore next -- a distance joint with a real dynamic body has non-zero effective mass; the zero guard is defensive. */
             mass = denom === 0 ? 0 : 1 / denom;
-            state.axialImpulse = warm?.axialImpulse ?? 0;
+            // Warm-start the persisted axial impulse (it accumulates across substeps and
+            // is zeroed by iterate when the rope goes slack). Re-reading the frame's warm
+            // value here would drop intra-step buildup and undo the slack-rope zeroing on
+            // later substeps — mirror the spring joint, which persists axialImpulse too.
             ctx.apply(aIndex, bIndex, rA, rB, (0, physics3d_shared_js_1.scaleVec3)(n, state.axialImpulse));
         },
         iterate(ctx) {
@@ -281,8 +368,11 @@ function distanceJoint(joint, aIndex, bIndex, warm) {
                 state.axialImpulse = 0;
             }
         },
+        postSubstep() {
+            state.stepAxial += state.axialImpulse;
+        },
         emitCache() {
-            const reaction2 = state.axialImpulse * state.axialImpulse;
+            const reaction2 = state.stepAxial * state.stepAxial;
             const broken = joint.breakImpulse !== undefined && reaction2 > joint.breakImpulse * joint.breakImpulse;
             return {
                 jointId: joint.id, impulseX: 0, impulseY: 0, impulseZ: 0, axialImpulse: state.axialImpulse, hingeAngle: 0,
@@ -296,6 +386,8 @@ function prismaticJoint(joint, aIndex, bIndex, warm) {
         impulse: warm ? { x: warm.impulseX, y: warm.impulseY, z: warm.impulseZ } : { x: 0, y: 0, z: 0 },
         axialImpulse: warm?.axialImpulse ?? 0,
         hingeAngle: 0,
+        stepImpulse: { x: 0, y: 0, z: 0 },
+        stepAxial: 0,
     };
     let rA = { x: 0, y: 0, z: 0 };
     let rB = { x: 0, y: 0, z: 0 };
@@ -398,10 +490,13 @@ function prismaticJoint(joint, aIndex, bIndex, warm) {
                 ctx.apply(aIndex, bIndex, rA, rB, (0, physics3d_shared_js_1.scaleVec3)(axis, dLambda));
             }
         },
+        postSubstep() {
+            state.stepImpulse = (0, physics3d_shared_js_1.addVec3)(state.stepImpulse, state.impulse);
+        },
         emitCache() {
             // perpendicular reaction only — the axialImpulse is the motor accumulator,
             // and motors/limits are excluded from breaking.
-            const reaction2 = (0, physics3d_shared_js_1.dotVec3)(state.impulse, state.impulse);
+            const reaction2 = (0, physics3d_shared_js_1.dotVec3)(state.stepImpulse, state.stepImpulse);
             const broken = joint.breakImpulse !== undefined && reaction2 > joint.breakImpulse * joint.breakImpulse;
             return {
                 jointId: joint.id,
@@ -420,16 +515,18 @@ function springJoint(joint, aIndex, bIndex, warm) {
         impulse: { x: 0, y: 0, z: 0 },
         axialImpulse: warm?.axialImpulse ?? 0,
         hingeAngle: 0,
+        stepImpulse: { x: 0, y: 0, z: 0 },
+        stepAxial: 0,
     };
     const omega = 6.283185307179586 * joint.frequencyHz;
     let rA = { x: 0, y: 0, z: 0 };
     let rB = { x: 0, y: 0, z: 0 };
     let n = { x: 0, y: 1, z: 0 };
-    let mass = 0;
+    let massEff = 0;
     let length = 0;
-    let gamma = 0;
-    let bias = 0;
-    let massSoft = 0;
+    let biasRate = 0;
+    let massScale = 1;
+    let impulseScale = 0;
     return {
         bodyIndices: [aIndex, bIndex],
         prepare(ctx) {
@@ -446,16 +543,19 @@ function springJoint(joint, aIndex, bIndex, warm) {
             const imB = ctx.invMass[bIndex];
             const linear = n.x * n.x * (imA.x + imB.x) + n.y * n.y * (imA.y + imB.y) + n.z * n.z * (imA.z + imB.z);
             const denom = linear + (0, physics3d_shared_js_1.dotVec3)(raxn, (0, physics3d_shared_js_1.mulMat3Vec)(ctx.invInertia[aIndex], raxn)) + (0, physics3d_shared_js_1.dotVec3)(rbxn, (0, physics3d_shared_js_1.mulMat3Vec)(ctx.invInertia[bIndex], rbxn));
-            mass = denom === 0 ? 0 : 1 / denom;
-            // Box2D soft-constraint coefficients from frequency + damping ratio.
-            const c = 2 * mass * joint.dampingRatio * omega;
-            const k = mass * omega * omega;
-            const softDenom = c + ctx.dt * k;
-            gamma = softDenom === 0 ? 0 : 1 / (ctx.dt * softDenom);
-            const beta = ctx.dt * k * gamma;
-            bias = (beta / ctx.dt) * (length - joint.restLength);
-            massSoft = mass === 0 ? 0 : 1 / (1 / mass + gamma);
-            state.axialImpulse = warm?.axialImpulse ?? 0;
+            massEff = denom === 0 ? 0 : 1 / denom;
+            // Box2D-v3 soft-constraint coefficients: substep-invariant (biasRate stays
+            // bounded as h -> 0), unlike the gamma/beta form whose 1/dt bias diverges
+            // under sub-stepping. hertz = frequencyHz, zeta = dampingRatio, h = ctx.dt.
+            const h = ctx.dt;
+            const a1 = 2 * joint.dampingRatio + omega * h;
+            const a2 = h * omega * a1;
+            const a3 = 1 / (1 + a2);
+            /* istanbul ignore next -- frequencyHz > 0 is validated and dampingRatio >= 0, so a1 = 2*zeta + omega*h is always positive. */
+            biasRate = a1 === 0 ? 0 : omega / a1;
+            massScale = a2 * a3;
+            impulseScale = a3;
+            // warm start: axialImpulse persists across substeps (per-substep magnitude).
             ctx.apply(aIndex, bIndex, rA, rB, (0, physics3d_shared_js_1.scaleVec3)(n, state.axialImpulse));
         },
         iterate(ctx) {
@@ -463,12 +563,20 @@ function springJoint(joint, aIndex, bIndex, warm) {
             const B = ctx.bodies[bIndex];
             const relVel = (0, physics3d_shared_js_1.subVec3)((0, physics3d_shared_js_1.addVec3)(B.v, (0, physics3d_shared_js_1.crossVec3)(B.w, rB)), (0, physics3d_shared_js_1.addVec3)(A.v, (0, physics3d_shared_js_1.crossVec3)(A.w, rA)));
             const cdot = (0, physics3d_shared_js_1.dotVec3)(relVel, n);
-            const dLambda = -massSoft * (cdot + bias + gamma * state.axialImpulse);
+            const dLambda = -massScale * massEff * (cdot + biasRate * (length - joint.restLength)) - impulseScale * state.axialImpulse;
             state.axialImpulse += dLambda;
             ctx.apply(aIndex, bIndex, rA, rB, (0, physics3d_shared_js_1.scaleVec3)(n, dLambda));
         },
+        postSubstep() {
+            state.stepAxial += state.axialImpulse;
+        },
         emitCache() {
-            return { jointId: joint.id, impulseX: 0, impulseY: 0, impulseZ: 0, axialImpulse: state.axialImpulse, hingeAngle: 0 };
+            const reaction2 = state.stepAxial * state.stepAxial;
+            const broken = joint.breakImpulse !== undefined && reaction2 > joint.breakImpulse * joint.breakImpulse;
+            return {
+                jointId: joint.id, impulseX: 0, impulseY: 0, impulseZ: 0, axialImpulse: state.axialImpulse, hingeAngle: 0,
+                ...(broken ? { broken: true } : {}),
+            };
         },
     };
 }
@@ -477,6 +585,8 @@ function grabJoint(joint, bodyIndex, warm) {
         impulse: warm ? { x: warm.impulseX, y: warm.impulseY, z: warm.impulseZ } : { x: 0, y: 0, z: 0 },
         axialImpulse: 0,
         hingeAngle: 0,
+        stepImpulse: { x: 0, y: 0, z: 0 },
+        stepAxial: 0,
     };
     let r = { x: 0, y: 0, z: 0 };
     let kInv = [0, 0, 0, 0, 0, 0, 0, 0, 0];
@@ -538,6 +648,28 @@ function validateJoint(joint) {
     if ('breakImpulse' in joint && joint.breakImpulse !== undefined && (!Number.isFinite(joint.breakImpulse) || joint.breakImpulse <= 0)) {
         throw new Error(`physics3d joint ${joint.id}: breakImpulse must be positive`);
     }
+    if (joint.type === 'ball') {
+        const hasLimit = joint.coneLimitTurns !== undefined || joint.twistMinTurns !== undefined || joint.twistMaxTurns !== undefined;
+        if (hasLimit) {
+            if (joint.axisA === undefined || !Number.isFinite(joint.axisA.x) || !Number.isFinite(joint.axisA.y) || !Number.isFinite(joint.axisA.z) || (0, physics3d_shared_js_1.dotVec3)(joint.axisA, joint.axisA) === 0) {
+                throw new Error(`physics3d joint ${joint.id}: cone-twist limits require a non-zero finite axisA`);
+            }
+            if (joint.axisB !== undefined && (!Number.isFinite(joint.axisB.x) || !Number.isFinite(joint.axisB.y) || !Number.isFinite(joint.axisB.z) || (0, physics3d_shared_js_1.dotVec3)(joint.axisB, joint.axisB) === 0)) {
+                throw new Error(`physics3d joint ${joint.id}: cone-twist axisB must be non-zero finite`);
+            }
+        }
+        if (joint.coneLimitTurns !== undefined && (!Number.isFinite(joint.coneLimitTurns) || joint.coneLimitTurns <= 0 || joint.coneLimitTurns > 0.5)) {
+            throw new Error(`physics3d joint ${joint.id}: coneLimitTurns must be in (0, 0.5]`);
+        }
+        for (const [name, value] of [['twistMinTurns', joint.twistMinTurns], ['twistMaxTurns', joint.twistMaxTurns]]) {
+            if (value !== undefined && (!Number.isFinite(value) || value < -0.5 || value > 0.5)) {
+                throw new Error(`physics3d joint ${joint.id}: ${name} must be in [-0.5, 0.5]`);
+            }
+        }
+        if (joint.twistMinTurns !== undefined && joint.twistMaxTurns !== undefined && joint.twistMinTurns > joint.twistMaxTurns) {
+            throw new Error(`physics3d joint ${joint.id}: twistMinTurns must not exceed twistMaxTurns`);
+        }
+    }
     if (joint.type === 'hinge') {
         if ((0, physics3d_shared_js_1.dotVec3)(joint.axisA, joint.axisA) === 0) {
             throw new Error(`physics3d joint ${joint.id}: hinge axisA must be non-zero`);

package/dist/cjs/physics3d-recipes.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeterministicRagdoll3DFixture = runDeterministicRagdoll3DFixture;
+exports.runDeterministicRigidWheelVehicle3DFixture = runDeterministicRigidWheelVehicle3DFixture;
+const canonical_js_1 = require("./canonical.js");
+const physics3d_js_1 = require("./physics3d.js");
+const physics3d_shared_js_1 = require("./physics3d-shared.js");
+const math_js_1 = require("./math.js");
+const RAGDOLL_GRAVITY_Y = -0.02;
+const VEHICLE_GRAVITY_Y = -0.02;
+const IDENT = { x: 0, y: 0, z: 0, w: 1 };
+// Deterministic fixed-point trig for per-tick wheel steering (vehicle precedent).
+const recipeMath = (0, math_js_1.createDeterministicMath)();
+function upDot(orientation) {
+    /* istanbul ignore next -- fixture bodies always carry an orientation. */
+    const q = orientation ?? IDENT;
+    return 1 - 2 * (q.x * q.x + q.z * q.z);
+}
+function ragdollBodies() {
+    const box = (id, x, y, z, half, mass) => ({
+        id, kind: 'dynamic', x, y, z, vx: 0, vy: 0, vz: 0, orientation: IDENT, angularVel: { x: 0, y: 0, z: 0 },
+        shape: { type: 'box', halfX: half.x, halfY: half.y, halfZ: half.z }, layer: 1, mask: 1, material: { friction: 6, restitution: 0 }, mass,
+    });
+    const capsule = (id, x, y, z, radius, halfHeight, mass) => ({
+        id, kind: 'dynamic', x, y, z, vx: 0, vy: 0, vz: 0, orientation: IDENT, angularVel: { x: 0, y: 0, z: 0 },
+        shape: { type: 'capsule', radius, halfHeight }, layer: 1, mask: 1, material: { friction: 6, restitution: 0 }, mass,
+    });
+    return [
+        { id: 'floor', kind: 'static', x: 0, y: -1, z: 0, vx: 0, vy: 0, vz: 0, shape: { type: 'box', halfX: 40, halfY: 1, halfZ: 40 }, layer: 1, mask: 1, material: { friction: 10, restitution: 0 } },
+        box('torso', 0, 4, 0, { x: 0.4, y: 0.6, z: 0.25 }, 4),
+        box('head', 0, 4.85, 0, { x: 0.25, y: 0.25, z: 0.25 }, 1),
+        capsule('arm-l', -0.4, 4.1, 0, 0.15, 0.5, 1),
+        capsule('arm-r', 0.4, 4.1, 0, 0.15, 0.5, 1),
+        capsule('leg-l', -0.2, 2.8, 0, 0.18, 0.6, 1.5),
+        capsule('leg-r', 0.2, 2.8, 0, 0.18, 0.6, 1.5),
+    ];
+}
+function ragdollJoints() {
+    return [
+        { id: 'neck', type: 'ball', a: 'torso', b: 'head', anchorA: { x: 0, y: 0.6, z: 0 }, anchorB: { x: 0, y: -0.25, z: 0 }, axisA: { x: 0, y: 1, z: 0 }, coneLimitTurns: 0.1, twistMinTurns: -0.05, twistMaxTurns: 0.05, disableCollision: true },
+        { id: 'shoulder-l', type: 'ball', a: 'torso', b: 'arm-l', anchorA: { x: -0.4, y: 0.6, z: 0 }, anchorB: { x: 0, y: 0.5, z: 0 }, axisA: { x: 0, y: 1, z: 0 }, coneLimitTurns: 0.2, disableCollision: true },
+        { id: 'shoulder-r', type: 'ball', a: 'torso', b: 'arm-r', anchorA: { x: 0.4, y: 0.6, z: 0 }, anchorB: { x: 0, y: 0.5, z: 0 }, axisA: { x: 0, y: 1, z: 0 }, coneLimitTurns: 0.2, disableCollision: true },
+        { id: 'hip-l', type: 'hinge', a: 'torso', b: 'leg-l', anchorA: { x: -0.2, y: -0.6, z: 0 }, anchorB: { x: 0, y: 0.6, z: 0 }, axisA: { x: 1, y: 0, z: 0 }, minAngle: -0.3, maxAngle: 2.0, disableCollision: true },
+        { id: 'hip-r', type: 'hinge', a: 'torso', b: 'leg-r', anchorA: { x: 0.2, y: -0.6, z: 0 }, anchorB: { x: 0, y: 0.6, z: 0 }, axisA: { x: 1, y: 0, z: 0 }, minAngle: -0.3, maxAngle: 2.0, disableCollision: true },
+    ];
+}
+function worldAnchor(world, id, local) {
+    const body = world.bodies.find((candidate) => candidate.id === id);
+    /* istanbul ignore next -- fixture joints only ever name bodies the fixture authored. */
+    if (body === undefined) {
+        throw new Error(`ragdoll fixture: unknown body ${id}`);
+    }
+    /* istanbul ignore next -- every fixture body is authored with an orientation. */
+    const rotated = (0, physics3d_shared_js_1.rotatePointByQuat)(body.orientation ?? IDENT, local);
+    return { x: body.x + rotated.x, y: body.y + rotated.y, z: body.z + rotated.z };
+}
+function runRagdollLoop(bodies, joints, frames) {
+    let world = (0, physics3d_js_1.createDeterministicPhysicsWorld3D)(bodies);
+    const snapshotFrame = Math.floor(frames / 2);
+    let snapshot = world;
+    for (let frame = 0; frame < frames; frame += 1) {
+        if (frame === snapshotFrame) {
+            snapshot = (0, canonical_js_1.cloneCanonical)(world);
+        }
+        world = (0, physics3d_js_1.stepDeterministicPhysicsWorld3D)(world, { gravityY: RAGDOLL_GRAVITY_Y, joints, computeChecksum: false }).world;
+    }
+    return { world, snapshot, snapshotFrame };
+}
+function runDeterministicRagdoll3DFixture(frames = 600) {
+    const bodies = ragdollBodies();
+    const joints = ragdollJoints();
+    const main = runRagdollLoop(bodies, joints, frames);
+    let restored = main.snapshot;
+    for (let frame = main.snapshotFrame; frame < frames; frame += 1) {
+        restored = (0, physics3d_js_1.stepDeterministicPhysicsWorld3D)(restored, { gravityY: RAGDOLL_GRAVITY_Y, joints, computeChecksum: false }).world;
+    }
+    const permuted = runRagdollLoop([...bodies].reverse(), [...joints].reverse(), frames);
+    const dyn = main.world.bodies.filter((body) => body.kind === 'dynamic');
+    let maxFinalSpeed = 0;
+    let maxFinalSpin = 0;
+    for (const body of dyn) {
+        maxFinalSpeed = Math.max(maxFinalSpeed, Math.abs(body.vx), Math.abs(body.vy), Math.abs(body.vz));
+        /* istanbul ignore next -- every fixture body is authored with an angularVel. */
+        const av = body.angularVel ?? { x: 0, y: 0, z: 0 };
+        maxFinalSpin = Math.max(maxFinalSpin, Math.abs(av.x), Math.abs(av.y), Math.abs(av.z));
+    }
+    let maxJointGap = 0;
+    for (const joint of joints) {
+        /* istanbul ignore next -- the ragdoll authors only ball/hinge joints; grab joints carry no anchor pair. */
+        if (joint.type === 'grab') {
+            continue;
+        }
+        const anchorA = worldAnchor(main.world, joint.a, joint.anchorA);
+        const anchorB = worldAnchor(main.world, joint.b, joint.anchorB);
+        const gap = Math.hypot(anchorA.x - anchorB.x, anchorA.y - anchorB.y, anchorA.z - anchorB.z);
+        maxJointGap = Math.max(maxJointGap, gap);
+    }
+    const brokenJoints = main.world.jointCache.filter((entry) => entry.broken === true).length;
+    const checksum = (0, canonical_js_1.defaultChecksum)(main.world);
+    return {
+        checksum,
+        restoredChecksum: (0, canonical_js_1.defaultChecksum)(restored),
+        permutedChecksum: (0, canonical_js_1.defaultChecksum)(permuted.world),
+        rollbackEquivalent: checksum === (0, canonical_js_1.defaultChecksum)(restored),
+        stableUnderAuthoringOrderPermutation: checksum === (0, canonical_js_1.defaultChecksum)(permuted.world),
+        maxFinalSpeed,
+        maxFinalSpin,
+        bodies: dyn.length,
+        maxJointGap,
+        brokenJoints,
+    };
+}
+// Rigid-wheel car: a chassis with four sphere wheels driven by hinge motors —
+// no raycast controller, just the rigid solver. The `angularDamping: 1` on the
+// wheels is load-bearing: the default 0.98 bleeds wheel spin and the car crawls.
+const WHEEL_OFFSETS = [
+    { id: 'wheel-fl', x: -0.9, z: 1.6, steered: true },
+    { id: 'wheel-fr', x: 0.9, z: 1.6, steered: true },
+    { id: 'wheel-rl', x: -0.9, z: -1.6, steered: false },
+    { id: 'wheel-rr', x: 0.9, z: -1.6, steered: false },
+];
+function rigidWheelBodies() {
+    const bodies = [
+        { id: 'floor', kind: 'static', x: 0, y: -1, z: 0, vx: 0, vy: 0, vz: 0, shape: { type: 'box', halfX: 60, halfY: 1, halfZ: 60 }, layer: 1, mask: 1, material: { friction: 10, restitution: 0 } },
+        { id: 'chassis', kind: 'dynamic', x: 0, y: 1, z: 0, vx: 0, vy: 0, vz: 0, orientation: IDENT, angularVel: { x: 0, y: 0, z: 0 }, shape: { type: 'box', halfX: 0.9, halfY: 0.25, halfZ: 1.6 }, layer: 1, mask: 1, material: { friction: 4, restitution: 0 }, mass: 8 },
+    ];
+    for (const wheel of WHEEL_OFFSETS) {
+        bodies.push({ id: wheel.id, kind: 'dynamic', x: wheel.x, y: 0.5, z: wheel.z, vx: 0, vy: 0, vz: 0, orientation: IDENT, angularVel: { x: 0, y: 0, z: 0 }, shape: { type: 'sphere', radius: 0.5 }, layer: 1, mask: 1, material: { friction: 10, restitution: 0 }, mass: 0.5, angularDamping: 1 });
+    }
+    return bodies;
+}
+// Rotate the spin axis (world +x) about world +y by `steerTurns` so a steered
+// front wheel rolls at an angle. Deterministic fixed-point trig, quantized.
+function steerAxis(steerTurns) {
+    const fixed = Math.round(steerTurns * recipeMath.fixedScale);
+    const cos = recipeMath.cosTurns(fixed) / recipeMath.fixedScale;
+    const sin = recipeMath.sinTurns(fixed) / recipeMath.fixedScale;
+    return { x: cos, y: 0, z: -sin };
+}
+function rigidWheelJoints(steerTurns) {
+    return WHEEL_OFFSETS.map((wheel) => ({
+        id: `axle-${wheel.id}`,
+        type: 'hinge',
+        a: 'chassis',
+        b: wheel.id,
+        anchorA: { x: wheel.x, y: -0.5, z: wheel.z },
+        anchorB: { x: 0, y: 0, z: 0 },
+        axisA: wheel.steered ? steerAxis(steerTurns) : { x: 1, y: 0, z: 0 },
+        motorSpeed: -0.15,
+        maxMotorTorque: 0.4,
+        disableCollision: true,
+    }));
+}
+// Straight until frame 300, steer left through frame 450, then straight again.
+function steerForFrame(frame) {
+    return frame >= 300 && frame < 450 ? 0.03 : 0;
+}
+function runRigidWheelLoop(bodies, frames) {
+    let world = (0, physics3d_js_1.createDeterministicPhysicsWorld3D)(bodies);
+    const snapshotFrame = Math.floor(frames / 2);
+    let snapshot = world;
+    let minUpDot = 1;
+    for (let frame = 0; frame < frames; frame += 1) {
+        if (frame === snapshotFrame) {
+            snapshot = (0, canonical_js_1.cloneCanonical)(world);
+        }
+        world = (0, physics3d_js_1.stepDeterministicPhysicsWorld3D)(world, { gravityY: VEHICLE_GRAVITY_Y, joints: rigidWheelJoints(steerForFrame(frame)), computeChecksum: false }).world;
+        const chassis = world.bodies.find((body) => body.id === 'chassis');
+        /* istanbul ignore else -- the chassis is authored by the fixture and never removed. */
+        if (chassis !== undefined) {
+            minUpDot = Math.min(minUpDot, upDot(chassis.orientation));
+        }
+    }
+    return { world, snapshot, snapshotFrame, minUpDot };
+}
+function runDeterministicRigidWheelVehicle3DFixture(frames = 600) {
+    const bodies = rigidWheelBodies();
+    const main = runRigidWheelLoop(bodies, frames);
+    let restored = main.snapshot;
+    for (let frame = main.snapshotFrame; frame < frames; frame += 1) {
+        restored = (0, physics3d_js_1.stepDeterministicPhysicsWorld3D)(restored, { gravityY: VEHICLE_GRAVITY_Y, joints: rigidWheelJoints(steerForFrame(frame)), computeChecksum: false }).world;
+    }
+    const permuted = runRigidWheelLoop([...bodies].reverse(), frames);
+    const chassis = main.world.bodies.find((body) => body.id === 'chassis');
+    const checksum = (0, canonical_js_1.defaultChecksum)(main.world);
+    return {
+        checksum,
+        restoredChecksum: (0, canonical_js_1.defaultChecksum)(restored),
+        permutedChecksum: (0, canonical_js_1.defaultChecksum)(permuted.world),
+        rollbackEquivalent: checksum === (0, canonical_js_1.defaultChecksum)(restored),
+        stableUnderAuthoringOrderPermutation: checksum === (0, canonical_js_1.defaultChecksum)(permuted.world),
+        forwardDistance: chassis.z,
+        lateralDistance: Math.abs(chassis.x),
+        minChassisUpDot: main.minUpDot,
+        bodies: main.world.bodies.filter((body) => body.kind === 'dynamic').length,
+    };
+}

package/dist/cjs/physics3d-shared.js

@@ -81,6 +81,12 @@ function solverSqrt(value) {
     if (value <= 0) {
         return 0;
     }
+    // Non-finite guard: `while (magnitude >= 4) magnitude /= 4` never terminates for
+    // Infinity (Inf/4 === Inf). Returning value keeps sqrt(Inf) = Inf / sqrt(NaN) = NaN
+    // without spinning, so a diverged body surfaces as a bad checksum, not a hang.
+    if (!Number.isFinite(value)) {
+        return value;
+    }
     let estimate = 1;
     let magnitude = value;
     while (magnitude >= 4) {