@jgengine/core 0.11.0 → 0.12.0

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() {

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/random/rng.d.ts

@@ -20,7 +20,10 @@ export declare function randomSeedFrom(seed: number): RandomSeed;
  * instead of closing over a generator.
  */
 export declare function stepRandomSeed(seed: RandomSeed): readonly [value: number, next: RandomSeed];
-/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
+/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.
+ *
+ * @capability seeded-random injected deterministic randomness for game logic — never `Math.random` in a simulation
+ */
 export declare function seededRng(seed: string | number): () => number;
 /** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */
 export declare function seededStreams(seed: string | number): (stream: string) => () => number;

package/dist/random/rng.js

@@ -29,7 +29,10 @@ export function stepRandomSeed(seed) {
     const value = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     return [value, next];
 }
-/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
+/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.
+ *
+ * @capability seeded-random injected deterministic randomness for game logic — never `Math.random` in a simulation
+ */
 export function seededRng(seed) {
     let cursor = randomSeedFrom(hashSeed(seed));
     return () => {

package/dist/runtime/adapter.d.ts

@@ -56,6 +56,8 @@ export declare function convexPresence(config?: {
  * WebSocket transport. Omitting `authority` (or passing `"client"`) is **presence-only** — prefer
  * `wsPresence()` to name that intent explicitly. Pass `{ authority: "server" }` for a shared,
  * host-authoritative world — see `examples/HOSTED.md`.
+ *
+ * @capability multiplayer-ws server-hosted shared world over WebSocket — `multiplayer: ws({ authority: "server" })`
  */
 export declare function ws(config?: {
     topology?: MultiplayerTopology;
@@ -78,6 +80,11 @@ export declare function socketIo(config?: {
     url?: string;
     authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
+/**
+ * Serverless peer-to-peer (WebRTC) session — one peer hosts, friends join by room code.
+ *
+ * @capability multiplayer-p2p serverless co-op over WebRTC — `multiplayer: p2p({ room })`
+ */
 export declare function p2p(config?: {
     topology?: MultiplayerTopology;
     room?: string;
@@ -105,6 +112,12 @@ export declare function resolveAuthority(multiplayer: unknown): MultiplayerAutho
 export declare function isPresenceOnly(multiplayer: unknown): boolean;
 /** True for a single-player world — no adapter, or an explicit `offline()` one. Gates offline-only wiring like local whole-world save. */
 export declare function isOffline(multiplayer: unknown): boolean;
+/**
+ * Explicit single-player adapter. Solo games never need this — omitting `multiplayer` in the shell
+ * `defineGame` already defaults to offline; pass it only where an adapter value is structurally required.
+ *
+ * @capability multiplayer-offline explicit solo adapter — omit `multiplayer` instead; offline is the shell default
+ */
 export declare function offline(): MultiplayerAdapterConfig;
 export declare function adapterOf(multiplayer: unknown): MultiplayerAdapterConfig | null;
 export declare function multiplayerAdapterKind(multiplayer: unknown): string | null;

package/dist/runtime/adapter.js

@@ -14,6 +14,8 @@ export function convexPresence(config) {
  * WebSocket transport. Omitting `authority` (or passing `"client"`) is **presence-only** — prefer
  * `wsPresence()` to name that intent explicitly. Pass `{ authority: "server" }` for a shared,
  * host-authoritative world — see `examples/HOSTED.md`.
+ *
+ * @capability multiplayer-ws server-hosted shared world over WebSocket — `multiplayer: ws({ authority: "server" })`
  */
 export function ws(config) {
     return { kind: "ws", topology: config?.topology ?? "shared", url: config?.url, authority: config?.authority };
@@ -33,6 +35,11 @@ export function fly(config) {
 export function socketIo(config) {
     return { kind: "socketio", topology: config?.topology ?? "shared", url: config?.url, authority: config?.authority };
 }
+/**
+ * Serverless peer-to-peer (WebRTC) session — one peer hosts, friends join by room code.
+ *
+ * @capability multiplayer-p2p serverless co-op over WebRTC — `multiplayer: p2p({ room })`
+ */
 export function p2p(config) {
     return { kind: "p2p", topology: config?.topology ?? "private", room: config?.room, authority: config?.authority };
 }
@@ -69,6 +76,12 @@ export function isOffline(multiplayer) {
     const adapter = adapterOf(multiplayer);
     return adapter === null || adapter.kind === "offline";
 }
+/**
+ * Explicit single-player adapter. Solo games never need this — omitting `multiplayer` in the shell
+ * `defineGame` already defaults to offline; pass it only where an adapter value is structurally required.
+ *
+ * @capability multiplayer-offline explicit solo adapter — omit `multiplayer` instead; offline is the shell default
+ */
 export function offline() {
     return { kind: "offline" };
 }

package/dist/runtime/context/combat.d.ts

@@ -0,0 +1,51 @@
+import { type DeathSystem } from "../../combat/death.js";
+import { type CombatSpatialDeps, type EffectSystem } from "../../combat/effects.js";
+import { type ProjectileSystem } from "../../combat/projectiles.js";
+import type { PhysicsConfig } from "../../game/defineGame.js";
+import type { GameEvents } from "../../game/events.js";
+import { type VfxInstanceStore } from "../../game/vfxInstance.js";
+import type { LootRegistry } from "../../game/lootTable.js";
+import type { EntityColliderSet } from "../../scene/colliders.js";
+import type { EntityStore } from "../../scene/entityStore.js";
+import type { ObjectStore } from "../../scene/objectStore.js";
+import type { SceneRaycastApi } from "../../scene/sceneRaycast.js";
+import type { WeaponStats } from "../../item/weapon.js";
+import type { SimClock } from "../../time/simClock.js";
+import type { WorldItemRecord, WorldItemSpawnInput } from "../../game/worldItem.js";
+import type { GameContextContent, GameContextEntityEntry, GameContextLoot } from "../gameContext.js";
+import { type CombatFx } from "./combatFx.js";
+/** @internal Wiring combat needs from the live scene, loot, and command seams. */
+export interface CombatSubsystemDeps {
+    content: GameContextContent;
+    signalNotify: () => void;
+    now: () => number;
+    events: GameEvents;
+    time: SimClock;
+    entities: EntityStore;
+    objects: ObjectStore;
+    combatSpatial: CombatSpatialDeps;
+    sceneRaycast: SceneRaycastApi;
+    entityCollidersOf: (instanceId: string) => EntityColliderSet | null;
+    objectCollidersOf: (instanceId: string) => EntityColliderSet | null;
+    catalogEntry: (instanceId: string) => GameContextEntityEntry | null | undefined;
+    statsByInstance: Map<string, import("../../scene/entityStats.js").StatValueMap>;
+    weapon: WeaponStats;
+    loot: GameContextLoot;
+    lootRegistry: LootRegistry;
+    spawnWorldItem: (input: WorldItemSpawnInput) => WorldItemRecord;
+    despawnEntity: (instanceId: string) => boolean;
+    runCommand: (name: string, args: unknown) => void;
+    localUserId: string;
+    physics?: PhysicsConfig;
+}
+/** @internal Effects, projectiles, death, and combat presentation surface. */
+export interface CombatSubsystem {
+    death: DeathSystem;
+    effects: EffectSystem;
+    floatingEffects: EffectSystem;
+    projectiles: ProjectileSystem;
+    combatFx: CombatFx;
+    vfxInstances: VfxInstanceStore;
+}
+/** @internal */
+export declare function createCombatSubsystem(d: CombatSubsystemDeps): CombatSubsystem;