@jgengine/core 0.8.0 → 0.9.0

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/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;
+}

package/dist/runtime/cameraDirector.d.ts

@@ -1,10 +1,15 @@
-import type { CinematicCameraConfig } from "../game/playableGame.js";
+import type { ChaseCameraConfig, CinematicCameraConfig } from "../game/playableGame.js";
+/** Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11). */
+export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank">>;
 export interface CameraDirector {
     follow(entityId: string | null): void;
     /** `undefined` means no runtime override — the shell falls back to the static `playable.camera.followEntityId`. `null` means explicitly follow nothing. */
     followedEntityId(): string | null | undefined;
     setCinematic(config: CinematicCameraConfig | null): void;
     cinematic(): CinematicCameraConfig | null;
+    /** Overlay a runtime patch on the chase rig's config — a boss-intro pull-back, drift zoom-out; `null` restores the static config. */
+    setChaseTuning(tuning: ChaseCameraTuning | null): void;
+    chaseTuning(): ChaseCameraTuning | null;
     subscribe(listener: () => void): () => void;
 }
 export declare function createCameraDirector(): CameraDirector;

package/dist/runtime/cameraDirector.js

@@ -2,6 +2,7 @@ export function createCameraDirector() {
     const listeners = new Set();
     let followEntity = undefined;
     let cinematicConfig = null;
+    let chaseTuningPatch = null;
     function notify() {
         for (const listener of listeners)
             listener();
@@ -17,6 +18,11 @@ export function createCameraDirector() {
             notify();
         },
         cinematic: () => cinematicConfig,
+        setChaseTuning(tuning) {
+            chaseTuningPatch = tuning;
+            notify();
+        },
+        chaseTuning: () => chaseTuningPatch,
         subscribe(listener) {
             listeners.add(listener);
             return () => listeners.delete(listener);

package/dist/runtime/commandRunner.d.ts

@@ -2,8 +2,8 @@ export type CommandValidationError = {
     reason: string;
 };
 export type CommandDef<TInput = unknown> = {
-    validate: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput) => CommandValidationError | null;
-    apply: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput) => import("./snapshot.js").GameRuntimeSnapshot;
+    validate: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string) => CommandValidationError | null;
+    apply: (snapshot: import("./snapshot.js").GameRuntimeSnapshot, input: TInput, actorUserId: string) => import("./snapshot.js").GameRuntimeSnapshot;
 };
 export type RunCommandResult = {
     ok: true;

package/dist/runtime/commandRunner.js

@@ -3,11 +3,11 @@ export function runCommand(snapshot, commands, commandName, input, actorUserId)
     if (!command) {
         return { ok: false, reason: `Unknown command: ${commandName}` };
     }
-    const validationError = command.validate(snapshot, input);
+    const validationError = command.validate(snapshot, input, actorUserId);
     if (validationError) {
         return { ok: false, reason: validationError.reason };
     }
-    const next = command.apply(snapshot, input);
+    const next = command.apply(snapshot, input, actorUserId);
     return {
         ok: true,
         snapshot: {

package/dist/runtime/gameContext.d.ts

@@ -30,16 +30,19 @@ import { type PaintLayer } from "../scene/paintLayer.js";
 import { type EntityStatsApi, type StatCatalog } from "../scene/entityStats.js";
 import type { EntityPose, EntityPosition, EntityStore, SceneEntity, SpawnOptions, SpawnPose } from "../scene/entityStore.js";
 import { type Forms } from "../scene/form.js";
+import type { EntityColliderSet } from "../scene/colliders.js";
 import { type ObjectRaycastHit, type ObjectRaycastInput } from "../scene/objectQuery.js";
 import { type ObjectStore } from "../scene/objectStore.js";
 import { type Roster } from "../scene/roster.js";
 import { type Possession } from "../scene/possession.js";
+import { type SceneRaycastHit, type SceneRaycastInput } from "../scene/sceneRaycast.js";
 import { type SpatialApi } from "../scene/spatial.js";
 import { type CycleTargetOptions } from "../scene/targeting.js";
 import { type Stats } from "../stats/statModifiers.js";
 import { type ObservableKeyedStore } from "../store/observableKeyedStore.js";
 import { type SimClock } from "../time/simClock.js";
 import { type TurnLoop, type TurnLoopConfig } from "../turn/turnLoop.js";
+import { RaceState, type RaceStateConfig } from "../game/race.js";
 import { type CameraDirector } from "./cameraDirector.js";
 import { type InputSnapshot } from "./inputSnapshot.js";
 import { type MotionIntents } from "./motionIntents.js";
@@ -63,6 +66,8 @@ export interface GameContextEntityEntry {
     role?: CatalogEntityRole;
     /** Right-click context-menu verbs for this entity (#31). */
     verbs?: readonly ContextVerb[];
+    /** Purpose-specific colliders (physical body + named damage hitboxes). */
+    colliders?: EntityColliderSet;
 }
 export interface GameContextObjectEntry {
     proximityPrompt?: ProximityPrompt;
@@ -72,6 +77,8 @@ export interface GameContextObjectEntry {
     slotInventory?: InventoryLayout;
     /** Right-click context-menu verbs for this object (#31). */
     verbs?: readonly ContextVerb[];
+    colliders?: EntityColliderSet;
+    halfExtents?: readonly [number, number, number];
 }
 export interface GameContextContent {
     itemById?(itemId: string): GameContextItemEntry | null | undefined;
@@ -86,11 +93,14 @@ export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAsset
         isNew: boolean;
     };
     now?: () => number;
+    occluder?: (from: EntityPosition, to: EntityPosition) => boolean;
 }
 export interface SceneObjectContext extends ObjectStore {
     catalog(instanceId: string): GameContextObjectEntry | null;
     raycast(input: ObjectRaycastInput): ObjectRaycastHit | null;
     raycastAll(input: ObjectRaycastInput): readonly ObjectRaycastHit[];
+    setColliders(instanceId: string, colliders: EntityColliderSet | null): void;
+    collidersOf(instanceId: string): EntityColliderSet | null;
 }
 export interface FloatTextInput {
     instanceId?: string;
@@ -129,6 +139,7 @@ export interface SceneEntityContext {
     despawn(instanceId: string): boolean;
     update: EntityStore["update"];
     setPose(instanceId: string, pose: EntityPose): boolean;
+    setPoseConstraint: EntityStore["setPoseConstraint"];
     get(instanceId: string): SceneEntity | null;
     list(): readonly SceneEntity[];
     spawnPoseOf(instanceId: string): SpawnPose | null;
@@ -152,6 +163,9 @@ export interface SceneEntityContext {
     hasLineOfSight: SpatialApi["hasLineOfSight"];
     queryArc: SpatialApi["queryArc"];
     moveToward: SpatialApi["moveToward"];
+    invalidateSpatial: SpatialApi["invalidate"];
+    setColliders(instanceId: string, colliders: EntityColliderSet | null): void;
+    collidersOf(instanceId: string): EntityColliderSet | null;
     form: Forms;
     paint: PaintLayer;
 }
@@ -210,11 +224,17 @@ export interface GameContextTurn {
     /** Lazily creates (on first call, `config` required) or returns the existing notify-wrapped turn loop for `id`. */
     loop(id: string, config?: TurnLoopConfig): TurnLoop;
 }
+export interface GameContextRace {
+    /** Lazily creates (on first call, `config` required) or returns the existing reactive race for `id` — discrete mutations and eventful `update` calls bump `ctx.version()`, so HUDs stop hand-managing `store.set` (#286.2). */
+    state(id: string, config?: RaceStateConfig): RaceState;
+}
 export interface GameContext {
     scene: {
         object: SceneObjectContext;
         entity: SceneEntityContext;
         worldItem: SceneWorldItemContext;
+        raycast(input: SceneRaycastInput): SceneRaycastHit | null;
+        raycastAll(input: SceneRaycastInput): readonly SceneRaycastHit[];
     };
     world: GameContextWorld;
     game: {
@@ -234,6 +254,7 @@ export interface GameContext {
         store: ObservableKeyedStore<unknown>;
         cards: GameContextCards;
         turn: GameContextTurn;
+        race: GameContextRace;
     };
     player: {
         userId: string;