@jgengine/core 0.10.0 → 0.12.0

package/dist/game/breeding.js

@@ -0,0 +1,181 @@
+/**
+ * Deterministic creature breeding & genetics — a genre-agnostic engine primitive for
+ * taming/husbandry games. Everything here operates over plain serializable records so a
+ * genome round-trips through save/load and multiplayer sync, and every random decision is
+ * driven by an injected `rng: () => number` (values in `[0, 1)`) so identical inputs and an
+ * identical rng stream always produce the identical offspring.
+ *
+ * The lifecycle it models:
+ *  - **inheritance** — each stat is drawn independently from the higher or lower parent,
+ *  - **mutation** — a bounded number of rolls that boost a stat, bump a heritable lineage
+ *    counter, and optionally flag a cosmetic/color mutation, gated by a soft cap,
+ *  - **imprint** — a rearing bonus accrued by fulfilling care requests over maturation,
+ *  - **incubation & maturation** — temperature-gated gestation viability and stage resolution.
+ *
+ * No species tables, coordinates, or game content live here; callers supply their own stat
+ * ids and tuning.
+ */
+const DEFAULT_HIGHER_STAT_CHANCE = 0.55;
+const DEFAULT_MUTATION_ROLLS = 3;
+const DEFAULT_MUTATION_CHANCE = 0.025;
+const DEFAULT_MUTATION_DELTA = 2;
+const DEFAULT_COLOR_MUTATION_CHANCE = 0.5;
+const DEFAULT_SOFT_CAP_THRESHOLD = 20;
+const DEFAULT_REDUCED_FACTOR = 0.5;
+function clamp01(x) {
+    return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+/**
+ * Per-roll mutation chance after applying the soft cap to both parents. Exposed so callers
+ * and tests can inspect the exact gating rule without breeding.
+ *
+ * @internal
+ */
+function effectiveMutationChance(a, b, config) {
+    const base = config.mutationChance ?? DEFAULT_MUTATION_CHANCE;
+    const cap = config.mutationSoftCap;
+    const threshold = cap?.threshold ?? DEFAULT_SOFT_CAP_THRESHOLD;
+    const scope = cap?.scope ?? "both";
+    const mode = cap?.mode ?? "block";
+    const aOver = a.mutationCount > threshold;
+    const bOver = b.mutationCount > threshold;
+    const capped = scope === "both" ? aOver && bOver : aOver || bOver;
+    if (!capped)
+        return base;
+    return mode === "reduce" ? base * (cap?.reducedFactor ?? DEFAULT_REDUCED_FACTOR) : 0;
+}
+/**
+ * Breed one offspring from two parents. For each stat present in either parent (iterated in
+ * sorted id order for a stable rng stream) the offspring independently inherits the higher
+ * parent's value with probability `higherStatChance` (default `0.55`), else the lower — a
+ * per-stat coin flip, so a strong parent does not guarantee a strong child. Then up to
+ * `mutationRolls` mutation rolls fire at the soft-capped chance; each success adds
+ * `mutationDelta` to a random stat, bumps the heritable `mutationCount`, and is flagged
+ * cosmetic with probability `colorMutationChance`. Lineage counters carry as the max of the
+ * two parents plus the new mutations, keeping them monotonic and heritable.
+ *
+ * Deterministic: the same parents, config, and rng sequence yield byte-identical results.
+ *
+ * @capability creature-breeding deterministic stat inheritance, mutation, and lineage genetics for taming games
+ */
+export function breedOffspring(parentA, parentB, rng, config = {}) {
+    const higherChance = config.higherStatChance ?? DEFAULT_HIGHER_STAT_CHANCE;
+    const rolls = Math.max(0, Math.floor(config.mutationRolls ?? DEFAULT_MUTATION_ROLLS));
+    const delta = config.mutationDelta ?? DEFAULT_MUTATION_DELTA;
+    const colorChance = config.colorMutationChance ?? DEFAULT_COLOR_MUTATION_CHANCE;
+    // Stable union of stat ids so the rng stream does not depend on object key order.
+    const statIds = Array.from(new Set([...Object.keys(parentA.stats), ...Object.keys(parentB.stats)])).sort();
+    const stats = {};
+    for (const id of statIds) {
+        const av = parentA.stats[id];
+        const bv = parentB.stats[id];
+        // A stat missing on one side behaves as if both parents shared the present value:
+        // one rng draw is still consumed so adding a stat to a parent cannot shift the stream.
+        const present = av ?? bv ?? 0;
+        const high = av === undefined || bv === undefined ? present : Math.max(av, bv);
+        const low = av === undefined || bv === undefined ? present : Math.min(av, bv);
+        stats[id] = rng() < higherChance ? high : low;
+    }
+    const chance = effectiveMutationChance(parentA, parentB, config);
+    const mutations = [];
+    let newMutations = 0;
+    let newColor = 0;
+    for (let i = 0; i < rolls; i++) {
+        if (rng() >= chance)
+            continue;
+        newMutations += 1;
+        let stat = "";
+        if (statIds.length > 0) {
+            const index = Math.min(statIds.length - 1, Math.floor(rng() * statIds.length));
+            stat = statIds[index];
+            stats[stat] = (stats[stat] ?? 0) + delta;
+        }
+        const color = rng() < colorChance;
+        if (color)
+            newColor += 1;
+        mutations.push({ stat, delta: stat === "" ? 0 : delta, color });
+    }
+    const genome = {
+        stats,
+        mutationCount: Math.max(parentA.mutationCount, parentB.mutationCount) + newMutations,
+        colorMutationCount: Math.max(parentA.colorMutationCount, parentB.colorMutationCount) + newColor,
+    };
+    return { genome, mutations };
+}
+const DEFAULT_STAT_BONUS = 0.2;
+const DEFAULT_HANDLER_BONUS = 0.3;
+/**
+ * Imprint gained per fulfilled care request when `requestCount` requests are scheduled over
+ * the maturation window: `1 / requestCount`, so fulfilling every request reaches full (1.0)
+ * imprint. Returns `0` for a non-positive request count.
+ *
+ * @capability imprint-increment per-care-request imprint gain across a maturation schedule
+ */
+export function imprintIncrementPerRequest(requestCount) {
+    return requestCount > 0 ? 1 / requestCount : 0;
+}
+/**
+ * Apply the imprint rearing bonus to a stat block. Every stat is scaled by
+ * `1 + statBonusAtFull * imprint`; when `asOwner` is set, the imprinting handler additionally
+ * gets `1 + handlerBonusAtFull * imprint`. `imprint` is a 0..1 fraction (clamped) and scales
+ * both bonuses linearly, so half-imprint yields half the bonus. Returns a fresh stat block.
+ *
+ * @capability imprint-bonus apply imprint stat and handler bonuses at an imprint fraction
+ */
+export function applyImprintBonus(stats, imprint, config = {}, options = {}) {
+    const fraction = clamp01(imprint);
+    const statBonus = config.statBonusAtFull ?? DEFAULT_STAT_BONUS;
+    const handlerBonus = config.handlerBonusAtFull ?? DEFAULT_HANDLER_BONUS;
+    let multiplier = 1 + statBonus * fraction;
+    if (options.asOwner)
+        multiplier *= 1 + handlerBonus * fraction;
+    const out = {};
+    for (const id of Object.keys(stats))
+        out[id] = stats[id] * multiplier;
+    return out;
+}
+/**
+ * Advance incubation one tick. While `temperature` is within `[minTemp, maxTemp]` the embryo
+ * makes progress (`elapsed += dt`) and keeps its health; outside the range it makes no
+ * progress and loses `healthLossPerTick * dt` health (clamped at `0`). Pure — returns a new
+ * state, never mutates the input.
+ *
+ * @capability incubation-tick advance egg incubation health inside/outside its temperature range
+ */
+export function tickIncubation(state, temperature, dt, config) {
+    if (dt <= 0)
+        return { health: state.health, elapsed: state.elapsed };
+    const inRange = temperature >= config.minTemp && temperature <= config.maxTemp;
+    if (inRange)
+        return { health: state.health, elapsed: state.elapsed + dt };
+    const loss = (config.healthLossPerTick ?? 1) * dt;
+    return { health: Math.max(0, state.health - loss), elapsed: state.elapsed };
+}
+/**
+ * True while the incubation still has health to hatch.
+ *
+ * @capability incubation-viability test whether an egg incubation still has health to hatch
+ */
+export function incubationViable(state) {
+    return state.health > 0;
+}
+/**
+ * Resolve the maturation stage for an elapsed time against a duration. Computes the clamped
+ * `elapsed / duration` fraction and returns the id of the last stage whose `at` threshold has
+ * been reached (boundaries inclusive). Stages need not be pre-sorted. Returns `""` when no
+ * stage qualifies (e.g. an empty list or all thresholds above the current fraction).
+ *
+ * @capability maturation-stage resolve the baby/juvenile/adolescent/adult stage from elapsed maturation
+ */
+export function maturationStage(elapsed, duration, stages) {
+    const fraction = duration > 0 ? clamp01(elapsed / duration) : 1;
+    let bestId = "";
+    let bestAt = -Infinity;
+    for (const stage of stages) {
+        if (stage.at <= fraction && stage.at >= bestAt) {
+            bestAt = stage.at;
+            bestId = stage.id;
+        }
+    }
+    return bestId;
+}

package/dist/game/cameraConfig.d.ts

@@ -0,0 +1,451 @@
+export interface CameraFollowState {
+    entityId: string;
+    target: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    camera: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    distance: number;
+}
+export interface FirstPersonCameraConfig {
+    /** Camera height above the followed entity's origin. Default 1.6. */
+    eyeHeight?: number;
+    /** Mouse-look radians per pixel of pointer movement. Default 0.0025. */
+    sensitivity?: number;
+    /** Clamp on look pitch in radians (± from horizon). Default 1.45. */
+    maxPitch?: number;
+    /** Show the centered crosshair overlay. Default true. */
+    reticle?: boolean;
+    /** Render a viewmodel in view: the built-in three-mesh gun, or `PlayableGame.viewmodel` when set (#542). `false` renders no viewmodel regardless of `PlayableGame.viewmodel`. Default true. */
+    viewmodel?: boolean;
+}
+/**
+ * Which camera rig the shell mounts. Every rig accepts `followEntityId: null`
+ * (avatar-less games — city-builders, card games, auto-battlers — still get a
+ * camera). Rigs are tuned through their config block below, never by writing
+ * camera positions from `onTick`.
+ * - `orbit` — third-person chase (the historical default; `perspective: "third"`).
+ * - `first` — pointer-lock mouse-look (`perspective: "first"`).
+ * - `topDown` — fixed height/pitch/yaw with decoupled follow (ARPG iso, top-down).
+ * - `rts` — free-pan / edge-scroll / rotate / zoom, optional follow.
+ * - `shoulder` — over-the-shoulder with ADS transition + shoulder swap.
+ * - `lockOn` — yaw bound to the player→target vector; move axis becomes strafe.
+ * - `chase` — speed-reactive vehicle chase (speed→FOV, spring arm, shake) + cockpit/hood/rear views.
+ * - `observer` — detached spectator/photo cam bound to any entity or fixed point; never reads player input.
+ * - `turntable` — slow auto-orbit of a fixed point: a rotating display stand for a scene. The friendly, flat spelling of `observer`'s point-orbit mode; providing `camera.turntable` selects it without an explicit `rig`.
+ * - `sideScroll` — fixed lateral follow (2.5D platformer/beat-'em-up side view); reads no player input.
+ * - `inspection` — model-viewer / editor rig (#207.7, #866): middle-drag pan, right-drag orbit, scroll zoom toward a configurable anchor; orbits a fixed point, reads no player/entity input.
+ * - `none` — no camera rig is mounted; use for HUD-only presentations or a game that manages its own camera.
+ */
+export type CameraRigKind = "orbit" | "first" | "topDown" | "rts" | "shoulder" | "lockOn" | "chase" | "observer" | "turntable" | "sideScroll" | "inspection" | "none";
+/** Canvas camera projection. "orthographic" renders a flat 2D-style view (side-scrollers, falling-block puzzles) — pair with `rig: "sideScroll"`; default "perspective". */
+export type CameraProjection = "perspective" | "orthographic";
+/** Fixed lateral 2.5D follow (side-on platformer cam): the camera sits perpendicular to the travel axis, tracks the followed entity, and never reads player look input. */
+export interface SideScrollCameraConfig {
+    /** World axis the action travels along; the camera watches from the perpendicular side. Default "x". */
+    axis?: "x" | "z";
+    /** Camera distance from the followed entity along the perpendicular axis. Default 10. */
+    distance?: number;
+    /** Camera height above the followed entity. Default 3. */
+    height?: number;
+    /** Height of the look point above the entity. Default 1. */
+    lookHeight?: number;
+    /** Per-second smoothing factor for the follow (0 hard-locks). Default 8. */
+    followSmoothing?: number;
+    fov?: number;
+}
+/** Fixed top-down / isometric rig (#23) — height/pitch/yaw + decoupled follow. */
+export interface TopDownCameraConfig {
+    /** Camera height above the follow point. Default 18. */
+    height?: number;
+    /** Elevation of the camera above the ground plane in radians (PI/2 = straight down, near 0 = grazing; values below 0.05 clamp to 0.05). Default ~1.02 (~58°, ARPG iso). */
+    pitch?: number;
+    /** Fixed azimuth in radians; ~PI/4 reads as isometric, 0 as straight top-down. Default PI/4. */
+    yaw?: number;
+    /** Horizontal look offset applied to the follow point. */
+    targetOffset?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** Exponential follow smoothing (higher = snappier, decoupled from any orbit drag). Default 8. */
+    followSmoothing?: number;
+    /** Scroll zoom bounds as a height multiplier. */
+    zoom?: {
+        min?: number;
+        max?: number;
+        speed?: number;
+    };
+}
+/** Free-pan / edge-scroll RTS rig (#24) — pan/rotate/zoom independent of any avatar. */
+export interface RtsCameraConfig extends TopDownCameraConfig {
+    /** WASD / arrow pan speed in world units per second. Default 24. */
+    panSpeed?: number;
+    /** Edge-scroll when the pointer nears a screen edge; number sets the margin fraction. Default true. */
+    edgeScroll?: boolean | {
+        margin?: number;
+        speed?: number;
+    };
+    /** Yaw rotate speed (radians/sec) for rotate keys / middle-drag. Default 1.4. */
+    rotateSpeed?: number;
+    /** World-space clamp for the pan center. */
+    bounds?: {
+        minX?: number;
+        maxX?: number;
+        minZ?: number;
+        maxZ?: number;
+    };
+    /** Start centered on this world point when there is no follow target. */
+    start?: {
+        x?: number;
+        z?: number;
+    };
+    /** Read WASD/arrow pan, edge-scroll, Q/E rotate, and wheel zoom. `false` sits static at the start/bounds position — a backdrop camera, no input at all. Default true. */
+    pan?: boolean;
+}
+/** Over-the-shoulder combat rig (#25) — offset, ADS, shoulder swap, decoupled reticle. */
+export interface ShoulderCameraConfig {
+    /** Lateral shoulder offset (world units, sign flips on swap). Default 0.6. */
+    shoulderOffset?: number;
+    /** Vertical offset above the follow point. Default 1.6. */
+    heightOffset?: number;
+    /** Boom distance behind the shoulder. Default 3.2. */
+    distance?: number;
+    /** Starting shoulder side. Default "right". */
+    side?: "left" | "right";
+    /** Aim-down-sights framing, blended in while `aim` is held. */
+    ads?: {
+        distance?: number;
+        shoulderOffset?: number;
+        fov?: number;
+        heightOffset?: number;
+    };
+    /** ADS blend speed (higher = snappier). Default 10. */
+    adsTransitionSpeed?: number;
+    /** Screen-space reticle offset (fraction of viewport), decoupled from camera center. */
+    reticleOffset?: {
+        x?: number;
+        y?: number;
+    };
+    /** Mouse-look sensitivity (radians per pixel). Default 0.0025. */
+    sensitivity?: number;
+    /** Base field of view. Default 55. */
+    fov?: number;
+}
+/** Lock-on / strafe rig (#26) — yaw bound to player→target, move axis becomes strafe. */
+export interface LockOnCameraConfig {
+    /** Target instance id; when omitted the rig reads the follower's current `getTarget`. */
+    targetEntityId?: string;
+    /** Boom distance behind the player, away from the target. Default 5. */
+    distance?: number;
+    /** Camera height above the follow point. Default 2.4. */
+    height?: number;
+    /** Height of the framed look point above the midpoint. Default 1.2. */
+    lookHeight?: number;
+    /** 0 frames the player, 1 frames the target, 0.5 the midpoint. Default 0.5. */
+    framingBias?: number;
+    /** Exponential yaw smoothing toward the player→target vector. Default 9. */
+    yawSmoothing?: number;
+}
+/** Fixed interior view for the chase rig (#27). */
+export type ChaseView = "chase" | "cockpit" | "hood" | "rear";
+/** Speed-reactive vehicle chase rig (#27) — speed→FOV, spring arm, procedural shake, interior views. */
+export interface ChaseCameraConfig {
+    /** Boom distance behind the vehicle. Default 6. */
+    distance?: number;
+    /** Camera height above the follow point. Default 2.6. */
+    height?: number;
+    /** Height of the look point above the follow point. Default 1.2. */
+    lookHeight?: number;
+    /** Spring-arm damping (higher = stiffer, less lag). Default 6. */
+    springDamping?: number;
+    /** Speed→FOV curve: FOV lerps from `base` to `max` as speed climbs to `speedForMax`. */
+    fov?: {
+        base?: number;
+        max?: number;
+        speedForMax?: number;
+    };
+    /** Procedural shake amplitude per unit of speed (adds to the trauma channel). Default 0.0. */
+    shakePerSpeed?: number;
+    /** Velocity-lead / predictive follow (#286.9): the rig aims `time` seconds ahead of the target along its velocity, clamped to `max` world units (default 4). */
+    lead?: {
+        time: number;
+        max?: number;
+    };
+    /** Roll into turns (#286.10): radians of camera roll per rad/s of the target's yaw rate, clamped to `max` (default 0.35), exponentially smoothed by `damping` (default 8). */
+    bank?: {
+        perYawRate: number;
+        max?: number;
+        damping?: number;
+    };
+    /**
+     * Drift-lag (#1051): when the target slides, rotate the chase anchor partway from
+     * its heading toward its travel (velocity) direction so the player sees the car's
+     * side while the framing stays stable. Omitting the block keeps the pure-heading
+     * behavior. `blend` (default 0.65) is the max fraction of the slip angle to
+     * follow, itself scaled by how far the slip has opened so straight-line driving
+     * is untouched; below `minSpeed` (default 4) planar speed the feature is off for
+     * parking-lot stability; reversing never swings the camera around. `response`
+     * (default 6) drives `1-exp(-response*dt)` smoothing toward the blended yaw.
+     */
+    velocityYaw?: {
+        blend?: number;
+        minSpeed?: number;
+        response?: number;
+    };
+    /** Which view to mount. Default "chase". */
+    view?: ChaseView;
+    /** Local offset for cockpit/hood/rear seats (relative to the vehicle, +z forward). */
+    seatOffsets?: {
+        cockpit?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+        hood?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+        rear?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+    };
+}
+/** Detached spectator/photo cam (#120) — binds to any entity or fixed point, never reads player input. */
+export interface ObserverCameraConfig {
+    /** What the observer looks at. Omit to stay on a fixed point at the origin (or `point`, if given). */
+    bind?: {
+        kind: "entity";
+        entityId: string;
+    } | {
+        kind: "point";
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    };
+    /** Orbit distance from the bound subject. Default 8. */
+    distance?: number;
+    /** Camera height above the bound subject. Default 3. */
+    height?: number;
+    /** Height of the look point above the subject. Default 1.2. */
+    lookHeight?: number;
+    /** Radians/second of automatic orbit around the subject (CCTV-style sweep); 0 holds a fixed angle. Default 0.2. */
+    orbitSpeed?: number;
+    /** Starting orbit angle in radians. Default 0. */
+    startAngle?: number;
+    fov?: number;
+}
+/**
+ * Turntable / showcase rig — slowly auto-orbits a fixed world point (no player
+ * input), the way a museum turntable rotates an object on display. A flat,
+ * self-describing spelling of `observer`'s point-orbit mode: `target` names the
+ * point directly instead of `bind: { kind: "point", position }`. Set
+ * `camera.turntable` and the rig is inferred — you don't also write `rig`.
+ */
+export interface TurntableCameraConfig {
+    /** World point the camera circles. Default the world origin. */
+    target?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Orbit radius from the target. Default 8. */
+    distance?: number;
+    /** Camera height above the target. Default 3. */
+    height?: number;
+    /** Height of the look point above the target. Default 1.2. */
+    lookHeight?: number;
+    /** Radians/second of rotation; 0 holds a fixed angle. Default 0.2. */
+    orbitSpeed?: number;
+    /** Starting angle in radians. Default 0. */
+    startAngle?: number;
+    fov?: number;
+}
+/**
+ * How scroll-zoom re-anchors the view for the inspection rig (#207.7):
+ * - `target` — dolly toward the orbit target (classic OrbitControls behavior).
+ * - `cursor` — dolly toward the point under the pointer.
+ * - `center` — dolly toward the viewport center; equivalent to `target` for an
+ *   OrbitControls-driven rig, since the camera always faces `target` and that
+ *   point already projects to the exact center of the viewport.
+ */
+export type InspectionZoomAnchor = "target" | "cursor" | "center";
+/** Model-viewer / inspection rig (#207.7) — orbit + pan + anchored zoom around a fixed point, never reads player input. */
+export interface InspectionCameraConfig {
+    /** Where scroll-zoom re-anchors the view. Default "target". */
+    anchor?: InspectionZoomAnchor;
+    /** Orbit target (the point orbited/panned around). Default origin. */
+    target?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** Camera distance from `target` used to seed the initial camera position when `initialPosition` is unset. Default 6. */
+    initialDistance?: number;
+    /** Explicit starting camera world position; overrides `initialDistance` when set. */
+    initialPosition?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    minDistance?: number;
+    maxDistance?: number;
+    /** Vertical orbit clamp (radians). Unset allows a full pole-to-pole orbit, unlike the tighter default on the classic orbit rig. */
+    minPolarAngle?: number;
+    maxPolarAngle?: number;
+    /** Middle-mouse pan. Default true for this rig. */
+    pan?: boolean;
+    rotateSpeed?: number;
+    zoomSpeed?: number;
+    dampingFactor?: number;
+}
+/** One stop on a scripted camera path (#29). */
+export interface CameraKeyframe {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    lookAt: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    fov?: number;
+    /** Seconds to travel from the previous keyframe to this one. Default 1. */
+    duration?: number;
+    /** Interpolation into this keyframe. Default "smooth" (smoothstep ease). */
+    ease?: "linear" | "smooth";
+}
+/** Scripted keyframe / path player (#29). When set it overrides the active rig. */
+export interface CinematicCameraConfig {
+    keyframes: readonly CameraKeyframe[];
+    /** Restart from the first keyframe after the last. Default false. */
+    loop?: boolean;
+}
+/** Camera-shake / trauma defaults (#28). Any rig reads the trauma channel; game systems feed it via `cameraShake()`. */
+export interface CameraShakeConfig {
+    /** Positional shake amplitude at full trauma (world units). Default 0.5. */
+    maxOffset?: number;
+    /** Rotational shake amplitude at full trauma (radians). Default 0.06. */
+    maxRoll?: number;
+    /** Trauma decay per second (fraction). Default 1.6. */
+    decayPerSecond?: number;
+    /** Trauma→shake exponent; 2 = quadratic falloff so small hits are subtle. Default 2. */
+    exponent?: number;
+    /** Noise frequency (Hz) of the shake oscillation. Default 24. */
+    frequency?: number;
+}
+export declare const CAMERA_FRUSTUM_DEFAULTS: {
+    readonly fov: 55;
+    readonly near: 0.1;
+    readonly far: 300;
+    readonly zoom: 50;
+};
+/** Player-facing FOV preference applied across every perspective camera rig. Orthographic projections ignore it. */
+export interface PlayerFovConfig {
+    /** Inclusive lower bound for the slider and persisted values. Default 40. */
+    min?: number;
+    /** Inclusive upper bound for the slider and persisted values. Default 120. */
+    max?: number;
+    /** Initial FOV when nothing is persisted. Defaults to `frustum.fov` or 55. */
+    default?: number;
+    /** Persist the preference in localStorage across reloads. Default true. */
+    persist?: boolean;
+    /** Show the shell FOV slider. Default true for perspective cameras; forced off for orthographic. */
+    control?: boolean;
+}
+/** Camera tuning for the shell's rig stack: pick the rig via `rig`, then tune it through its matching config block. All fields optional — the default is the third-person orbit rig. */
+export interface GameCameraConfig {
+    /** Selects the rig — the one camera-selection knob. Overrides the legacy `perspective` shorthand. */
+    rig?: CameraRigKind;
+    /** Canvas camera projection. "orthographic" renders a flat 2D-style view (side-scrollers, falling-block puzzles) — pair with `rig: "sideScroll"`; default perspective. */
+    projection?: CameraProjection;
+    /** Render frustum overrides applied to the canvas camera. `far` defaults to 300 — raise it for worlds whose content spans more than a few hundred units, or distant scenery silently clips. `zoom` is the orthographic zoom in canvas pixels per world unit, read only when `projection` is "orthographic"; default 50. */
+    frustum?: {
+        fov?: number;
+        near?: number;
+        far?: number;
+        zoom?: number;
+    };
+    /** Universal player FOV preference (slider + persistence) for perspective rigs. Ignored when `projection` is `"orthographic"`. */
+    playerFov?: PlayerFovConfig;
+    /** @deprecated Legacy shorthand for `rig: "orbit" | "first"` — set `rig` instead. "third" mounts the orbit camera (default); "first" mounts pointer-lock mouse-look. */
+    perspective?: "third" | "first";
+    /** First-person tuning; only read when the rig resolves to "first". */
+    firstPerson?: FirstPersonCameraConfig;
+    /** Top-down / isometric tuning (#23); read when `rig: "topDown"`. */
+    topDown?: TopDownCameraConfig;
+    /** Free-pan / edge-scroll RTS tuning (#24); read when `rig: "rts"`. */
+    rts?: RtsCameraConfig;
+    /** Over-the-shoulder tuning (#25); read when `rig: "shoulder"`. */
+    shoulder?: ShoulderCameraConfig;
+    /** Lock-on / strafe tuning (#26); read when `rig: "lockOn"`. */
+    lockOn?: LockOnCameraConfig;
+    /** Vehicle chase tuning (#27); read when `rig: "chase"`. */
+    chase?: ChaseCameraConfig;
+    /** Detached spectator/photo cam tuning (#120); read when `rig: "observer"`. */
+    observer?: ObserverCameraConfig;
+    /** Turntable / showcase tuning; setting this selects the `turntable` rig on its own. */
+    turntable?: TurntableCameraConfig;
+    /** Fixed side-on follow tuning; read when `rig: "sideScroll"`. */
+    sideScroll?: SideScrollCameraConfig;
+    /** Model-viewer / inspection tuning (#207.7); read when `rig: "inspection"`. */
+    inspection?: InspectionCameraConfig;
+    /** Camera-shake / trauma channel defaults (#28); read by every rig. */
+    shake?: CameraShakeConfig;
+    /** Scripted keyframe path (#29); when set, plays over the active rig. */
+    cinematic?: CinematicCameraConfig;
+    /** Seconds to cross-fade the camera when the rig changes (#29). 0 hard-cuts. Default 0.6. */
+    transitionSeconds?: number;
+    minDistance?: number;
+    maxDistance?: number;
+    targetHeight?: number;
+    /** Extra offset on top of entity position for the orbit target. */
+    targetOffset?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    initialDistance?: number;
+    initialHeight?: number;
+    /** Initial horizontal boom facing (radians): 0 = camera behind on -Z, PI = camera on +Z. Seeds the orbit rig; unset keeps the legacy -Z placement. */
+    initialYaw?: number;
+    /** Initial boom elevation (radians): 0 = level, positive = camera above the target looking down. Seeds the orbit rig; unset derives elevation from `initialHeight`/`initialDistance`. */
+    initialPitch?: number;
+    /** Lock orbit radius while the follow target moves (default true in shell). */
+    followLock?: boolean;
+    /** When false, orbit target stays fixed (cinematic / debug). Default true. */
+    followEnabled?: boolean;
+    /** Instance id to follow, or null for an avatar-less free camera; defaults to local player in the dev shell. */
+    followEntityId?: string | null;
+    /** Fired each frame after cameraFollow lock is applied. */
+    onCameraFollow?: (state: CameraFollowState) => void;
+    rotateSpeed?: number;
+    zoomSpeed?: number;
+    dampingFactor?: number;
+    targetSmoothing?: number;
+    dragTargetSmoothing?: number;
+    distanceSmoothing?: number;
+    /** Vertical look clamp (three.js polar angle, radians): 0 = top-down over the head, PI/2 = level, >PI/2 = look up from below. Widen for top-down or vertical aim; unset keeps the standard chase feel. */
+    minPolarAngle?: number;
+    maxPolarAngle?: number;
+    /** Signed boom-elevation clamp `[min, max]` (radians): min < 0 dips the camera below the target, max > 0 rises overhead. Maps onto `minPolarAngle`/`maxPolarAngle` (polar = PI/2 − pitch); explicit polar fields win. */
+    pitchClamp?: readonly [number, number];
+    /** Spring-arm occlusion for the orbit rig: pull the camera in past walls/terrain so it never clips inside geometry. Off unless `enabled`. */
+    collision?: {
+        enabled?: boolean;
+        padding?: number;
+        minTargetDistance?: number;
+    };
+}

package/dist/game/cameraConfig.js

@@ -0,0 +1 @@
+export const CAMERA_FRUSTUM_DEFAULTS = { fov: 55, near: 0.1, far: 300, zoom: 50 };

package/dist/game/connectedPlayers.d.ts

@@ -1,10 +1,10 @@
 import type { InputFrame } from "../runtime/inputSnapshot.js";
-/** A player currently joined to a hosted world — the unit a shared-world loop iterates instead of `ctx.player`. */
+/** A player currently joined to a hosted world — the unit a shared-world loop iterates instead of `ctx.player`. Frozen by the registry (see {@link ConnectedPlayers.get}); fields are `readonly` so a caller can't edit its own copy and assume the change stuck. */
 export interface ConnectedPlayer {
-    userId: string;
-    isNew: boolean;
+    readonly userId: string;
+    readonly isNew: boolean;
     /** This player's latest {@link InputFrame}, written by the host each time the client sends input; `null` until the first frame arrives. The per-player movement seam reads it in `onTick`. */
-    input: InputFrame | null;
+    readonly input: InputFrame | null;
 }
 /**
  * The set of players connected to one hosted world. A single-player game uses `ctx.player`; a shared-world loop
@@ -15,7 +15,9 @@ export interface ConnectedPlayers {
     join(userId: string, isNew: boolean): void;
     leave(userId: string): boolean;
     has(userId: string): boolean;
+    /** Returns a frozen `ConnectedPlayer` — mutating it (or reassigning `.input`) throws instead of corrupting the registry. */
     get(userId: string): ConnectedPlayer | null;
+    /** Frozen `ConnectedPlayer` entries, same immutability contract as {@link get}. */
     list(): readonly ConnectedPlayer[];
     ids(): readonly string[];
     count(): number;

package/dist/game/connectedPlayers.js

@@ -3,7 +3,7 @@ export function createConnectedPlayers() {
     const players = new Map();
     return {
         join(userId, isNew) {
-            players.set(userId, { userId, isNew, input: null });
+            players.set(userId, Object.freeze({ userId, isNew, input: null }));
         },
         leave: (userId) => players.delete(userId),
         has: (userId) => players.has(userId),
@@ -14,7 +14,7 @@ export function createConnectedPlayers() {
         setInput(userId, frame) {
             const player = players.get(userId);
             if (player !== undefined)
-                player.input = frame;
+                players.set(userId, Object.freeze({ ...player, input: frame }));
         },
         input: (userId) => players.get(userId)?.input ?? null,
     };