@jgengine/core 0.10.0 → 0.12.0

package/dist/physics/physicsWorld.js

@@ -1,3 +1,8 @@
+const PHYSICS_PRECISION_PRESETS = {
+    low: { solverIterations: 2, correctionFactor: 0.15, sleepThresholdSteps: 15, wakeThreshold: 0.75, jointCorrection: 0.35 },
+    standard: { solverIterations: 4, correctionFactor: 0.2, sleepThresholdSteps: 30, wakeThreshold: 0.5, jointCorrection: 0.5 },
+    high: { solverIterations: 8, correctionFactor: 0.3, sleepThresholdSteps: 45, wakeThreshold: 0.35, jointCorrection: 0.65 },
+};
 export const SHAPE_BOX = 0;
 export const SHAPE_SPHERE = 1;
 export const JOINT_FIXED = 0;
@@ -90,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.
@@ -119,6 +127,7 @@ export class PhysicsWorld {
         stepMs: 0,
     };
     constructor(config) {
+        const preset = PHYSICS_PRECISION_PRESETS[config.precision ?? "standard"];
         this.capacity = config.capacity;
         this.bounds = { min: config.bounds.min, max: config.bounds.max };
         this.gravity = config.gravity ?? -20;
@@ -129,16 +138,16 @@ export class PhysicsWorld {
         this.restitutionThreshold = config.restitutionThreshold ?? 1;
         this.friction = config.friction ?? 0.4;
         this.linearDamping = config.linearDamping ?? 0.2;
-        this.solverIterations = Math.max(1, config.solverIterations ?? 4);
-        this.correctionFactor = config.correctionFactor ?? 0.2;
+        this.solverIterations = Math.max(1, config.solverIterations ?? preset.solverIterations);
+        this.correctionFactor = config.correctionFactor ?? preset.correctionFactor;
         this.slop = config.slop ?? 0.005;
         const sleepV = config.sleepLinearVelocity ?? 0.08;
         const sleepMoveEps = sleepV * this.fixedDt;
         this.sleepMove2 = sleepMoveEps * sleepMoveEps;
-        this.sleepSteps = config.sleepThresholdSteps ?? 30;
-        this.wakeThreshold = config.wakeThreshold ?? 0.5;
+        this.sleepSteps = config.sleepThresholdSteps ?? preset.sleepThresholdSteps;
+        this.wakeThreshold = config.wakeThreshold ?? preset.wakeThreshold;
         this.jointCapacity = Math.max(0, config.jointCapacity ?? 256);
-        this.jointCorrection = config.jointCorrection ?? 0.5;
+        this.jointCorrection = config.jointCorrection ?? preset.jointCorrection;
         const cap = config.capacity;
         this.posX = new Float32Array(cap);
         this.posY = new Float32Array(cap);
@@ -307,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. */
@@ -327,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;
@@ -603,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;
@@ -612,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];
@@ -639,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) {
@@ -861,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;
@@ -870,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;
@@ -918,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);
@@ -947,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;
@@ -988,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) {
@@ -1010,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() {

package/dist/physics/radialImpulse.d.ts

@@ -0,0 +1,25 @@
+/** How a radial impulse fades from the blast center to its edge. */
+export type RadialFalloff = "linear" | "quadratic" | "none";
+/** A radial push: the impulse vector plus the 0..1 falloff sampled at the target. */
+export interface RadialImpulse {
+    /** Impulse along the first axis (direction × magnitude). */
+    x: number;
+    /** Impulse along the second axis (direction × magnitude). */
+    y: number;
+    /** Impulse magnitude = `power` × `falloff`. */
+    magnitude: number;
+    /** Falloff weight at the target, 1 at the center down to 0 at the radius. */
+    falloff: number;
+}
+/** Options for {@link radialImpulse}. */
+export interface RadialImpulseOptions {
+    /** Falloff shape. Defaults to `"linear"` (`1 − d/r`). */
+    falloff?: RadialFalloff;
+}
+/**
+ * Point-source radial impulse pushing a `target` away from a blast `source`: full `power` at the center
+ * fading to zero at `radius`. Returns `null` when the target sits at or beyond the radius (unaffected),
+ * so callers can early-out. At the exact center the direction is zero. This is the explosion/knockback/
+ * shockwave push — every arena game hand-rolled the distance, falloff, and normalize.
+ */
+export declare function radialImpulse(source: readonly [number, number], target: readonly [number, number], radius: number, power: number, options?: RadialImpulseOptions): RadialImpulse | null;

package/dist/physics/radialImpulse.js

@@ -0,0 +1,27 @@
+function falloffAt(distance, radius, shape) {
+    const linear = 1 - distance / radius;
+    if (shape === "none")
+        return 1;
+    if (shape === "quadratic")
+        return linear * linear;
+    return linear;
+}
+/**
+ * Point-source radial impulse pushing a `target` away from a blast `source`: full `power` at the center
+ * fading to zero at `radius`. Returns `null` when the target sits at or beyond the radius (unaffected),
+ * so callers can early-out. At the exact center the direction is zero. This is the explosion/knockback/
+ * shockwave push — every arena game hand-rolled the distance, falloff, and normalize.
+ */
+export function radialImpulse(source, target, radius, power, options = {}) {
+    if (radius <= 0)
+        return null;
+    const dx = target[0] - source[0];
+    const dy = target[1] - source[1];
+    const distance = Math.hypot(dx, dy);
+    if (distance >= radius)
+        return null;
+    const falloff = falloffAt(distance, radius, options.falloff ?? "linear");
+    const magnitude = power * falloff;
+    const invLen = distance > 1e-6 ? 1 / distance : 0;
+    return { x: dx * invLen * magnitude, y: dy * invLen * magnitude, magnitude, falloff };
+}

package/dist/physics/vehicleObstacles.d.ts

@@ -0,0 +1,44 @@
+import { type CollisionObstacle } from "../movement/movementModel.js";
+/**
+ * A single blocked-move event a car can react to (#1051): crash damage, screen shake, a metal-crunch
+ * cue. Reported once, when a move is first vetoed, then consumed by {@link VehicleObstacleClamp.takeImpact}.
+ */
+export interface VehicleImpact {
+    /** Speed (world units/s) the car was carrying *into* the obstacle at the moment the move was blocked. */
+    closingSpeed: number;
+    /** Unit push-back direction — points from the struck surface back toward the car. */
+    normal: readonly [number, number];
+    /** Index into the obstacle set passed for the blocking tick. */
+    obstacleIndex: number;
+}
+/**
+ * A planar move clamp for a kinematic car: feed {@link clampMove} to a vehicle's `clampMove` hook so
+ * an attempted XZ displacement slides along world solids instead of driving through them, and read
+ * {@link takeImpact} once per tick for the crash it produced.
+ */
+export interface VehicleObstacleClamp {
+    /** Resolve an attempted `from`→`to` XZ move to the destination actually allowed (slide-along). */
+    clampMove(from: readonly [number, number], to: readonly [number, number]): readonly [number, number];
+    /** Impact recorded since last take, consumed on read (null when none). Closing speed is the velocity component into the obstacle at block time, units/s. */
+    takeImpact(): VehicleImpact | null;
+}
+/**
+ * Build a slide-along move clamp for a kinematic car (#1051). `obstacles` is sampled fresh each tick —
+ * the caller hands back the already-filtered set of solids near the car — and `dt` supplies the current
+ * tick length so a blocked move's lost displacement converts to a closing speed. `radius` inflates each
+ * obstacle footprint by the car's body radius (default {@link DEFAULT_VEHICLE_RADIUS}).
+ *
+ * The slide itself is delegated to {@link resolveObstacleStep} so cars and pedestrians share one proven
+ * axis-separated resolver: a shallow graze keeps its tangential run and only the into-wall component is
+ * shed, a head-on zeroes forward progress. When any component is shed the largest such block this tick is
+ * kept as a {@link VehicleImpact}; {@link VehicleObstacleClamp.takeImpact} returns and clears it so a hit
+ * fires exactly once. The happy path (no solids near) is a zero-allocation passthrough returning `to`.
+ */
+export declare function createVehicleObstacleClamp(options: {
+    /** Solids near the car this tick (already filtered to the relevant, solid set). */
+    obstacles: () => readonly CollisionObstacle[];
+    /** Vehicle body radius (units). Default {@link DEFAULT_VEHICLE_RADIUS}. */
+    radius?: number;
+    /** Current tick dt (seconds) — the divisor turning shed displacement into closing speed. */
+    dt: () => number;
+}): VehicleObstacleClamp;

package/dist/physics/vehicleObstacles.js

@@ -0,0 +1,115 @@
+import { resolveObstacleStep } from "../movement/movementModel.js";
+/** Matches the unit-box default {@link resolveObstacleStep} applies to obstacles without explicit extents. */
+const DEFAULT_OBSTACLE_HALF_EXTENTS = [0.5, 0.5, 0.5];
+/** Default vehicle body radius (units) inflating obstacle footprints; a compact hatchback-ish disc. */
+const DEFAULT_VEHICLE_RADIUS = 1.4;
+/**
+ * Y the car body is pinned to when handing solids to {@link resolveObstacleStep}. That stepper gates
+ * each obstacle by a 1.8-tall pedestrian span around `current[1]`; centring every pre-filtered solid
+ * on this value makes the gate always admit them, so collision is purely horizontal and the car hits
+ * world solids at any ground elevation (bridges, hills) even though the clamp only knows XZ.
+ */
+const CAR_BODY_MID_Y = 0.9;
+/** Below this the returned step is treated as unblocked (float-noise slack), so no phantom impacts fire. */
+const BLOCK_EPSILON = 1e-6;
+/**
+ * Build a slide-along move clamp for a kinematic car (#1051). `obstacles` is sampled fresh each tick —
+ * the caller hands back the already-filtered set of solids near the car — and `dt` supplies the current
+ * tick length so a blocked move's lost displacement converts to a closing speed. `radius` inflates each
+ * obstacle footprint by the car's body radius (default {@link DEFAULT_VEHICLE_RADIUS}).
+ *
+ * The slide itself is delegated to {@link resolveObstacleStep} so cars and pedestrians share one proven
+ * axis-separated resolver: a shallow graze keeps its tangential run and only the into-wall component is
+ * shed, a head-on zeroes forward progress. When any component is shed the largest such block this tick is
+ * kept as a {@link VehicleImpact}; {@link VehicleObstacleClamp.takeImpact} returns and clears it so a hit
+ * fires exactly once. The happy path (no solids near) is a zero-allocation passthrough returning `to`.
+ */
+export function createVehicleObstacleClamp(options) {
+    const radius = options.radius ?? DEFAULT_VEHICLE_RADIUS;
+    // Grow-only scratch of Y-normalised solids, reused across ticks so a sustained crash allocates nothing
+    // after warm-up. Per-clamp (closure-local) so concurrent cars never share it.
+    const scratch = [];
+    let pending = null;
+    function vehicleView(source) {
+        const n = source.length;
+        for (let i = 0; i < n; i += 1) {
+            let entry = scratch[i];
+            if (entry === undefined) {
+                entry = { position: [0, 0, 0] };
+                scratch[i] = entry;
+            }
+            const from = source[i];
+            entry.position[0] = from.position[0];
+            entry.position[1] = CAR_BODY_MID_Y;
+            entry.position[2] = from.position[2];
+            entry.halfExtents = from.halfExtents;
+        }
+        if (scratch.length > n)
+            scratch.length = n;
+        return scratch;
+    }
+    /** Obstacle the attempted endpoint penetrates deepest (its inflated footprint), else nearest centre. */
+    function blockingIndex(source, tx, tz) {
+        let bestIndex = -1;
+        let bestDepth = -Number.POSITIVE_INFINITY;
+        let fallbackIndex = 0;
+        let fallbackDistSq = Number.POSITIVE_INFINITY;
+        for (let i = 0; i < source.length; i += 1) {
+            const o = source[i];
+            const half = o.halfExtents ?? DEFAULT_OBSTACLE_HALF_EXTENTS;
+            const ex = half[0] + radius;
+            const ez = half[2] + radius;
+            const minX = o.position[0] - ex;
+            const maxX = o.position[0] + ex;
+            const minZ = o.position[2] - ez;
+            const maxZ = o.position[2] + ez;
+            if (tx > minX && tx < maxX && tz > minZ && tz < maxZ) {
+                const depth = Math.min(tx - minX, maxX - tx, tz - minZ, maxZ - tz);
+                if (depth > bestDepth) {
+                    bestDepth = depth;
+                    bestIndex = i;
+                }
+            }
+            const dx = o.position[0] - tx;
+            const dz = o.position[2] - tz;
+            const distSq = dx * dx + dz * dz;
+            if (distSq < fallbackDistSq) {
+                fallbackDistSq = distSq;
+                fallbackIndex = i;
+            }
+        }
+        return bestIndex >= 0 ? bestIndex : fallbackIndex;
+    }
+    return {
+        clampMove(from, to) {
+            const obstacles = options.obstacles();
+            if (obstacles.length === 0)
+                return to;
+            const attemptedX = to[0] - from[0];
+            const attemptedZ = to[1] - from[1];
+            const step = resolveObstacleStep([from[0], CAR_BODY_MID_Y, from[1]], attemptedX, attemptedZ, vehicleView(obstacles), radius);
+            const blockedX = attemptedX - step.stepX;
+            const blockedZ = attemptedZ - step.stepZ;
+            if (blockedX === 0 && blockedZ === 0)
+                return to;
+            const blockedMag = Math.hypot(blockedX, blockedZ);
+            if (blockedMag > BLOCK_EPSILON) {
+                const dt = options.dt();
+                const closingSpeed = dt > 0 ? blockedMag / dt : 0;
+                if (pending === null || closingSpeed > pending.closingSpeed) {
+                    pending = {
+                        closingSpeed,
+                        normal: [-blockedX / blockedMag, -blockedZ / blockedMag],
+                        obstacleIndex: blockingIndex(obstacles, to[0], to[1]),
+                    };
+                }
+            }
+            return [from[0] + step.stepX, from[1] + step.stepZ];
+        },
+        takeImpact() {
+            const impact = pending;
+            pending = null;
+            return impact;
+        },
+    };
+}

package/dist/procedural.d.ts

@@ -0,0 +1,3 @@
+export { createDecayMeterSet, type DecayMeterSet } from "./survival/decayMeter.js";
+export { createMoodleStack, stackMoodles, type Moodle, type MoodleStack } from "./survival/moodle.js";
+export { createMultiRegionHealth, type MultiRegionHealth } from "./survival/regionHealth.js";

package/dist/procedural.js

@@ -0,0 +1,3 @@
+export { createDecayMeterSet } from "./survival/decayMeter.js";
+export { createMoodleStack, stackMoodles } from "./survival/moodle.js";
+export { createMultiRegionHealth } from "./survival/regionHealth.js";