@jgengine/core 0.8.0 → 0.10.0

package/dist/physics/forceVolume.js

@@ -63,6 +63,44 @@ export class ForceVolume {
         this.members = next;
     }
 }
+/** One tick's force math for a body outside `PhysicsWorld` — apply the returned velocity in any custom integrator. */
+export function applyVolumeForce(velocity, force, mode, dt) {
+    if (mode === "velocity")
+        return force;
+    if (mode === "accelerate") {
+        return [velocity[0] + force[0] * dt, velocity[1] + force[1] * dt, velocity[2] + force[2] * dt];
+    }
+    return [velocity[0] + force[0], velocity[1] + force[1], velocity[2] + force[2]];
+}
+export function createVolumeTrigger(config) {
+    let members = new Set();
+    return {
+        bounds: config.bounds,
+        step(bodies) {
+            const entered = [];
+            const insideNow = [];
+            const next = new Set();
+            for (const body of bodies) {
+                if (!inside(config.bounds, body.position[0], body.position[1], body.position[2]))
+                    continue;
+                next.add(body.id);
+                insideNow.push(body.id);
+                if (!members.has(body.id))
+                    entered.push(body.id);
+            }
+            const exited = [];
+            for (const id of members) {
+                if (!next.has(id))
+                    exited.push(id);
+            }
+            members = next;
+            return { entered, inside: insideNow, exited };
+        },
+        reset() {
+            members = new Set();
+        },
+    };
+}
 /**
  * Carries bodies standing on a moving platform by composing their transform with the platform's
  * per-`step` delta — moving/rotating lifts and conveyor floors (Fall Guys, Gang Beasts). The

package/dist/physics/kinematicVehicle.d.ts

@@ -0,0 +1,52 @@
+import type { AxisInput } from "../input/axisInput.js";
+import { type GripCurve } from "./vehicleBody.js";
+export interface KinematicVehicleTuning {
+    engineAccel: number;
+    brakeAccel: number;
+    topSpeed: number;
+    reverseSpeed: number;
+    turnRate: number;
+    turnSpeedRef: number;
+    grip?: GripCurve;
+    gripStrength: number;
+    handbrakeGrip: number;
+    /** Forward-speed decay per second when coasting (sleds, boats); default `0`. */
+    rollingResistance?: number;
+}
+export interface KinematicVehicleOptions {
+    position?: readonly [number, number, number];
+    heading?: number;
+    /** Grip multiplier by world position — off-track gravel, ice patches; default `1` everywhere. */
+    surfaceFriction?: (x: number, z: number) => number;
+    /** Extra velocity damping per second by world position (rough ground drag); default `0`. */
+    dragAt?: (x: number, z: number) => number;
+}
+export interface KinematicVehicleStep {
+    position: readonly [number, number, number];
+    heading: number;
+    /** Signed speed along the heading, world units/s. */
+    forwardSpeed: number;
+    lateralSpeed: number;
+    /** Lateral/forward slip ratio driving the grip curve — drift indicators key off it. */
+    slip: number;
+    /** The `surfaceFriction` sample used this tick (`< 1` = off the ideal surface). */
+    surface: number;
+}
+/**
+ * The pure-kinematic arcade car every racing game hand-rolled (#282.1): steer-yaw scaled by speed,
+ * throttle/brake acceleration, and a grip-curve lateral-slip bleed — no `PhysicsWorld`, no wheels,
+ * just the drift-friendly integration the three shipped racers proved out. Games keep their flavor
+ * (drift meters, boost, off-track rules) via `surfaceFriction`/`dragAt` hooks and the returned slip.
+ */
+export interface KinematicVehicle {
+    tick(dt: number, axis: AxisInput): KinematicVehicleStep;
+    pose(): {
+        position: readonly [number, number, number];
+        heading: number;
+    };
+    velocity(): readonly [number, number];
+    /** Scale the current velocity (boost pads, hard collisions). */
+    scaleVelocity(factor: number): void;
+    resetTo(position: readonly [number, number, number], heading: number): void;
+}
+export declare function createKinematicVehicle(tuning: KinematicVehicleTuning, options?: KinematicVehicleOptions): KinematicVehicle;

package/dist/physics/kinematicVehicle.js

@@ -0,0 +1,81 @@
+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 rollingResistance = tuning.rollingResistance ?? 0;
+    const surfaceFriction = options.surfaceFriction ?? (() => 1);
+    const dragAt = options.dragAt ?? (() => 0);
+    let x = options.position?.[0] ?? 0;
+    let y = options.position?.[1] ?? 0;
+    let z = options.position?.[2] ?? 0;
+    let heading = options.heading ?? 0;
+    let vx = 0;
+    let vz = 0;
+    function forward() {
+        return [Math.sin(heading), Math.cos(heading)];
+    }
+    return {
+        tick(dt, axis) {
+            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, tuning.turnRate, dt);
+            const [fx, fz] = forward();
+            let accel = 0;
+            if (axis.throttle > 0 && speed < tuning.topSpeed)
+                accel += axis.throttle * tuning.engineAccel;
+            if (axis.brake > 0) {
+                if (speed > 0.2)
+                    accel -= axis.brake * tuning.brakeAccel;
+                else if (speed > -tuning.reverseSpeed)
+                    accel -= axis.brake * tuning.engineAccel;
+            }
+            vx += fx * accel * dt;
+            vz += fz * accel * dt;
+            let forwardSpeed = vx * fx + vz * fz;
+            const lateralSpeed = -vx * fz + vz * fx;
+            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 keep = Math.max(0, 1 - gripValue * tuning.gripStrength * dt);
+            const keptLateral = lateralSpeed * keep;
+            if (rollingResistance > 0)
+                forwardSpeed *= Math.max(0, 1 - rollingResistance * dt);
+            vx = fx * forwardSpeed - fz * keptLateral;
+            vz = fz * forwardSpeed + fx * keptLateral;
+            const drag = dragAt(x, z);
+            let dragDamp = 1;
+            if (drag > 0) {
+                dragDamp = Math.max(0, 1 - drag * dt);
+                vx *= dragDamp;
+                vz *= dragDamp;
+            }
+            x += vx * dt;
+            z += vz * dt;
+            return {
+                position: [x, y, z],
+                heading,
+                forwardSpeed: vx * fx + vz * fz,
+                lateralSpeed: keptLateral * dragDamp,
+                slip,
+                surface,
+            };
+        },
+        pose: () => ({ position: [x, y, z], heading }),
+        velocity: () => [vx, vz],
+        scaleVelocity(factor) {
+            vx *= factor;
+            vz *= factor;
+        },
+        resetTo(position, nextHeading) {
+            x = position[0];
+            y = position[1];
+            z = position[2];
+            heading = nextHeading;
+            vx = 0;
+            vz = 0;
+        },
+    };
+}

package/dist/physics/physicsWorld.d.ts

@@ -72,11 +72,15 @@ export type AddBodyOptions = BoxBodyOptions | SphereBodyOptions;
 export declare const SHAPE_BOX = 0;
 export declare const SHAPE_SPHERE = 1;
 /**
- * `hinge`/`fixed`/`distance` are hard bilateral constraints; `spring` is a soft PD constraint.
- * No angular state → `hinge`/`fixed` both pin the shared anchor (`axis` is metadata), `distance`
- * holds a fixed separation, `spring` drives toward `restLength` (suspension, follow-point carry).
+ * Hard bilateral: `fixed` pins the shared anchor (3-DOF), `hinge` pins only the plane
+ * perpendicular to `axis` (free along the axis — translational cylindrical), `distance`
+ * holds a fixed separation. `spring` is a soft PD drive toward `restLength`.
  */
 export type JointKind = "hinge" | "distance" | "spring" | "fixed";
+export declare const JOINT_FIXED = 0;
+export declare const JOINT_HINGE = 1;
+export declare const JOINT_DISTANCE = 2;
+export declare const JOINT_SPRING = 3;
 export interface JointOptions {
     /** First body index. */
     bodyA: number;
@@ -94,7 +98,7 @@ export interface JointOptions {
     damping?: number;
     /** Clamp on the per-substep spring impulse (a follow-point that never yanks). Default unbounded. */
     maxImpulse?: number;
-    /** Hinge axis, retained as metadata (this sim has no angular DOF). */
+    /** Unit hinge axis (world). Required semantics for `hingeJoint`; free motion along this axis. Default [0,1,0]. */
     axis?: readonly [number, number, number];
 }
 /** A contact reported to `onCollision`. The object is reused each call — read/copy, never retain. */
@@ -157,12 +161,12 @@ export declare class PhysicsWorld {
     private readonly numCells;
     private readonly cellStart;
     private readonly cursor;
-    private readonly sorted;
+    private sorted;
     private readonly bodyCell;
     private readonly awakeList;
     private readonly awakeSlot;
     private awakeCount;
-    private readonly jSpring;
+    private readonly jKind;
     private readonly jActive;
     private readonly jBodyA;
     private readonly jBodyB;
@@ -172,6 +176,9 @@ export declare class PhysicsWorld {
     private readonly jAnchorBX;
     private readonly jAnchorBY;
     private readonly jAnchorBZ;
+    private readonly jAxisX;
+    private readonly jAxisY;
+    private readonly jAxisZ;
     private readonly jRest;
     private readonly jStiffness;
     private readonly jDamping;

package/dist/physics/physicsWorld.js

@@ -1,5 +1,9 @@
 export const SHAPE_BOX = 0;
 export const SHAPE_SPHERE = 1;
+export const JOINT_FIXED = 0;
+export const JOINT_HINGE = 1;
+export const JOINT_DISTANCE = 2;
+export const JOINT_SPRING = 3;
 const FLAG_SLEEPING = 1;
 const FLAG_STATIC = 2;
 const FLAG_DEAD = 4;
@@ -65,7 +69,7 @@ export class PhysicsWorld {
     awakeList;
     awakeSlot;
     awakeCount = 0;
-    jSpring;
+    jKind;
     jActive;
     jBodyA;
     jBodyB;
@@ -75,6 +79,9 @@ export class PhysicsWorld {
     jAnchorBX;
     jAnchorBY;
     jAnchorBZ;
+    jAxisX;
+    jAxisY;
+    jAxisZ;
     jRest;
     jStiffness;
     jDamping;
@@ -168,7 +175,7 @@ export class PhysicsWorld {
         this.awakeSlot = new Int32Array(cap).fill(-1);
         this.bodyFree = new Int32Array(cap);
         const jc = this.jointCapacity;
-        this.jSpring = new Uint8Array(jc);
+        this.jKind = new Uint8Array(jc);
         this.jActive = new Uint8Array(jc);
         this.jBodyA = new Int32Array(jc);
         this.jBodyB = new Int32Array(jc);
@@ -178,6 +185,9 @@ export class PhysicsWorld {
         this.jAnchorBX = new Float32Array(jc);
         this.jAnchorBY = new Float32Array(jc);
         this.jAnchorBZ = new Float32Array(jc);
+        this.jAxisX = new Float32Array(jc);
+        this.jAxisY = new Float32Array(jc);
+        this.jAxisZ = new Float32Array(jc);
         this.jRest = new Float32Array(jc);
         this.jStiffness = new Float32Array(jc);
         this.jDamping = new Float32Array(jc);
@@ -224,18 +234,25 @@ export class PhysicsWorld {
         this.collisionMinSpeed = minApproachSpeed;
     }
     hingeJoint(options) {
-        return this.addJoint(options, false, 0);
+        const raw = options.axis ?? [0, 1, 0];
+        const len = Math.hypot(raw[0], raw[1], raw[2]);
+        if (!(len > 1e-9))
+            throw new Error("PhysicsWorld: hingeJoint axis must be non-zero");
+        return this.addJoint(options, JOINT_HINGE, 0, [raw[0] / len, raw[1] / len, raw[2] / len]);
     }
     fixedJoint(options) {
-        return this.addJoint(options, false, 0);
+        return this.addJoint(options, JOINT_FIXED, 0, null);
     }
     distanceJoint(options) {
-        return this.addJoint(options, false, null);
+        return this.addJoint(options, JOINT_DISTANCE, null, null);
     }
     springJoint(options) {
-        return this.addJoint(options, true, null);
+        return this.addJoint(options, JOINT_SPRING, null, null);
     }
-    addJoint(options, spring, restOverride) {
+    addJoint(options, kind, restOverride, axis) {
+        if (kind !== JOINT_FIXED && kind !== JOINT_HINGE && kind !== JOINT_DISTANCE && kind !== JOINT_SPRING) {
+            throw new Error(`PhysicsWorld: joint kind ${kind} is not implemented`);
+        }
         let id;
         if (this.jFreeCount > 0) {
             id = this.jFree[--this.jFreeCount];
@@ -256,7 +273,10 @@ export class PhysicsWorld {
         this.jAnchorBX[id] = aB?.[0] ?? 0;
         this.jAnchorBY[id] = aB?.[1] ?? 0;
         this.jAnchorBZ[id] = aB?.[2] ?? 0;
-        this.jSpring[id] = spring ? 1 : 0;
+        this.jKind[id] = kind;
+        this.jAxisX[id] = axis?.[0] ?? 0;
+        this.jAxisY[id] = axis?.[1] ?? 0;
+        this.jAxisZ[id] = axis?.[2] ?? 0;
         this.jStiffness[id] = options.stiffness ?? 40;
         this.jDamping[id] = options.damping ?? 6;
         this.jMaxImpulse[id] = options.maxImpulse ?? Number.POSITIVE_INFINITY;
@@ -587,28 +607,56 @@ export class PhysicsWorld {
         const n = this.bodyHigh;
         const start = this.cellStart;
         start.fill(0);
-        // Sleeping bodies never move, so their cell index is cached from addBody / their last awake
-        // substep — only awake bodies pay the cell recomputation each substep.
         const awakeCount = this.awakeCount;
         for (let a = 0; a < awakeCount; a += 1) {
             const i = this.awakeList[a];
             this.bodyCell[i] = this.cellOf(i);
         }
-        // Dead slots (tombstoned by removeBody) sit inside [0, bodyHigh) but never enter the grid.
+        const nx = this.nx;
+        const ny = this.ny;
         for (let i = 0; i < n; i += 1) {
             if ((this.flags[i] & FLAG_DEAD) !== 0)
                 continue;
-            start[this.bodyCell[i] + 1] += 1;
+            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;
+                }
+            }
         }
         for (let c = 0; c < this.numCells; c += 1) {
             start[c + 1] += start[c];
             this.cursor[c] = start[c];
         }
+        const total = start[this.numCells];
+        if (total > this.sorted.length) {
+            this.sorted = new Int32Array(Math.max(total, this.sorted.length * 2));
+        }
         for (let i = 0; i < n; i += 1) {
             if ((this.flags[i] & FLAG_DEAD) !== 0)
                 continue;
-            const c = this.bodyCell[i];
-            this.sorted[this.cursor[c]++] = i;
+            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;
+                    }
+                }
+            }
         }
     }
     cellOf(i) {
@@ -620,26 +668,18 @@ export class PhysicsWorld {
     solve(restitutionPass, countPass) {
         const nx = this.nx;
         const ny = this.ny;
-        const nz = this.nz;
-        const nxny = nx * ny;
-        // A contact may wake a sleeping body mid-pass, appending it to the awake list; re-read the
-        // count each iteration so it is solved this substep too.
         for (let a = 0; a < this.awakeCount; a += 1) {
             const i = this.awakeList[a];
-            const c = this.bodyCell[i];
-            const cz = (c / nxny) | 0;
-            const cy = ((c - cz * nxny) / nx) | 0;
-            const cx = c - cz * nxny - cy * nx;
-            const z0 = cz > 0 ? cz - 1 : cz;
-            const z1 = cz < nz - 1 ? cz + 1 : cz;
-            const y0 = cy > 0 ? cy - 1 : cy;
-            const y1 = cy < ny - 1 ? cy + 1 : cy;
-            const x0 = cx > 0 ? cx - 1 : cx;
-            const x1 = cx < nx - 1 ? cx + 1 : cx;
-            for (let z = z0; z <= z1; z += 1) {
-                for (let y = y0; y <= y1; y += 1) {
+            const ix0 = cellCoord(this.posX[i] - this.halfX[i], this.bounds.min[0], this.cellSize, this.nx);
+            const ix1 = cellCoord(this.posX[i] + this.halfX[i], this.bounds.min[0], this.cellSize, this.nx);
+            const iy0 = cellCoord(this.posY[i] - this.halfY[i], this.bounds.min[1], this.cellSize, this.ny);
+            const iy1 = cellCoord(this.posY[i] + this.halfY[i], this.bounds.min[1], this.cellSize, this.ny);
+            const iz0 = cellCoord(this.posZ[i] - this.halfZ[i], this.bounds.min[2], this.cellSize, this.nz);
+            const iz1 = cellCoord(this.posZ[i] + this.halfZ[i], this.bounds.min[2], this.cellSize, this.nz);
+            for (let z = iz0; z <= iz1; z += 1) {
+                for (let y = iy0; y <= iy1; y += 1) {
                     const rowBase = (z * ny + y) * nx;
-                    for (let x = x0; x <= x1; x += 1) {
+                    for (let x = ix0; x <= ix1; x += 1) {
                         const cell = rowBase + x;
                         const end = this.cellStart[cell + 1];
                         for (let s = this.cellStart[cell]; s < end; s += 1) {
@@ -649,6 +689,14 @@ export class PhysicsWorld {
                             const jSleeping = (this.flags[j] & FLAG_SLEEPING) !== 0;
                             if (!jSleeping && j < i)
                                 continue;
+                            const jx0 = cellCoord(this.posX[j] - this.halfX[j], this.bounds.min[0], this.cellSize, this.nx);
+                            const jy0 = cellCoord(this.posY[j] - this.halfY[j], this.bounds.min[1], this.cellSize, this.ny);
+                            const jz0 = cellCoord(this.posZ[j] - this.halfZ[j], this.bounds.min[2], this.cellSize, this.nz);
+                            const mx0 = ix0 > jx0 ? ix0 : jx0;
+                            const my0 = iy0 > jy0 ? iy0 : jy0;
+                            const mz0 = iz0 > jz0 ? iz0 : jz0;
+                            if (x !== mx0 || y !== my0 || z !== mz0)
+                                continue;
                             this.resolve(i, j, restitutionPass, countPass);
                         }
                     }
@@ -819,6 +867,7 @@ export class PhysicsWorld {
         for (let id = 0; id < this.jointHigh; id += 1) {
             if (this.jActive[id] !== 1)
                 continue;
+            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];
@@ -827,9 +876,91 @@ export class PhysicsWorld {
             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;
+            let dx = bx - ax;
+            let dy = by - ay;
+            let dz = bz - az;
+            const imA = bA >= 0 ? this.invMass[bA] : 0;
+            const imB = bB >= 0 ? this.invMass[bB] : 0;
+            const imSum = imA + imB;
+            if (imSum === 0)
+                continue;
+            if (kind === JOINT_HINGE) {
+                const ux = this.jAxisX[id];
+                const uy = this.jAxisY[id];
+                const uz = this.jAxisZ[id];
+                const along = dx * ux + dy * uy + dz * uz;
+                dx -= along * ux;
+                dy -= along * uy;
+                dz -= along * uz;
+                const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+                const vax = bA >= 0 ? this.velX[bA] : 0;
+                const vay = bA >= 0 ? this.velY[bA] : 0;
+                const vaz = bA >= 0 ? this.velZ[bA] : 0;
+                const vbx = bB >= 0 ? this.velX[bB] : 0;
+                const vby = bB >= 0 ? this.velY[bB] : 0;
+                const vbz = bB >= 0 ? this.velZ[bB] : 0;
+                let rvx = vbx - vax;
+                let rvy = vby - vay;
+                let rvz = vbz - vaz;
+                const rvAlong = rvx * ux + rvy * uy + rvz * uz;
+                rvx -= rvAlong * ux;
+                rvy -= rvAlong * uy;
+                rvz -= rvAlong * uz;
+                if (dist > 1e-9) {
+                    const nX = dx / dist;
+                    const nY = dy / dist;
+                    const nZ = dz / dist;
+                    if (dist > slop) {
+                        if (bA >= 0)
+                            this.wake(bA);
+                        if (bB >= 0)
+                            this.wake(bB);
+                    }
+                    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;
+                    }
+                    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;
+                    }
+                }
+                else {
+                    const rvl = Math.sqrt(rvx * rvx + rvy * rvy + rvz * rvz);
+                    if (rvl > 1e-9) {
+                        const nX = rvx / rvl;
+                        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;
+                        }
+                    }
+                }
+                continue;
+            }
             const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
             if (dist < 1e-9)
                 continue;
@@ -837,11 +968,6 @@ export class PhysicsWorld {
             const nY = dy / dist;
             const nZ = dz / dist;
             const c = dist - this.jRest[id];
-            const imA = bA >= 0 ? this.invMass[bA] : 0;
-            const imB = bB >= 0 ? this.invMass[bB] : 0;
-            const imSum = imA + imB;
-            if (imSum === 0)
-                continue;
             const vax = bA >= 0 ? this.velX[bA] : 0;
             const vay = bA >= 0 ? this.velY[bA] : 0;
             const vaz = bA >= 0 ? this.velZ[bA] : 0;
@@ -849,7 +975,7 @@ export class PhysicsWorld {
             const vby = bB >= 0 ? this.velY[bB] : 0;
             const vbz = bB >= 0 ? this.velZ[bB] : 0;
             const rvn = (vbx - vax) * nX + (vby - vay) * nY + (vbz - vaz) * nZ;
-            if (this.jSpring[id] === 1) {
+            if (kind === JOINT_SPRING) {
                 if (Math.abs(c) > slop) {
                     if (bA >= 0)
                         this.wake(bA);
@@ -874,6 +1000,9 @@ export class PhysicsWorld {
                 }
                 continue;
             }
+            if (kind !== JOINT_FIXED && kind !== JOINT_DISTANCE) {
+                throw new Error(`PhysicsWorld: joint kind ${kind} is not implemented`);
+            }
             if (Math.abs(c) > slop) {
                 if (bA >= 0)
                     this.wake(bA);

package/dist/physics/ragdoll.js

@@ -88,7 +88,7 @@ export function createRagdoll(world, config) {
                     (world.posY[a] + world.posY[b]) / 2,
                     (world.posZ[a] + world.posZ[b]) / 2,
                 ];
-            links.push(world.hingeJoint({
+            links.push(world.fixedJoint({
                 bodyA: a,
                 bodyB: b,
                 anchorA: [mid[0] - world.posX[a], mid[1] - world.posY[a], mid[2] - world.posZ[a]],

package/dist/physics/vehicleBody.js

@@ -1,3 +1,4 @@
+import { steerYaw } from "../movement/steering.js";
 /**
  * Piecewise-linear tire-grip curve: normalized lateral slip → available grip (0..1). Grip peaks near
  * the breakaway slip then falls off as the tire slides — the shape that separates a planted corner
@@ -166,7 +167,7 @@ export class VehicleBody {
         if (grounded) {
             const steerScale = Math.min(1, Math.abs(speed) / this.turnSpeedRef);
             const dir = speed >= 0 ? 1 : -1;
-            this.heading += input.steer * this.turnRate * steerScale * dir * dt;
+            this.heading = steerYaw(this.heading, input.steer * steerScale * dir, this.turnRate, dt);
         }
         const [fx, fz] = this.forward;
         if (grounded) {

package/dist/random/rng.d.ts

@@ -1,2 +1,4 @@
+/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
 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

@@ -7,6 +7,7 @@ function hashSeed(seed) {
     }
     return h >>> 0;
 }
+/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
 export function seededRng(seed) {
     let a = hashSeed(seed) >>> 0;
     return () => {
@@ -17,6 +18,7 @@ export function seededRng(seed) {
         return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     };
 }
+/** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */
 export function seededStreams(seed) {
     const base = typeof seed === "number" ? seed.toString() : seed;
     return (stream) => seededRng(`${base}:${stream}`);

package/dist/random/seedLink.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_SEED_PARAM = "seed";
+export declare function withSeedParam(url: string, seed: string | number, param?: string): string;
+export declare function seedFromSearch(search: string, param?: string): string | null;
+export declare function seedFromUrl(url: string, param?: string): string | null;
+export declare function dailySeed(nowMs: number, salt?: string): string;

package/dist/random/seedLink.js

@@ -0,0 +1,35 @@
+export const DEFAULT_SEED_PARAM = "seed";
+function splitUrl(url) {
+    const hashIndex = url.indexOf("#");
+    const hash = hashIndex === -1 ? "" : url.slice(hashIndex + 1);
+    const rest = hashIndex === -1 ? url : url.slice(0, hashIndex);
+    const queryIndex = rest.indexOf("?");
+    const base = queryIndex === -1 ? rest : rest.slice(0, queryIndex);
+    const query = queryIndex === -1 ? "" : rest.slice(queryIndex + 1);
+    return { base, query, hash };
+}
+export function withSeedParam(url, seed, param = DEFAULT_SEED_PARAM) {
+    const { base, query, hash } = splitUrl(url);
+    const params = new URLSearchParams(query);
+    params.set(param, typeof seed === "number" ? seed.toString() : seed);
+    const queryString = params.toString();
+    return `${base}${queryString ? `?${queryString}` : ""}${hash ? `#${hash}` : ""}`;
+}
+export function seedFromSearch(search, param = DEFAULT_SEED_PARAM) {
+    const normalized = search.startsWith("?") ? search.slice(1) : search;
+    const params = new URLSearchParams(normalized);
+    const value = params.get(param);
+    return value === null || value === "" ? null : value;
+}
+export function seedFromUrl(url, param = DEFAULT_SEED_PARAM) {
+    const { query } = splitUrl(url);
+    return seedFromSearch(query, param);
+}
+export function dailySeed(nowMs, salt) {
+    const date = new Date(nowMs);
+    const year = date.getUTCFullYear().toString().padStart(4, "0");
+    const month = (date.getUTCMonth() + 1).toString().padStart(2, "0");
+    const day = date.getUTCDate().toString().padStart(2, "0");
+    const base = `${year}-${month}-${day}`;
+    return salt !== undefined && salt.length > 0 ? `${base}:${salt}` : base;
+}