@jgengine/core 0.11.0 → 0.13.0

package/dist/physics/kinematicVehicle.js

@@ -2,6 +2,7 @@ import { steerYaw } from "../movement/steering.js";
 import { DEFAULT_GRIP_CURVE, sampleGripCurve } from "./vehicleBody.js";
 export function createKinematicVehicle(tuning, options = {}) {
     const grip = tuning.grip ?? DEFAULT_GRIP_CURVE;
+    const chassis = tuning.chassis;
     const rollingResistance = tuning.rollingResistance ?? 0;
     const surfaceFriction = options.surfaceFriction ?? (() => 1);
     const dragAt = options.dragAt ?? (() => 0);
@@ -12,6 +13,14 @@ export function createKinematicVehicle(tuning, options = {}) {
     let heading = options.heading ?? 0;
     let vx = 0;
     let vz = 0;
+    let gearIndex = 0;
+    let rpm = tuning.powertrain?.idleRpm ?? 0;
+    let shiftRemaining = 0;
+    let steerAngle = 0;
+    let yawRate = 0;
+    let previousForwardSpeed = 0;
+    let bodyPitch = 0;
+    let bodyRoll = 0;
     function forward() {
         return [Math.sin(heading), Math.cos(heading)];
     }
@@ -22,18 +31,100 @@ export function createKinematicVehicle(tuning, options = {}) {
             const turnRate = tuning.turnRate * (modifiers?.turnRateScale ?? 1);
             const [fx0, fz0] = forward();
             const speed = vx * fx0 + vz * fz0;
-            const steerScale = Math.min(1, Math.abs(speed) / tuning.turnSpeedRef);
-            const direction = speed >= 0 ? 1 : -1;
-            heading = steerYaw(heading, axis.steer * steerScale * direction, turnRate, dt);
+            if (tuning.steering === undefined) {
+                const steerScale = Math.min(1, Math.abs(speed) / tuning.turnSpeedRef);
+                const direction = speed >= 0 ? 1 : -1;
+                heading = steerYaw(heading, axis.steer * steerScale * direction, turnRate, dt);
+                yawRate = dt > 0 ? -axis.steer * steerScale * direction * turnRate : 0;
+                steerAngle = axis.steer;
+            }
+            else {
+                const steering = tuning.steering;
+                const speedBlend = Math.min(1, Math.abs(speed) / Math.max(0.001, steering.highSpeedAt));
+                const lock = steering.maxAngle + (steering.highSpeedAngle - steering.maxAngle) * speedBlend;
+                const targetAngle = axis.steer * lock * (modifiers?.turnRateScale ?? 1);
+                const response = 1 - Math.exp(-Math.max(0, steering.response) * Math.max(0, dt));
+                steerAngle += (targetAngle - steerAngle) * response;
+                const targetYaw = Math.abs(speed) < 0.05 ? 0 : -(speed / Math.max(0.1, steering.wheelbase)) * Math.tan(steerAngle);
+                const yawResponse = 1 - Math.exp(-Math.max(0, steering.yawDamping ?? 10) * Math.max(0, dt));
+                yawRate += (targetYaw - yawRate) * yawResponse;
+                heading += yawRate * dt;
+            }
             const [fx, fz] = forward();
             let accel = 0;
-            if (axis.throttle > 0 && speed < topSpeed)
-                accel += axis.throttle * engineAccel;
+            let tractionLimited = false;
+            let absActive = false;
+            let wheelspin = false;
+            // Powertrain state tracks wheel speed EVERY tick (not just under throttle): the engine keeps
+            // spinning with the wheels, so rpm, gear and downshifts stay live while coasting or braking. That
+            // is what makes engine braking below gear-dependent. Drive torque itself is still applied only on
+            // throttle; `gearLeverage` (current ratio / top-gear ratio) is `1` in top gear and grows in the
+            // low gears the car downshifts into as it slows.
+            let torqueFactor = 1;
+            let gearLeverage = 1;
+            if (tuning.powertrain !== undefined) {
+                const powertrain = tuning.powertrain;
+                shiftRemaining = Math.max(0, shiftRemaining - dt);
+                const ratio = powertrain.gears[Math.min(gearIndex, powertrain.gears.length - 1)] ?? 1;
+                const topGearRatio = powertrain.gears[powertrain.gears.length - 1] ?? ratio;
+                gearLeverage = topGearRatio > 0 ? Math.min(ENGINE_BRAKE_MAX_LEVERAGE, ratio / topGearRatio) : 1;
+                const wheelRpm = Math.abs(speed) / Math.max(0.01, powertrain.wheelRadius) * 60 / (Math.PI * 2);
+                rpm = Math.max(powertrain.idleRpm, Math.min(powertrain.redlineRpm, wheelRpm * ratio * powertrain.finalDrive));
+                if (shiftRemaining <= 0 && rpm >= powertrain.shiftUpRpm && gearIndex < powertrain.gears.length - 1) {
+                    gearIndex += 1;
+                    shiftRemaining = powertrain.shiftSeconds;
+                }
+                else if (shiftRemaining <= 0 && rpm <= powertrain.shiftDownRpm && gearIndex > 0) {
+                    gearIndex -= 1;
+                    shiftRemaining = powertrain.shiftSeconds;
+                }
+                const normalizedRpm = (rpm - powertrain.idleRpm) / Math.max(1, powertrain.redlineRpm - powertrain.idleRpm);
+                const torque = sampleGripCurve(powertrain.torqueCurve, normalizedRpm);
+                torqueFactor = torque * (shiftRemaining > 0 ? 0.32 : 1);
+            }
+            if (axis.throttle > 0 && speed < topSpeed) {
+                accel += chassis === undefined
+                    ? axis.throttle * engineAccel * torqueFactor
+                    : (axis.throttle * chassis.engineForce * (modifiers?.accelScale ?? 1) * torqueFactor) / chassis.massKg;
+            }
             if (axis.brake > 0) {
-                if (speed > 0.2)
-                    accel -= axis.brake * tuning.brakeAccel;
-                else if (speed > -tuning.reverseSpeed)
-                    accel -= axis.brake * engineAccel;
+                if (speed > 0.2) {
+                    const abs = tuning.dynamics?.abs ?? 0;
+                    const brakeScale = Math.max(0.15, 1 - abs * Math.max(0, Math.abs(speed) / Math.max(1, topSpeed) - 0.72));
+                    absActive = brakeScale < 0.999;
+                    accel -= chassis === undefined
+                        ? axis.brake * tuning.brakeAccel * brakeScale
+                        : (axis.brake * chassis.brakeForce * brakeScale) / chassis.massKg;
+                }
+                else if (speed > -tuning.reverseSpeed) {
+                    accel -= chassis === undefined
+                        ? axis.brake * engineAccel
+                        : (axis.brake * chassis.engineForce * (modifiers?.accelScale ?? 1)) / chassis.massKg;
+                }
+            }
+            const traction = tuning.dynamics?.tractionControl ?? 0;
+            if (traction > 0 && Math.abs(speed) > 0.5) {
+                const lateral = Math.abs(-vx * fz + vz * fx);
+                const excess = Math.max(0, lateral / (Math.abs(speed) + 1) - 0.18);
+                if (excess > 0) {
+                    accel *= Math.max(0.2, 1 - excess * traction * 3);
+                    tractionLimited = true;
+                }
+            }
+            // Coast resistance for the mass-and-force chassis (#1051) — derived from the vehicle's own weight,
+            // gravity, and gearing, never a flat "brake force" constant. Two weight-based terms:
+            //   • rolling resistance  F = μ_rr · m · g                    (always, the road-load floor)
+            //   • engine braking      F = μ_eb · m · g · gearLeverage     (throttle lifted, in gear)
+            // Engine braking is routed through the CURRENT gear, so it strengthens as the car downshifts toward
+            // a stop — exactly like lifting off in a real drivetrain. Both are forces (∝ m·g) whose per-mass
+            // deceleration is weight-independent and gear-scaled; the per-tick decel is capped so coasting can
+            // never push the car backwards.
+            if (chassis !== undefined && dt > 0 && Math.abs(speed) > 1e-4) {
+                let resistDecel = ROLLING_RESISTANCE_COEFFICIENT * GRAVITY;
+                if (axis.throttle <= 0 && tuning.powertrain !== undefined) {
+                    resistDecel += ENGINE_BRAKE_COEFFICIENT * GRAVITY * gearLeverage;
+                }
+                accel -= Math.sign(speed) * Math.min(resistDecel, Math.abs(speed) / dt);
             }
             vx += fx * accel * dt;
             vz += fz * accel * dt;
@@ -42,11 +133,41 @@ export function createKinematicVehicle(tuning, options = {}) {
             const surface = surfaceFriction(x, z);
             const slip = Math.abs(lateralSpeed) / (Math.abs(forwardSpeed) + 1);
             const handbrakeFactor = 1 - axis.handbrake * (1 - tuning.handbrakeGrip);
-            const gripValue = sampleGripCurve(grip, slip) * surface * handbrakeFactor;
+            const downforce = 1 + (tuning.dynamics?.downforce ?? 0) * Math.min(1, Math.abs(forwardSpeed) / Math.max(1, topSpeed));
+            const gripValue = sampleGripCurve(grip, slip) * surface * handbrakeFactor * downforce;
             const keep = Math.max(0, 1 - gripValue * tuning.gripStrength * dt);
-            const keptLateral = lateralSpeed * keep;
+            const stability = tuning.dynamics?.stabilityControl ?? 0;
+            let keptLateral = lateralSpeed * keep * Math.max(0, 1 - stability * Math.abs(axis.steer) * dt);
+            if (chassis !== undefined) {
+                // Friction budget (#1051): total tire force F = μeff * m * g, with μeff = tireGrip * gripValue
+                // (grip curve * surface * handbrake * downforce). Lateral load transfer (|centripetal accel| *
+                // comHeight / (trackWidth * g), capped ~0.6) shrinks the lateral share so tall/narrow chassis wash
+                // out earlier. Lateral consumes its capped share first; only the remainder feeds drive/brake.
+                const capacity = chassis.tireGrip * gripValue * chassis.massKg * GRAVITY;
+                const transfer = Math.min(0.6, (Math.abs(yawRate * forwardSpeed) * chassis.comHeight) / (Math.max(0.1, chassis.trackWidth) * GRAVITY));
+                const lateralCapacity = capacity * (1 - 0.5 * transfer);
+                const reductionWanted = lateralSpeed - keptLateral;
+                const maxReduction = dt > 0 ? (lateralCapacity * dt) / chassis.massKg : 0;
+                let reductionActual = reductionWanted;
+                if (Math.abs(reductionWanted) > maxReduction) {
+                    reductionActual = Math.sign(reductionWanted) * maxReduction;
+                    keptLateral = lateralSpeed - reductionActual;
+                }
+                const lateralForceUsed = dt > 0 ? (chassis.massKg * Math.abs(reductionActual)) / dt : 0;
+                const remainingLong = Math.max(0, capacity - lateralForceUsed);
+                if (chassis.massKg * Math.abs(accel) > remainingLong) {
+                    const actualAccel = (Math.sign(accel) * remainingLong) / chassis.massKg;
+                    forwardSpeed -= (accel - actualAccel) * dt;
+                    if (accel > 0 && axis.throttle > 0)
+                        wheelspin = true;
+                }
+            }
             if (rollingResistance > 0)
                 forwardSpeed *= Math.max(0, 1 - rollingResistance * dt);
+            const aerodynamicDrag = tuning.dynamics?.aerodynamicDrag ?? 0;
+            if (aerodynamicDrag > 0) {
+                forwardSpeed *= 1 / (1 + aerodynamicDrag * Math.abs(forwardSpeed) * dt);
+            }
             vx = fx * forwardSpeed - fz * keptLateral;
             vz = fz * forwardSpeed + fx * keptLateral;
             const drag = dragAt(x, z);
@@ -69,6 +190,28 @@ export function createKinematicVehicle(tuning, options = {}) {
                 x = toX;
                 z = toZ;
             }
+            // Rest snap (#1051): parked with no throttle/brake/handbrake and sub-threshold motion → exact zero,
+            // killing residual creep and jitter. Zeroing previousForwardSpeed keeps the stop free of a pitch spike.
+            if (chassis !== undefined &&
+                axis.throttle <= 0 &&
+                axis.brake <= 0 &&
+                axis.handbrake <= 0 &&
+                Math.abs(vx * fx + vz * fz) < 0.2 &&
+                Math.abs(-vx * fz + vz * fx) < 0.2) {
+                vx = 0;
+                vz = 0;
+                forwardSpeed = 0;
+                previousForwardSpeed = 0;
+            }
+            const longitudinalAcceleration = dt > 0 ? (forwardSpeed - previousForwardSpeed) / dt : 0;
+            previousForwardSpeed = forwardSpeed;
+            const attitudeResponse = 1 - Math.exp(-Math.max(0, tuning.dynamics?.attitudeResponse ?? 7) * Math.max(0, dt));
+            // comHeight scales brake dive / throttle squat and cornering lean (#1051); `1` without a chassis.
+            const comScale = chassis !== undefined ? chassis.comHeight : 1;
+            const targetPitch = clampSigned(-longitudinalAcceleration * (tuning.dynamics?.bodyPitchFactor ?? 0) * comScale, tuning.dynamics?.maxBodyPitch ?? 0.12);
+            const targetRoll = clampSigned(-yawRate * forwardSpeed * (tuning.dynamics?.bodyRollFactor ?? 0) * comScale, tuning.dynamics?.maxBodyRoll ?? 0.16);
+            bodyPitch += (targetPitch - bodyPitch) * attitudeResponse;
+            bodyRoll += (targetRoll - bodyRoll) * attitudeResponse;
             return {
                 position: [x, y, z],
                 heading,
@@ -76,6 +219,16 @@ export function createKinematicVehicle(tuning, options = {}) {
                 lateralSpeed: -vx * fz + vz * fx,
                 slip,
                 surface,
+                gear: speed < -0.2 ? 0 : gearIndex + 1,
+                rpm,
+                steerAngle,
+                yawRate,
+                longitudinalAcceleration,
+                tractionLimited,
+                absActive,
+                wheelspin,
+                bodyPitch,
+                bodyRoll,
             };
         },
         pose: () => ({ position: [x, y, z], heading }),
@@ -91,6 +244,35 @@ export function createKinematicVehicle(tuning, options = {}) {
             heading = nextHeading;
             vx = 0;
             vz = 0;
+            gearIndex = 0;
+            rpm = tuning.powertrain?.idleRpm ?? 0;
+            shiftRemaining = 0;
+            steerAngle = 0;
+            yawRate = 0;
+            previousForwardSpeed = 0;
+            bodyPitch = 0;
+            bodyRoll = 0;
         },
     };
 }
+/** Gravitational acceleration, m/s², for the chassis friction budget and weight-transfer ratio (#1051). */
+const GRAVITY = 9.81;
+/**
+ * Tyre rolling-resistance coefficient μ_rr (#1051). The always-present coast force is `μ_rr · m · g`
+ * (the road-load floor) — a little high vs. a real ~0.013 tyre so a lifted-off car settles to a stop
+ * in a game-reasonable distance rather than gliding for tens of seconds.
+ */
+const ROLLING_RESISTANCE_COEFFICIENT = 0.03;
+/**
+ * Engine-braking drag as a weight fraction (#1051): the lift-off force is `μ_eb · m · g` routed through
+ * the current gear (`ratio / top-gear ratio`, capped by {@link ENGINE_BRAKE_MAX_LEVERAGE}). Like rolling
+ * resistance it scales with the vehicle's own weight and gravity — not a per-car constant — so every car
+ * settles with a consistent, firm lift-off deceleration that grows as it downshifts toward a stop, while
+ * always staying well short of the service brakes.
+ */
+const ENGINE_BRAKE_COEFFICIENT = 0.11;
+/** Cap on low-gear engine-braking leverage so lifting off never bites as hard as the brake pedal. */
+const ENGINE_BRAKE_MAX_LEVERAGE = 2.5;
+function clampSigned(value, magnitude) {
+    return Math.max(-Math.abs(magnitude), Math.min(Math.abs(magnitude), value));
+}

package/dist/physics/physicsWorld.d.ts

@@ -199,6 +199,7 @@ export declare class PhysicsWorld {
     private jFreeCount;
     private jointHigh;
     private jointActiveCount;
+    private readonly anchorScratch;
     private readonly bodyFree;
     private bodyFreeCount;
     private bodyHigh;
@@ -238,6 +239,13 @@ export declare class PhysicsWorld {
     /** Move a joint's local anchor offset on A (world axes, no rotation applied by the solver). */
     setJointAnchorA(id: number, x: number, y: number, z: number): void;
     setJointRest(id: number, restLength: number): void;
+    /**
+     * Gather joint `id`'s two world anchor points into {@link anchorScratch} as [ax,ay,az,bx,by,bz]
+     * (A's local offset added to body A's centre, or world-origin when A is unset; B likewise, treating
+     * `anchorB` as a world point when B is unset). The single definition shared by {@link jointDistance},
+     * {@link readJointSegments}, and {@link solveJoints}.
+     */
+    private anchorWorld;
     private jointDistance;
     /** Write [ax,ay,az,bx,by,bz] world endpoints per active joint into `out`; returns the joint count. */
     readJointSegments(out: Float32Array): number;
@@ -268,10 +276,28 @@ export declare class PhysicsWorld {
     getStats(): PhysicsStats;
     private substep;
     private constrainBounds;
+    /**
+     * Walk every broadphase cell body `i`'s AABB overlaps, invoking `visit(cell)` once per cell. The
+     * cell-range math (six `cellCoord` calls plus the row-major triple loop) lives here so the count
+     * and scatter passes of {@link buildGrid} share one definition. `visit` is a caller-hoisted closure
+     * (created once per `buildGrid`, not per body) so the hot loop stays allocation-free.
+     */
+    private forEachBodyCell;
     private buildGrid;
     private cellOf;
     private solve;
     private resolve;
+    /**
+     * Apply an axial velocity impulse `jn` along unit axis (nX,nY,nZ) to a joint's two bodies: body A
+     * recoils (−) and body B advances (+), each scaled by its inverse mass. A world anchor (body index
+     * < 0) is skipped. Scalar args only — no allocation on the joint hot path.
+     */
+    private applyAxialImpulse;
+    /**
+     * Positional (Baumgarte) twin of {@link applyAxialImpulse}: nudge the joint's two bodies along
+     * (nX,nY,nZ) by `corr` — body A advances (+), body B recoils (−), each scaled by its inverse mass.
+     */
+    private applyAxialCorrection;
     private solveJoints;
     private updateSleep;
 }

package/dist/physics/physicsWorld.js

@@ -95,6 +95,9 @@ export class PhysicsWorld {
     jFreeCount = 0;
     jointHigh = 0;
     jointActiveCount = 0;
+    // Reused scratch for a joint's two world anchor points [ax,ay,az,bx,by,bz]; filled by anchorWorld
+    // so the gather is defined once and no per-call array is allocated on the joint hot path.
+    anchorScratch = new Float64Array(6);
     // Removed bodies tombstone (FLAG_DEAD) rather than compact: `id` is the SoA slot itself, handed
     // out to callers and stored raw in joints/game state, so a slot can never move once allocated.
     // `bodyHigh` is the high-water mark of ever-used slots; `bodyFree` recycles dead ones for addBody.
@@ -313,18 +316,29 @@ export class PhysicsWorld {
     setJointRest(id, restLength) {
         this.jRest[id] = restLength;
     }
-    jointDistance(id) {
+    /**
+     * Gather joint `id`'s two world anchor points into {@link anchorScratch} as [ax,ay,az,bx,by,bz]
+     * (A's local offset added to body A's centre, or world-origin when A is unset; B likewise, treating
+     * `anchorB` as a world point when B is unset). The single definition shared by {@link jointDistance},
+     * {@link readJointSegments}, and {@link solveJoints}.
+     */
+    anchorWorld(id) {
+        const s = this.anchorScratch;
         const bA = this.jBodyA[id];
         const bB = this.jBodyB[id];
-        const ax = (bA >= 0 ? this.posX[bA] : 0) + this.jAnchorAX[id];
-        const ay = (bA >= 0 ? this.posY[bA] : 0) + this.jAnchorAY[id];
-        const az = (bA >= 0 ? this.posZ[bA] : 0) + this.jAnchorAZ[id];
-        const bx = bB >= 0 ? this.posX[bB] + this.jAnchorBX[id] : this.jAnchorBX[id];
-        const by = bB >= 0 ? this.posY[bB] + this.jAnchorBY[id] : this.jAnchorBY[id];
-        const bz = bB >= 0 ? this.posZ[bB] + this.jAnchorBZ[id] : this.jAnchorBZ[id];
-        const dx = bx - ax;
-        const dy = by - ay;
-        const dz = bz - az;
+        s[0] = (bA >= 0 ? this.posX[bA] : 0) + this.jAnchorAX[id];
+        s[1] = (bA >= 0 ? this.posY[bA] : 0) + this.jAnchorAY[id];
+        s[2] = (bA >= 0 ? this.posZ[bA] : 0) + this.jAnchorAZ[id];
+        s[3] = bB >= 0 ? this.posX[bB] + this.jAnchorBX[id] : this.jAnchorBX[id];
+        s[4] = bB >= 0 ? this.posY[bB] + this.jAnchorBY[id] : this.jAnchorBY[id];
+        s[5] = bB >= 0 ? this.posZ[bB] + this.jAnchorBZ[id] : this.jAnchorBZ[id];
+    }
+    jointDistance(id) {
+        this.anchorWorld(id);
+        const s = this.anchorScratch;
+        const dx = s[3] - s[0];
+        const dy = s[4] - s[1];
+        const dz = s[5] - s[2];
         return Math.sqrt(dx * dx + dy * dy + dz * dz);
     }
     /** Write [ax,ay,az,bx,by,bz] world endpoints per active joint into `out`; returns the joint count. */
@@ -333,15 +347,15 @@ export class PhysicsWorld {
         for (let id = 0; id < this.jointHigh; id += 1) {
             if (this.jActive[id] !== 1)
                 continue;
-            const bA = this.jBodyA[id];
-            const bB = this.jBodyB[id];
+            this.anchorWorld(id);
+            const s = this.anchorScratch;
             const o = n * 6;
-            out[o] = (bA >= 0 ? this.posX[bA] : 0) + this.jAnchorAX[id];
-            out[o + 1] = (bA >= 0 ? this.posY[bA] : 0) + this.jAnchorAY[id];
-            out[o + 2] = (bA >= 0 ? this.posZ[bA] : 0) + this.jAnchorAZ[id];
-            out[o + 3] = bB >= 0 ? this.posX[bB] + this.jAnchorBX[id] : this.jAnchorBX[id];
-            out[o + 4] = bB >= 0 ? this.posY[bB] + this.jAnchorBY[id] : this.jAnchorBY[id];
-            out[o + 5] = bB >= 0 ? this.posZ[bB] + this.jAnchorBZ[id] : this.jAnchorBZ[id];
+            out[o] = s[0];
+            out[o + 1] = s[1];
+            out[o + 2] = s[2];
+            out[o + 3] = s[3];
+            out[o + 4] = s[4];
+            out[o + 5] = s[5];
             n += 1;
         }
         return n;
@@ -609,6 +623,29 @@ export class PhysicsWorld {
                 this.velY[i] = this.velY[i] < rt ? 0 : -this.velY[i] * e;
         }
     }
+    /**
+     * Walk every broadphase cell body `i`'s AABB overlaps, invoking `visit(cell)` once per cell. The
+     * cell-range math (six `cellCoord` calls plus the row-major triple loop) lives here so the count
+     * and scatter passes of {@link buildGrid} share one definition. `visit` is a caller-hoisted closure
+     * (created once per `buildGrid`, not per body) so the hot loop stays allocation-free.
+     */
+    forEachBodyCell(i, visit) {
+        const nx = this.nx;
+        const ny = this.ny;
+        const x0 = cellCoord(this.posX[i] - this.halfX[i], this.bounds.min[0], this.cellSize, this.nx);
+        const x1 = cellCoord(this.posX[i] + this.halfX[i], this.bounds.min[0], this.cellSize, this.nx);
+        const y0 = cellCoord(this.posY[i] - this.halfY[i], this.bounds.min[1], this.cellSize, this.ny);
+        const y1 = cellCoord(this.posY[i] + this.halfY[i], this.bounds.min[1], this.cellSize, this.ny);
+        const z0 = cellCoord(this.posZ[i] - this.halfZ[i], this.bounds.min[2], this.cellSize, this.nz);
+        const z1 = cellCoord(this.posZ[i] + this.halfZ[i], this.bounds.min[2], this.cellSize, this.nz);
+        for (let z = z0; z <= z1; z += 1) {
+            for (let y = y0; y <= y1; y += 1) {
+                const rowBase = (z * ny + y) * nx;
+                for (let x = x0; x <= x1; x += 1)
+                    visit(rowBase + x);
+            }
+        }
+    }
     buildGrid() {
         const n = this.bodyHigh;
         const start = this.cellStart;
@@ -618,24 +655,13 @@ export class PhysicsWorld {
             const i = this.awakeList[a];
             this.bodyCell[i] = this.cellOf(i);
         }
-        const nx = this.nx;
-        const ny = this.ny;
+        const countCell = (cell) => {
+            start[cell + 1] += 1;
+        };
         for (let i = 0; i < n; i += 1) {
             if ((this.flags[i] & FLAG_DEAD) !== 0)
                 continue;
-            const x0 = cellCoord(this.posX[i] - this.halfX[i], this.bounds.min[0], this.cellSize, this.nx);
-            const x1 = cellCoord(this.posX[i] + this.halfX[i], this.bounds.min[0], this.cellSize, this.nx);
-            const y0 = cellCoord(this.posY[i] - this.halfY[i], this.bounds.min[1], this.cellSize, this.ny);
-            const y1 = cellCoord(this.posY[i] + this.halfY[i], this.bounds.min[1], this.cellSize, this.ny);
-            const z0 = cellCoord(this.posZ[i] - this.halfZ[i], this.bounds.min[2], this.cellSize, this.nz);
-            const z1 = cellCoord(this.posZ[i] + this.halfZ[i], this.bounds.min[2], this.cellSize, this.nz);
-            for (let z = z0; z <= z1; z += 1) {
-                for (let y = y0; y <= y1; y += 1) {
-                    const rowBase = (z * ny + y) * nx;
-                    for (let x = x0; x <= x1; x += 1)
-                        start[rowBase + x + 1] += 1;
-                }
-            }
+            this.forEachBodyCell(i, countCell);
         }
         for (let c = 0; c < this.numCells; c += 1) {
             start[c + 1] += start[c];
@@ -645,24 +671,15 @@ export class PhysicsWorld {
         if (total > this.sorted.length) {
             this.sorted = new Int32Array(Math.max(total, this.sorted.length * 2));
         }
+        let scatterBody = 0;
+        const scatterCell = (cell) => {
+            this.sorted[this.cursor[cell]++] = scatterBody;
+        };
         for (let i = 0; i < n; i += 1) {
             if ((this.flags[i] & FLAG_DEAD) !== 0)
                 continue;
-            const x0 = cellCoord(this.posX[i] - this.halfX[i], this.bounds.min[0], this.cellSize, this.nx);
-            const x1 = cellCoord(this.posX[i] + this.halfX[i], this.bounds.min[0], this.cellSize, this.nx);
-            const y0 = cellCoord(this.posY[i] - this.halfY[i], this.bounds.min[1], this.cellSize, this.ny);
-            const y1 = cellCoord(this.posY[i] + this.halfY[i], this.bounds.min[1], this.cellSize, this.ny);
-            const z0 = cellCoord(this.posZ[i] - this.halfZ[i], this.bounds.min[2], this.cellSize, this.nz);
-            const z1 = cellCoord(this.posZ[i] + this.halfZ[i], this.bounds.min[2], this.cellSize, this.nz);
-            for (let z = z0; z <= z1; z += 1) {
-                for (let y = y0; y <= y1; y += 1) {
-                    const rowBase = (z * ny + y) * nx;
-                    for (let x = x0; x <= x1; x += 1) {
-                        const c = rowBase + x;
-                        this.sorted[this.cursor[c]++] = i;
-                    }
-                }
-            }
+            scatterBody = i;
+            this.forEachBodyCell(i, scatterCell);
         }
     }
     cellOf(i) {
@@ -867,6 +884,39 @@ export class PhysicsWorld {
         this.posY[j] += corr * imJ * nY;
         this.posZ[j] += corr * imJ * nZ;
     }
+    /**
+     * Apply an axial velocity impulse `jn` along unit axis (nX,nY,nZ) to a joint's two bodies: body A
+     * recoils (−) and body B advances (+), each scaled by its inverse mass. A world anchor (body index
+     * < 0) is skipped. Scalar args only — no allocation on the joint hot path.
+     */
+    applyAxialImpulse(bA, bB, imA, imB, jn, nX, nY, nZ) {
+        if (bA >= 0) {
+            this.velX[bA] -= jn * imA * nX;
+            this.velY[bA] -= jn * imA * nY;
+            this.velZ[bA] -= jn * imA * nZ;
+        }
+        if (bB >= 0) {
+            this.velX[bB] += jn * imB * nX;
+            this.velY[bB] += jn * imB * nY;
+            this.velZ[bB] += jn * imB * nZ;
+        }
+    }
+    /**
+     * Positional (Baumgarte) twin of {@link applyAxialImpulse}: nudge the joint's two bodies along
+     * (nX,nY,nZ) by `corr` — body A advances (+), body B recoils (−), each scaled by its inverse mass.
+     */
+    applyAxialCorrection(bA, bB, imA, imB, corr, nX, nY, nZ) {
+        if (bA >= 0) {
+            this.posX[bA] += corr * imA * nX;
+            this.posY[bA] += corr * imA * nY;
+            this.posZ[bA] += corr * imA * nZ;
+        }
+        if (bB >= 0) {
+            this.posX[bB] -= corr * imB * nX;
+            this.posY[bB] -= corr * imB * nY;
+            this.posZ[bB] -= corr * imB * nZ;
+        }
+    }
     solveJoints(dt) {
         const beta = this.jointCorrection;
         const slop = this.slop;
@@ -876,15 +926,11 @@ export class PhysicsWorld {
             const kind = this.jKind[id];
             const bA = this.jBodyA[id];
             const bB = this.jBodyB[id];
-            const ax = (bA >= 0 ? this.posX[bA] : 0) + this.jAnchorAX[id];
-            const ay = (bA >= 0 ? this.posY[bA] : 0) + this.jAnchorAY[id];
-            const az = (bA >= 0 ? this.posZ[bA] : 0) + this.jAnchorAZ[id];
-            const bx = bB >= 0 ? this.posX[bB] + this.jAnchorBX[id] : this.jAnchorBX[id];
-            const by = bB >= 0 ? this.posY[bB] + this.jAnchorBY[id] : this.jAnchorBY[id];
-            const bz = bB >= 0 ? this.posZ[bB] + this.jAnchorBZ[id] : this.jAnchorBZ[id];
-            let dx = bx - ax;
-            let dy = by - ay;
-            let dz = bz - az;
+            this.anchorWorld(id);
+            const s = this.anchorScratch;
+            let dx = s[3] - s[0];
+            let dy = s[4] - s[1];
+            let dz = s[5] - s[2];
             const imA = bA >= 0 ? this.invMass[bA] : 0;
             const imB = bB >= 0 ? this.invMass[bB] : 0;
             const imSum = imA + imB;
@@ -924,27 +970,9 @@ export class PhysicsWorld {
                     }
                     const rvn = rvx * nX + rvy * nY + rvz * nZ;
                     const jn = -rvn / imSum;
-                    if (bA >= 0) {
-                        this.velX[bA] -= jn * imA * nX;
-                        this.velY[bA] -= jn * imA * nY;
-                        this.velZ[bA] -= jn * imA * nZ;
-                    }
-                    if (bB >= 0) {
-                        this.velX[bB] += jn * imB * nX;
-                        this.velY[bB] += jn * imB * nY;
-                        this.velZ[bB] += jn * imB * nZ;
-                    }
+                    this.applyAxialImpulse(bA, bB, imA, imB, jn, nX, nY, nZ);
                     const corr = (dist * beta) / imSum;
-                    if (bA >= 0) {
-                        this.posX[bA] += corr * imA * nX;
-                        this.posY[bA] += corr * imA * nY;
-                        this.posZ[bA] += corr * imA * nZ;
-                    }
-                    if (bB >= 0) {
-                        this.posX[bB] -= corr * imB * nX;
-                        this.posY[bB] -= corr * imB * nY;
-                        this.posZ[bB] -= corr * imB * nZ;
-                    }
+                    this.applyAxialCorrection(bA, bB, imA, imB, corr, nX, nY, nZ);
                 }
                 else {
                     const rvl = Math.sqrt(rvx * rvx + rvy * rvy + rvz * rvz);
@@ -953,16 +981,7 @@ export class PhysicsWorld {
                         const nY = rvy / rvl;
                         const nZ = rvz / rvl;
                         const jn = -rvl / imSum;
-                        if (bA >= 0) {
-                            this.velX[bA] -= jn * imA * nX;
-                            this.velY[bA] -= jn * imA * nY;
-                            this.velZ[bA] -= jn * imA * nZ;
-                        }
-                        if (bB >= 0) {
-                            this.velX[bB] += jn * imB * nX;
-                            this.velY[bB] += jn * imB * nY;
-                            this.velZ[bB] += jn * imB * nZ;
-                        }
+                        this.applyAxialImpulse(bA, bB, imA, imB, jn, nX, nY, nZ);
                     }
                 }
                 continue;
@@ -994,16 +1013,7 @@ export class PhysicsWorld {
                     jn = maxJ;
                 else if (jn < -maxJ)
                     jn = -maxJ;
-                if (bA >= 0) {
-                    this.velX[bA] -= jn * imA * nX;
-                    this.velY[bA] -= jn * imA * nY;
-                    this.velZ[bA] -= jn * imA * nZ;
-                }
-                if (bB >= 0) {
-                    this.velX[bB] += jn * imB * nX;
-                    this.velY[bB] += jn * imB * nY;
-                    this.velZ[bB] += jn * imB * nZ;
-                }
+                this.applyAxialImpulse(bA, bB, imA, imB, jn, nX, nY, nZ);
                 continue;
             }
             if (kind !== JOINT_FIXED && kind !== JOINT_DISTANCE) {
@@ -1016,27 +1026,9 @@ export class PhysicsWorld {
                     this.wake(bB);
             }
             const jn = -rvn / imSum;
-            if (bA >= 0) {
-                this.velX[bA] -= jn * imA * nX;
-                this.velY[bA] -= jn * imA * nY;
-                this.velZ[bA] -= jn * imA * nZ;
-            }
-            if (bB >= 0) {
-                this.velX[bB] += jn * imB * nX;
-                this.velY[bB] += jn * imB * nY;
-                this.velZ[bB] += jn * imB * nZ;
-            }
+            this.applyAxialImpulse(bA, bB, imA, imB, jn, nX, nY, nZ);
             const corr = (c * beta) / imSum;
-            if (bA >= 0) {
-                this.posX[bA] += corr * imA * nX;
-                this.posY[bA] += corr * imA * nY;
-                this.posZ[bA] += corr * imA * nZ;
-            }
-            if (bB >= 0) {
-                this.posX[bB] -= corr * imB * nX;
-                this.posY[bB] -= corr * imB * nY;
-                this.posZ[bB] -= corr * imB * nZ;
-            }
+            this.applyAxialCorrection(bA, bB, imA, imB, corr, nX, nY, nZ);
         }
     }
     updateSleep() {