@jgengine/core 0.19.0 → 0.22.0

package/dist/physics/forceVolume.d.ts

@@ -1,5 +1,46 @@
 import type { PhysicsBounds, PhysicsWorld } from "./physicsWorld.js";
 export type ForceMode = "impulse" | "velocity" | "accelerate";
+/** World-space force position, axis or acceleration vector. */
+export type ForceVector = readonly [number, number, number];
+/** Renderer-free localized acceleration shared by physical actors and cosmetic particles. */
+export interface ForceFieldConfig {
+    center: ForceVector;
+    shape: {
+        kind: "sphere";
+        radius: number;
+    } | {
+        kind: "box";
+        halfExtents: ForceVector;
+    };
+    /** Positive attracts toward the center; negative repels. Units/s². */
+    strength: number;
+    /** Edge-to-center falloff exponent; zero is uniform. Default 1. */
+    attenuation?: number;
+    /** Blend radial attraction with `direction`, from 0 to 1. */
+    directionality?: number;
+    /** World-space direction; default [0, 0, -1]. */
+    direction?: ForceVector;
+    /** Signed tangential acceleration around a world-space axis. */
+    vortex?: {
+        axis: ForceVector;
+        strength: number;
+        /** Independent signed acceleration along the normalized axis, in units/s². */
+        lift?: number;
+    };
+    /** Affected target bits; omission affects every target. */
+    mask?: number;
+    /** Cap the combined acceleration magnitude. */
+    maxAcceleration?: number;
+}
+/** Validate force authoring once before sampling in a hot loop.
+ * Coordinates stay within the safe integer range; acceleration magnitudes stay within 1e12 units/s².
+ * @capability force-field-validation reject invalid localized force authoring before simulation
+ */
+export declare function validateForceField(config: ForceFieldConfig): void;
+/** Sample localized acceleration; `out` permits allocation-free integration.
+ * @capability localized-forces sample signed attraction, directional force, vortex spin and axial lift with target masks and caps
+ */
+export declare function sampleForceField(config: ForceFieldConfig, position: ForceVector, targetMask?: number, out?: [number, number, number]): [number, number, number];
 export interface ForceVolumeConfig {
     /** Region a body's center must be inside to be affected. */
     bounds: PhysicsBounds;

package/dist/physics/forceVolume.js

@@ -1,3 +1,91 @@
+const DEFAULT_FORCE_DIRECTION = [0, 0, -1];
+/** Validate force authoring once before sampling in a hot loop.
+ * Coordinates stay within the safe integer range; acceleration magnitudes stay within 1e12 units/s².
+ * @capability force-field-validation reject invalid localized force authoring before simulation
+ */
+export function validateForceField(config) {
+    const vector = (value) => Array.isArray(value) && value.length === 3 && value.every(component => typeof component === "number" && Number.isFinite(component) && Math.abs(component) <= Number.MAX_SAFE_INTEGER);
+    const finite = (value, min = -1e12, max = 1e12) => typeof value === "number" && Number.isFinite(value) && value >= min && value <= max;
+    if (config === null || typeof config !== "object" || !vector(config.center) || !finite(config.strength))
+        throw new RangeError("Force field requires safe finite coordinates and strength in -1e12..1e12");
+    if (config.shape?.kind === "sphere") {
+        if (!finite(config.shape.radius, Number.MIN_VALUE))
+            throw new RangeError("Force sphere radius must be finite and positive");
+    }
+    else if (config.shape?.kind === "box") {
+        if (!vector(config.shape.halfExtents) || !config.shape.halfExtents.every(value => value > 0))
+            throw new RangeError("Force box extents must be finite and positive");
+    }
+    else
+        throw new RangeError("Force field requires sphere or box shape");
+    if (config.attenuation !== undefined && !finite(config.attenuation, 0))
+        throw new RangeError("Force attenuation must be finite and nonnegative");
+    if (config.directionality !== undefined && !finite(config.directionality, 0, 1))
+        throw new RangeError("Force directionality must be in 0..1");
+    if (config.direction !== undefined && (!vector(config.direction) || Math.hypot(...config.direction) === 0))
+        throw new RangeError("Force direction must be finite and nonzero");
+    if (config.vortex !== undefined && (!vector(config.vortex.axis) || Math.hypot(...config.vortex.axis) === 0 || !finite(config.vortex.strength)))
+        throw new RangeError("Force vortex requires a finite nonzero axis and finite strength");
+    if (config.vortex?.lift !== undefined && !finite(config.vortex.lift))
+        throw new RangeError("Force vortex lift must be finite");
+    if (config.mask !== undefined && (!finite(config.mask, 0, 0xffffffff) || !Number.isInteger(config.mask)))
+        throw new RangeError("Force mask must be an unsigned 32-bit integer");
+    if (config.maxAcceleration !== undefined && !finite(config.maxAcceleration, 0))
+        throw new RangeError("Force acceleration cap must be finite and nonnegative");
+}
+/** Sample localized acceleration; `out` permits allocation-free integration.
+ * @capability localized-forces sample signed attraction, directional force, vortex spin and axial lift with target masks and caps
+ */
+export function sampleForceField(config, position, targetMask = 0xffffffff, out = [0, 0, 0]) {
+    out[0] = out[1] = out[2] = 0;
+    if (((config.mask ?? 0xffffffff) & targetMask) === 0)
+        return out;
+    const x = position[0] - config.center[0];
+    const y = position[1] - config.center[1];
+    const z = position[2] - config.center[2];
+    const distance = Math.hypot(x, y, z);
+    const extent = config.shape.kind === "sphere"
+        ? distance / config.shape.radius
+        : Math.max(Math.abs(x) / config.shape.halfExtents[0], Math.abs(y) / config.shape.halfExtents[1], Math.abs(z) / config.shape.halfExtents[2]);
+    if (!Number.isFinite(extent) || extent >= 1)
+        return out;
+    const envelope = Math.pow(1 - extent, Math.max(0, config.attenuation ?? 1));
+    const directional = Math.max(0, Math.min(1, config.directionality ?? 0));
+    const direction = config.direction ?? DEFAULT_FORCE_DIRECTION;
+    const directionLength = Math.hypot(...direction);
+    const radialScale = distance > 1e-9 ? -config.strength * (1 - directional) / distance : 0;
+    const directionScale = directionLength > 1e-9 ? config.strength * directional / directionLength : 0;
+    out[0] = x * radialScale + direction[0] * directionScale;
+    out[1] = y * radialScale + direction[1] * directionScale;
+    out[2] = z * radialScale + direction[2] * directionScale;
+    if (config.vortex !== undefined) {
+        const [ax, ay, az] = config.vortex.axis;
+        const axisLength = Math.hypot(ax, ay, az);
+        if (axisLength > 1e-9) {
+            const liftScale = (config.vortex.lift ?? 0) / axisLength;
+            out[0] += ax * liftScale;
+            out[1] += ay * liftScale;
+            out[2] += az * liftScale;
+        }
+        const tx = ay * z - az * y;
+        const ty = az * x - ax * z;
+        const tz = ax * y - ay * x;
+        const tangentLength = Math.hypot(tx, ty, tz);
+        if (tangentLength > 1e-9) {
+            const scale = config.vortex.strength / tangentLength;
+            out[0] += tx * scale;
+            out[1] += ty * scale;
+            out[2] += tz * scale;
+        }
+    }
+    const magnitude = Math.hypot(...out) * envelope;
+    const cap = Math.max(0, config.maxAcceleration ?? Number.POSITIVE_INFINITY);
+    const scale = magnitude > cap ? envelope * cap / magnitude : envelope;
+    out[0] = out[0] === 0 ? 0 : out[0] * scale;
+    out[1] = out[1] === 0 ? 0 : out[1] * scale;
+    out[2] = out[2] === 0 ? 0 : out[2] * scale;
+    return out;
+}
 function inside(bounds, x, y, z) {
     return (x >= bounds.min[0] &&
         x <= bounds.max[0] &&

package/dist/physics/kinematicVehicle.d.ts

@@ -130,10 +130,15 @@ export interface KinematicVehicleOptions {
     /**
      * Veto or clamp a planar move before it commits — walls, closed gates, arena bounds. Given the
      * attempted `from`→`to` on the XZ plane, return the destination actually allowed; velocity is
-     * rederived from the permitted displacement, so motion blocked on an axis stops on that axis
-     * instead of grinding into the obstacle. Default: no clamp (the move always commits).
+     * rederived from the permitted displacement, so motion blocked on an axis stops on that axis.
+     * A result may carry `motion`, the permitted XZ displacement in world units before position
+     * recovery. Use it when the endpoint also depenetrates the body: recovery must not add velocity.
+     * Plain tuple results retain displacement-based velocity. Called once per tick; no purity required.
+     * Default: no clamp (the move always commits).
      */
-    clampMove?: (from: readonly [number, number], to: readonly [number, number]) => readonly [number, number];
+    clampMove?: (from: readonly [number, number], to: readonly [number, number]) => readonly [number, number] & {
+        readonly motion?: readonly [number, number];
+    };
 }
 /**
  * Per-tick multipliers layered over the base tuning — the transient overrides games apply for one

package/dist/physics/kinematicVehicle.js

@@ -236,8 +236,8 @@ export function createKinematicVehicle(initialTuning, options = {}) {
             const toZ = z + vz * dt;
             if (clampMove !== undefined && dt > 0) {
                 const allowed = clampMove([x, z], [toX, toZ]);
-                vx = (allowed[0] - x) / dt;
-                vz = (allowed[1] - z) / dt;
+                vx = (allowed.motion?.[0] ?? allowed[0] - x) / dt;
+                vz = (allowed.motion?.[1] ?? allowed[1] - z) / dt;
                 x = allowed[0];
                 z = allowed[1];
             }

package/dist/physics/physicsWorldBackend.js

@@ -1,5 +1,10 @@
 import { IDENTITY_QUAT, isIdentityQuat, shapeHalfExtents, } from "./physicsBackend.js";
 import { PhysicsWorld } from "./physicsWorld.js";
+/** Exact touching is not overlap; account for the same few-ulp face rounding as shapecast. */
+function axisOverlaps(center, bodyCenter, combinedHalf) {
+    const tolerance = Number.EPSILON * 8 * Math.max(1, Math.abs(center), Math.abs(bodyCenter - combinedHalf), Math.abs(bodyCenter + combinedHalf));
+    return combinedHalf - Math.abs(bodyCenter - center) > tolerance;
+}
 const ALL_LAYERS = 0xffffffff;
 const CAPABILITIES = {
     rotation: false,
@@ -408,6 +413,17 @@ export function createPhysicsWorldBackend(options) {
                         least === 2 ? -1 : least === 3 ? 1 : 0,
                         least === 4 ? -1 : least === 5 ? 1 : 0,
                     ];
+                    // Expanding an AABB by a capsule's half-height can round exact floor contact inside
+                    // by a few ulps. Keep entering contacts and real penetration, but allow departing or
+                    // tangent motion through this numerical touch so it cannot mask a later wall/ceiling.
+                    const faceScale = least < 2
+                        ? Math.max(1, Math.abs(ox), Math.abs(minX), Math.abs(maxX))
+                        : least < 4
+                            ? Math.max(1, Math.abs(oy), Math.abs(minY), Math.abs(maxY))
+                            : Math.max(1, Math.abs(oz), Math.abs(minZ), Math.abs(maxZ));
+                    const touchTolerance = Number.EPSILON * 8 * faceScale;
+                    if (motionLen > 0 && pens[least] <= touchTolerance && mx * normal[0] + my * normal[1] + mz * normal[2] >= 0)
+                        continue;
                 }
                 else {
                     if (!(motionLen > 0))
@@ -437,11 +453,11 @@ export function createPhysicsWorldBackend(options) {
                 if (!bodyMatches(rec, desc.mask, desc.exclude, handle))
                     continue;
                 const i = rec.index;
-                if (Math.abs(world.posX[i] - desc.position[0]) >= rec.half[0] + half[0])
+                if (!axisOverlaps(desc.position[0], world.posX[i], rec.half[0] + half[0]))
                     continue;
-                if (Math.abs(world.posY[i] - desc.position[1]) >= rec.half[1] + half[1])
+                if (!axisOverlaps(desc.position[1], world.posY[i], rec.half[1] + half[1]))
                     continue;
-                if (Math.abs(world.posZ[i] - desc.position[2]) >= rec.half[2] + half[2])
+                if (!axisOverlaps(desc.position[2], world.posZ[i], rec.half[2] + half[2]))
                     continue;
                 out.push(handle);
             }

package/dist/physics/spatialGrid.d.ts

@@ -36,6 +36,6 @@ export declare class SpatialGrid {
     rebuild(count: number, xs: Float32Array, zs: Float32Array): void;
     /** Fill `out` with every entity within `radius` of (x,z); returns the hit count (capped at `out.length`). */
     queryCircle(x: number, z: number, radius: number, out: Int32Array): number;
-    /** Invoke `cb(a, b)` once for each unordered pair within `maxDistance` (mutual separation/overlap). */
+    /** Invoke `cb(a, b)` once for each unordered pair within finite, nonnegative `maxDistance`, including distances larger than `cellSize`. */
     forEachPair(maxDistance: number, cb: (a: number, b: number) => void): void;
 }

package/dist/physics/spatialGrid.js

@@ -103,25 +103,24 @@ export class SpatialGrid {
         }
         return n;
     }
-    /** Invoke `cb(a, b)` once for each unordered pair within `maxDistance` (mutual separation/overlap). */
+    /** Invoke `cb(a, b)` once for each unordered pair within finite, nonnegative `maxDistance`, including distances larger than `cellSize`. */
     forEachPair(maxDistance, cb) {
+        if (!Number.isFinite(maxDistance) || maxDistance < 0) {
+            throw new RangeError("SpatialGrid: maxDistance must be finite and nonnegative");
+        }
         const xs = this.xs;
         const zs = this.zs;
         if (xs === null || zs === null)
             return;
         const d2 = maxDistance * maxDistance;
         const nx = this.nx;
-        const nz = this.nz;
         for (let i = 0; i < this.entityCount; i += 1) {
-            const c = this.cellOfBody[i];
-            const cz = (c / nx) | 0;
-            const cx = c - cz * nx;
             const x = xs[i];
             const z = zs[i];
-            const z0 = cz > 0 ? cz - 1 : cz;
-            const z1 = cz < nz - 1 ? cz + 1 : cz;
-            const x0 = cx > 0 ? cx - 1 : cx;
-            const x1 = cx < nx - 1 ? cx + 1 : cx;
+            const z0 = this.cellZ(z - maxDistance);
+            const z1 = this.cellZ(z + maxDistance);
+            const x0 = this.cellX(x - maxDistance);
+            const x1 = this.cellX(x + maxDistance);
             for (let gz = z0; gz <= z1; gz += 1) {
                 const rowBase = gz * nx;
                 for (let gx = x0; gx <= x1; gx += 1) {

package/dist/physics/vehicleDynamics.d.ts

@@ -1,4 +1,5 @@
 import type { AxisInput } from "../input/axisInput.js";
+import type { KinematicVehicleOptions } from "./kinematicVehicle.js";
 import type { GripCurve } from "./vehicleBody.js";
 /**
  * One axle's tire, in physical terms. Lateral force follows a simplified Pacejka curve
@@ -243,8 +244,8 @@ export interface VehicleDynamicsOptions {
     heading?: number;
     /** Grip multiplier by world position (gravel, ice, wet paint); default `1`. */
     surfaceFriction?: (x: number, z: number) => number;
-    /** Clamp a planar move (walls, bounds); velocity is rederived from the allowed displacement. */
-    clampMove?: (from: readonly [number, number], to: readonly [number, number]) => readonly [number, number];
+    /** Clamp a planar move; optional result `motion` separates permitted displacement from position recovery. Called once per physics substep. */
+    clampMove?: KinematicVehicleOptions["clampMove"];
     /** Terrain height under a point; read per wheel when `suspension` is set (ramps, hills, ledges). Default flat at the spawn height. */
     groundHeight?: (x: number, z: number) => number;
 }

package/dist/physics/vehicleDynamics.js

@@ -390,8 +390,8 @@ export function createVehicleDynamics(initialTuning, options = {}) {
         const toZ = state.z + nvz * h;
         if (clampMove !== undefined && h > 0) {
             const allowed = clampMove([state.x, state.z], [toX, toZ]);
-            nvx = (allowed[0] - state.x) / h;
-            nvz = (allowed[1] - state.z) / h;
+            nvx = (allowed.motion?.[0] ?? allowed[0] - state.x) / h;
+            nvz = (allowed.motion?.[1] ?? allowed[1] - state.z) / h;
             state.x = allowed[0];
             state.z = allowed[1];
         }

package/dist/physics/vehicleObstacles.d.ts

@@ -1,4 +1,5 @@
 import { type CollisionObstacle } from "../movement/movementModel.js";
+import type { KinematicVehicleOptions } from "./kinematicVehicle.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}.
@@ -17,8 +18,8 @@ export interface VehicleImpact {
  * {@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];
+    /** Resolve an attempted XZ move; recovery endpoints carry permitted world-unit displacement in `motion`. */
+    clampMove: NonNullable<KinematicVehicleOptions["clampMove"]>;
     /** 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;
 }

package/dist/physics/vehicleObstacles.js

@@ -106,11 +106,30 @@ export function createVehicleObstacleClamp(options) {
                 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)
+            const current = [from[0], CAR_BODY_MID_Y, from[1]];
+            const solids = vehicleView(obstacles);
+            const step = resolveObstacleStep(current, attemptedX, attemptedZ, solids, radius);
+            if (attemptedX === step.stepX && attemptedZ === step.stepZ)
                 return to;
+            // The resolver's zero-step escape is the same positional recovery included in `step`.
+            // Separate it from motion using this tick's already sampled solids, never a second callback.
+            // This preserves the resolver's tangential projection, including diagonal/compound contacts.
+            const escape = resolveObstacleStep(current, 0, 0, solids, radius);
+            const recovering = escape.stepX !== 0 || escape.stepZ !== 0;
+            // Recover first, then collide the motor move at that safe origin. Otherwise the resolver
+            // excludes the penetrated box and permits driving straight back into it on every tick.
+            const motion = recovering
+                ? resolveObstacleStep([from[0] + escape.stepX, CAR_BODY_MID_Y, from[1] + escape.stepZ], attemptedX, attemptedZ, solids, radius)
+                : step;
+            // One bounded recovery pass may meet another overlapping solid. Keep that second escape
+            // positional too; overlapping/inconsistent solids never become an unbounded recovery loop.
+            const secondaryEscape = recovering
+                ? resolveObstacleStep([from[0] + escape.stepX, CAR_BODY_MID_Y, from[1] + escape.stepZ], 0, 0, solids, radius)
+                : { stepX: 0, stepZ: 0 };
+            const motionX = motion.stepX - secondaryEscape.stepX;
+            const motionZ = motion.stepZ - secondaryEscape.stepZ;
+            const blockedX = attemptedX - motionX;
+            const blockedZ = attemptedZ - motionZ;
             const blockedMag = Math.hypot(blockedX, blockedZ);
             if (blockedMag > BLOCK_EPSILON) {
                 const dt = options.dt();
@@ -123,7 +142,12 @@ export function createVehicleObstacleClamp(options) {
                     };
                 }
             }
-            return [from[0] + step.stepX, from[1] + step.stepZ];
+            const result = [from[0] + escape.stepX + motion.stepX, from[1] + escape.stepZ + motion.stepZ];
+            if (recovering) {
+                // Per-result tuples stay stable if a host retains a prior result for diagnostics.
+                return Object.assign(result, { motion: [motionX, motionZ] });
+            }
+            return result;
         },
         takeImpact() {
             const impact = pending;

package/dist/runtime/cameraDirector.d.ts

@@ -1,6 +1,32 @@
-import type { ChaseCameraConfig, ChaseView, CinematicCameraConfig } from "../game/playableGame.js";
+import type { CameraRigKind, ChaseCameraConfig, ChaseView, CinematicCameraConfig, GameCameraConfig } from "../game/playableGame.js";
+import type { GameContext } from "./gameContext.js";
+/** Data overlay for an existing rig; callbacks and Canvas projection/preferences remain configured by the game. */
+export type CameraRigConfig = Omit<GameCameraConfig, "rig" | "projection" | "pixelPerfect" | "frustum" | "playerFov" | "weapon" | "onCameraFollow">;
+/** Runtime rig selection and detached data overlay over the configured camera. */
+export interface CameraRigOverride {
+    kind: CameraRigKind;
+    config: CameraRigConfig;
+}
+/** Camera policy state before the JSON-safe snapshot number encoding. */
+export interface CameraDirectorState {
+    followEntityId?: string | null;
+    rig: CameraRigOverride | null;
+    cinematic: CinematicCameraConfig | null;
+    chase: ChaseCameraTuning | null;
+}
+type CameraSerialized<T> = T extends number ? number | {
+    $cameraNumber: "Infinity";
+} : T extends object ? {
+    [Key in keyof T]: CameraSerialized<T[Key]>;
+} : T;
+/** JSON-safe camera policy; documented instant chase responses use an explicit Infinity marker. */
+export type CameraDirectorSnapshot = CameraSerialized<CameraDirectorState>;
+/** @internal */
+export declare function validateCameraRig(kind: CameraRigKind, config?: CameraRigConfig): void;
+/** @internal */
+export declare function validateChaseCameraTuning(tuning: ChaseCameraTuning | null): void;
 /** Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11), a whole driving-feel overlay applied only while a vehicle is piloted (#1299), or a `view` switch between chase and seat cameras. */
-export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank" | "shakePerSpeed" | "velocityYaw" | "yawResponse" | "distanceBySpeed" | "pitchFollow" | "fovKick" | "lookBackAction" | "collision" | "view">>;
+export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank" | "shakePerSpeed" | "velocityYaw" | "yawResponse" | "headingSource" | "distanceBySpeed" | "pitchFollow" | "fovKick" | "lookBackAction" | "collision" | "view">>;
 /** Default order {@link nextChaseView} cycles through. */
 export declare const CHASE_VIEWS: readonly ChaseView[];
 /**
@@ -15,6 +41,9 @@ 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;
+    /** Replace the runtime rig overlay; `null` restores the game's configured rig/config. Existing chase tuning remains independent. */
+    setRig(kind: CameraRigKind | null, config?: CameraRigConfig): void;
+    rig(): CameraRigOverride | null;
     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. */
@@ -24,7 +53,15 @@ export interface CameraDirector {
     kickFov(degrees: number): void;
     /** Drain the FOV impulses queued since the last call; the shell's chase rig calls this once per frame. */
     takeFovKick(): number;
+    snapshot(): CameraDirectorSnapshot;
+    /** Invalid state throws before changing any camera field. */
+    restore(state: CameraDirectorSnapshot): void;
+    /** Clear runtime policy and transient FOV kicks; configured camera data remains untouched. */
+    reset(): void;
     subscribe(listener: () => void): () => void;
 }
 /** @internal */
 export declare function createCameraDirector(): CameraDirector;
+/** Local camera policy is saved, never broadcast to another player's presentation. @internal */
+export declare function installCameraPersistence(ctx: GameContext): void;
+export {};

package/dist/runtime/cameraDirector.js

@@ -1,3 +1,122 @@
+const RIG_KINDS = ["orbit", "first", "topDown", "rts", "shoulder", "lockOn", "chase", "observer", "turntable", "sideScroll", "inspection", "none"];
+const number = (value) => typeof value === "number" && Number.isFinite(value);
+const response = (value) => number(value) || value === Number.POSITIVE_INFINITY;
+const boolean = (value) => typeof value === "boolean";
+const string = (value) => typeof value === "string";
+const oneOf = (...values) => (value) => typeof value === "string" && values.includes(value);
+const shape = (fields, required = []) => (value) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+        return false;
+    const row = value;
+    return required.every((key) => row[key] !== undefined) && Object.entries(row).every(([key, field]) => Object.hasOwn(fields, key) && (field === undefined || fields[key](field)));
+};
+function numbers(...keys) {
+    return Object.fromEntries(keys.map((key) => [key, number]));
+}
+const point = shape(numbers("x", "y", "z"));
+const target3d = shape(numbers("x", "y", "z"), ["x", "y", "z"]);
+const topDownFields = {
+    ...numbers("height", "pitch", "yaw", "followSmoothing"), targetOffset: point,
+    zoom: shape(numbers("min", "max", "speed")),
+};
+const chaseFields = (allowInfinity) => ({
+    ...numbers("distance", "height", "lookHeight", "springDamping", "shakePerSpeed"),
+    headingSource: oneOf("body", "input"), view: oneOf("chase", "cockpit", "hood", "rear"),
+    yawResponse: allowInfinity ? response : number,
+    fov: shape({ ...numbers("base", "max", "speedForMax"), response: allowInfinity ? response : number }),
+    distanceBySpeed: shape(numbers("extra", "speedForMax"), ["extra"]),
+    pitchFollow: shape(numbers("blend", "max", "response")), fovKick: shape(numbers("decay", "max")),
+    lookBackAction: string,
+    collision: (value) => boolean(value) || shape(numbers("radius", "minDistance"))(value),
+    lead: shape(numbers("time", "max"), ["time"]), bank: shape(numbers("perYawRate", "max", "damping"), ["perYawRate"]),
+    velocityYaw: shape(numbers("blend", "minSpeed", "response")),
+});
+const cinematic = shape({
+    loop: boolean,
+    keyframes: (value) => Array.isArray(value) && value.every(shape({
+        position: target3d, lookAt: target3d, ...numbers("fov", "duration"), ease: oneOf("linear", "smooth"),
+    }, ["position", "lookAt"])),
+}, ["keyframes"]);
+const rigConfig = shape({
+    ...numbers("transitionSeconds", "minDistance", "maxDistance", "targetHeight", "initialDistance", "initialHeight", "initialYaw", "initialPitch", "rotateSpeed", "zoomSpeed", "dampingFactor", "targetSmoothing", "dragTargetSmoothing", "distanceSmoothing", "minPolarAngle", "maxPolarAngle"),
+    perspective: oneOf("third", "first"), targetOffset: point, followLock: boolean, followEnabled: boolean,
+    followEntityId: (value) => value === null || string(value),
+    pitchClamp: (value) => Array.isArray(value) && value.length === 2 && value.every(number),
+    collision: shape({ enabled: boolean, ...numbers("padding", "minTargetDistance") }),
+    firstPerson: shape({ ...numbers("eyeHeight", "sensitivity", "maxPitch"), reticle: boolean, viewmodel: boolean }),
+    topDown: shape(topDownFields),
+    rts: shape({ ...topDownFields, ...numbers("panSpeed", "rotateSpeed"), pan: boolean,
+        edgeScroll: (value) => boolean(value) || shape(numbers("margin", "speed"))(value),
+        bounds: shape(numbers("minX", "maxX", "minZ", "maxZ")), start: shape(numbers("x", "z")),
+    }),
+    shoulder: shape({ ...numbers("shoulderOffset", "heightOffset", "distance", "adsTransitionSpeed", "sensitivity", "fov"),
+        side: oneOf("left", "right"), ads: shape(numbers("distance", "shoulderOffset", "fov", "heightOffset")), reticleOffset: shape(numbers("x", "y")),
+    }),
+    lockOn: shape({ ...numbers("distance", "height", "lookHeight", "framingBias", "yawSmoothing"), targetEntityId: string }),
+    chase: shape({ ...chaseFields(true), seatOffsets: shape({ cockpit: point, hood: point, rear: point }) }),
+    observer: shape({ ...numbers("distance", "height", "lookHeight", "orbitSpeed", "startAngle", "fov"),
+        bind: (value) => shape({ kind: oneOf("entity"), entityId: string }, ["kind", "entityId"])(value) ||
+            shape({ kind: oneOf("point"), position: target3d }, ["kind", "position"])(value),
+    }),
+    turntable: shape({ ...numbers("distance", "height", "lookHeight", "orbitSpeed", "startAngle", "fov"), target: target3d }),
+    sideScroll: shape({ ...numbers("distance", "height", "lookHeight", "followSmoothing", "fov"), axis: oneOf("x", "z") }),
+    inspection: shape({ ...numbers("initialDistance", "minDistance", "maxDistance", "minPolarAngle", "maxPolarAngle", "rotateSpeed", "zoomSpeed", "dampingFactor"),
+        anchor: oneOf("target", "cursor", "center"), target: point, initialPosition: point, pan: boolean,
+    }),
+    shake: shape(numbers("maxOffset", "maxRoll", "decayPerSecond", "exponent", "frequency")), cinematic,
+});
+/** @internal */
+export function validateCameraRig(kind, config = {}) {
+    if (!RIG_KINDS.includes(kind) || !rigConfig(config))
+        throw new Error("invalid camera rig override");
+}
+/** @internal */
+export function validateChaseCameraTuning(tuning) {
+    if (tuning !== null && !shape(chaseFields(true))(tuning))
+        throw new Error("invalid chase camera tuning");
+}
+function reviveNumbers(raw) {
+    if (Array.isArray(raw))
+        return raw.map(reviveNumbers);
+    if (raw === null || typeof raw !== "object")
+        return raw;
+    if (Object.getPrototypeOf(raw) !== Object.prototype && Object.getPrototypeOf(raw) !== null)
+        return raw;
+    if (Object.keys(raw).length === 1 && "$cameraNumber" in raw && raw.$cameraNumber === "Infinity")
+        return Infinity;
+    return Object.fromEntries(Object.entries(raw).map(([key, value]) => [key, reviveNumbers(value)]));
+}
+function decodeCameraState(raw) {
+    try {
+        raw = reviveNumbers(raw);
+    }
+    catch {
+        return null;
+    }
+    if (raw === null || typeof raw !== "object")
+        return null;
+    const state = raw;
+    if (state.followEntityId !== undefined && state.followEntityId !== null && typeof state.followEntityId !== "string")
+        return null;
+    if (!("rig" in state) || !("cinematic" in state) || !("chase" in state))
+        return null;
+    try {
+        if (state.rig !== null) {
+            if (!shape({ kind: oneOf(...RIG_KINDS), config: rigConfig }, ["kind", "config"])(state.rig))
+                return null;
+        }
+        if (state.cinematic !== null && !cinematic(state.cinematic))
+            return null;
+        if (state.chase !== null && !shape(chaseFields(true))(state.chase))
+            return null;
+        return structuredClone(state);
+    }
+    catch {
+        return null;
+    }
+}
 /** Default order {@link nextChaseView} cycles through. */
 export const CHASE_VIEWS = ["chase", "hood", "cockpit"];
 /**
@@ -19,6 +138,7 @@ export function createCameraDirector() {
     let followEntity = undefined;
     let cinematicConfig = null;
     let chaseTuningPatch = null;
+    let rigOverride = null;
     let pendingFovKick = 0;
     function notify() {
         for (const listener of listeners)
@@ -30,6 +150,13 @@ export function createCameraDirector() {
             notify();
         },
         followedEntityId: () => followEntity,
+        setRig(kind, config = {}) {
+            if (kind !== null)
+                validateCameraRig(kind, config);
+            rigOverride = kind === null ? null : { kind, config: structuredClone(config) };
+            notify();
+        },
+        rig: () => rigOverride,
         setCinematic(config) {
             cinematicConfig = config;
             notify();
@@ -49,9 +176,44 @@ export function createCameraDirector() {
             pendingFovKick = 0;
             return kick;
         },
+        snapshot: () => JSON.parse(JSON.stringify({ ...(followEntity === undefined ? {} : { followEntityId: followEntity }), rig: rigOverride, cinematic: cinematicConfig, chase: chaseTuningPatch }, (_key, value) => {
+            if (value === Infinity)
+                return { $cameraNumber: "Infinity" };
+            if (typeof value === "number" && !Number.isFinite(value))
+                throw new Error("invalid camera number");
+            return value;
+        })),
+        restore(state) {
+            const decoded = decodeCameraState(state);
+            if (decoded === null)
+                throw new Error("invalid camera director state");
+            followEntity = decoded.followEntityId;
+            rigOverride = decoded.rig;
+            cinematicConfig = decoded.cinematic;
+            chaseTuningPatch = decoded.chase;
+            pendingFovKick = 0;
+            notify();
+        },
+        reset() {
+            followEntity = undefined;
+            rigOverride = null;
+            cinematicConfig = null;
+            chaseTuningPatch = null;
+            pendingFovKick = 0;
+            notify();
+        },
         subscribe(listener) {
             listeners.add(listener);
             return () => listeners.delete(listener);
         },
     };
 }
+/** Local camera policy is saved, never broadcast to another player's presentation. @internal */
+export function installCameraPersistence(ctx) {
+    ctx.game.registerSave?.({
+        key: "camera",
+        snapshot: ctx.camera.snapshot,
+        hydrate: ctx.camera.restore,
+        decode: decodeCameraState,
+    });
+}

package/dist/runtime/commandDispatch.d.ts

@@ -0,0 +1,14 @@
+import type { CommandResult } from "../commands/commandRegistry.js";
+import type { GameContext } from "./gameContext.js";
+import type { LiveGameBackend } from "./transport.js";
+/** A UI command completes locally or after its authoritative host acknowledges it. */
+export type DispatchedCommandResult = CommandResult<GameContext> | Promise<CommandResult<GameContext>>;
+type Route = {
+    transport: LiveGameBackend["transport"];
+    serverId: () => string | null;
+};
+/** Bind UI command dispatch to the host for this context. A missing join rejects; it never mutates the local replica. */
+export declare function bindCommandTransport(ctx: GameContext, route: Route): () => void;
+/** Dispatch a player's command through the bound host, or locally for an unbound offline context. Await the result before showing success. */
+export declare function dispatchCommand(ctx: GameContext, name: string, input: unknown): DispatchedCommandResult;
+export {};