@jgengine/core 0.8.0 → 0.9.0

package/dist/faction/factions.js

@@ -0,0 +1,76 @@
+export function createFactionGraph(config) {
+    const symmetric = config.symmetric ?? true;
+    const unaligned = config.unaligned ?? "neutral";
+    const defs = new Map();
+    for (const def of config.factions)
+        defs.set(def.id, def);
+    function relationBetween(observer, other) {
+        if (observer == null || other == null)
+            return unaligned;
+        const from = defs.get(observer);
+        const to = defs.get(other);
+        if (from === undefined || to === undefined)
+            return unaligned;
+        if (observer === other)
+            return from.towardSelf ?? "friendly";
+        const direct = from.relations?.[other];
+        if (direct !== undefined)
+            return direct;
+        if (symmetric) {
+            const mirrored = to.relations?.[observer];
+            if (mirrored !== undefined)
+                return mirrored;
+        }
+        return from.towardOthers ?? "neutral";
+    }
+    return {
+        relationBetween,
+        isHostile: (observer, other) => relationBetween(observer, other) === "hostile",
+        isFriendly: (observer, other) => relationBetween(observer, other) === "friendly",
+        isNeutral: (observer, other) => relationBetween(observer, other) === "neutral",
+        has: (factionId) => defs.has(factionId),
+        ids: () => [...defs.keys()],
+    };
+}
+export function createFactionRoster(graph) {
+    const membership = new Map();
+    function factionOf(entityId) {
+        return membership.get(entityId) ?? null;
+    }
+    function relationBetweenEntities(observer, other) {
+        return graph.relationBetween(factionOf(observer), factionOf(other));
+    }
+    return {
+        assign(entityId, factionId) {
+            if (factionId === null)
+                membership.delete(entityId);
+            else
+                membership.set(entityId, factionId);
+        },
+        factionOf,
+        relationBetweenEntities,
+        isHostile: (observer, other) => relationBetweenEntities(observer, other) === "hostile",
+        isFriendly: (observer, other) => relationBetweenEntities(observer, other) === "friendly",
+        members(factionId) {
+            const out = [];
+            for (const [entityId, id] of membership)
+                if (id === factionId)
+                    out.push(entityId);
+            return out;
+        },
+        hostilesOf(observer, candidates) {
+            const out = [];
+            for (const id of candidates) {
+                if (id !== observer && relationBetweenEntities(observer, id) === "hostile")
+                    out.push(id);
+            }
+            return out;
+        },
+        remove(entityId) {
+            membership.delete(entityId);
+        },
+        clear() {
+            membership.clear();
+        },
+    };
+}

package/dist/faction/reputation.d.ts

@@ -0,0 +1,32 @@
+import type { FactionRelation } from "./factions.js";
+export interface ReputationTier {
+    id: string;
+    min: number;
+    relation: FactionRelation;
+}
+export declare const DEFAULT_REPUTATION_TIERS: readonly ReputationTier[];
+export declare function tierForStanding(tiers: readonly ReputationTier[], standing: number): ReputationTier;
+export interface ReputationLedgerConfig {
+    tiers?: readonly ReputationTier[];
+    initial?: Readonly<Record<string, number>>;
+    min?: number;
+    max?: number;
+}
+export interface ReputationLedger {
+    standing(actorId: string, factionId: string): number;
+    hasStanding(actorId: string, factionId: string): boolean;
+    gain(actorId: string, factionId: string, amount: number): number;
+    set(actorId: string, factionId: string, standing: number): number;
+    tier(actorId: string, factionId: string): ReputationTier;
+    relation(actorId: string, factionId: string): FactionRelation;
+    standings(actorId: string): Record<string, number>;
+    reset(actorId: string, factionId?: string): void;
+}
+export declare function createReputationLedger(config?: ReputationLedgerConfig): ReputationLedger;
+export interface EffectiveRelationInput {
+    base: FactionRelation;
+    ledger: ReputationLedger;
+    actorId: string;
+    factionId: string;
+}
+export declare function effectiveRelation(input: EffectiveRelationInput): FactionRelation;

package/dist/faction/reputation.js

@@ -0,0 +1,82 @@
+export const DEFAULT_REPUTATION_TIERS = [
+    { id: "hated", min: -42000, relation: "hostile" },
+    { id: "hostile", min: -6000, relation: "hostile" },
+    { id: "unfriendly", min: -3000, relation: "neutral" },
+    { id: "neutral", min: 0, relation: "neutral" },
+    { id: "friendly", min: 3000, relation: "friendly" },
+    { id: "honored", min: 9000, relation: "friendly" },
+    { id: "revered", min: 21000, relation: "friendly" },
+    { id: "exalted", min: 42000, relation: "friendly" },
+];
+export function tierForStanding(tiers, standing) {
+    let match = tiers[0];
+    for (const tier of tiers) {
+        if (standing >= tier.min && tier.min >= match.min)
+            match = tier;
+    }
+    return match;
+}
+export function createReputationLedger(config = {}) {
+    const tiers = [...(config.tiers ?? DEFAULT_REPUTATION_TIERS)].sort((a, b) => a.min - b.min);
+    const initial = config.initial ?? {};
+    const min = config.min ?? Number.NEGATIVE_INFINITY;
+    const max = config.max ?? Number.POSITIVE_INFINITY;
+    const records = new Map();
+    function clamp(value) {
+        return Math.min(max, Math.max(min, value));
+    }
+    function standing(actorId, factionId) {
+        const stored = records.get(actorId)?.get(factionId);
+        if (stored !== undefined)
+            return stored;
+        return initial[factionId] ?? 0;
+    }
+    function store(actorId, factionId, value) {
+        const clamped = clamp(value);
+        let row = records.get(actorId);
+        if (row === undefined) {
+            row = new Map();
+            records.set(actorId, row);
+        }
+        row.set(factionId, clamped);
+        return clamped;
+    }
+    return {
+        standing,
+        hasStanding(actorId, factionId) {
+            return records.get(actorId)?.has(factionId) === true || initial[factionId] !== undefined;
+        },
+        gain(actorId, factionId, amount) {
+            return store(actorId, factionId, standing(actorId, factionId) + amount);
+        },
+        set(actorId, factionId, value) {
+            return store(actorId, factionId, value);
+        },
+        tier(actorId, factionId) {
+            return tierForStanding(tiers, standing(actorId, factionId));
+        },
+        relation(actorId, factionId) {
+            return tierForStanding(tiers, standing(actorId, factionId)).relation;
+        },
+        standings(actorId) {
+            const out = { ...initial };
+            const row = records.get(actorId);
+            if (row !== undefined)
+                for (const [factionId, value] of row)
+                    out[factionId] = value;
+            return out;
+        },
+        reset(actorId, factionId) {
+            if (factionId === undefined)
+                records.delete(actorId);
+            else
+                records.get(actorId)?.delete(factionId);
+        },
+    };
+}
+export function effectiveRelation(input) {
+    if (input.ledger.hasStanding(input.actorId, input.factionId)) {
+        return input.ledger.relation(input.actorId, input.factionId);
+    }
+    return input.base;
+}

package/dist/game/chat.d.ts

@@ -1,4 +1,5 @@
 import type { GameEvents } from "./events.js";
+import type { ChatFilter } from "./chatFilter.js";
 import type { EmotesDeps } from "./social.js";
 export type ChatChannelKind = "global" | "party" | "proximity";
 export interface ChatRateLimit {
@@ -52,6 +53,7 @@ export interface ChatDeps {
     blockedBy?: (userId: string) => readonly string[];
     maxBodyLength?: number;
     defaultRateLimit?: ChatRateLimit;
+    filter?: ChatFilter;
 }
 export declare const DEFAULT_CHAT_RATE_LIMIT: ChatRateLimit;
 export declare const DEFAULT_CHAT_HISTORY_LIMIT = 100;

package/dist/game/chat.js

@@ -34,6 +34,7 @@ export function createChat(deps) {
     const maxBodyLength = deps.maxBodyLength ?? DEFAULT_CHAT_BODY_LENGTH;
     const defaultRateLimit = deps.defaultRateLimit ?? DEFAULT_CHAT_RATE_LIMIT;
     const blockedBy = deps.blockedBy ?? (() => []);
+    const filter = deps.filter;
     const channelDefs = new Map();
     for (const def of BUILTIN_CHANNELS)
         channelDefs.set(def.id, { ...def });
@@ -97,6 +98,13 @@ export function createChat(deps) {
             return { reason: "empty message" };
         if (trimmed.length > maxBodyLength)
             return { reason: "message too long" };
+        let filteredBody = trimmed;
+        if (filter !== undefined) {
+            const filtered = filter.apply(trimmed);
+            if (!filtered.ok)
+                return { reason: "filtered" };
+            filteredBody = filtered.body;
+        }
         const resolved = resolveRecipients(fromUserId, channelId, def);
         if ("reason" in resolved)
             return resolved;
@@ -110,7 +118,7 @@ export function createChat(deps) {
             id: `msg_${counter}`,
             channelId,
             fromUserId,
-            body: trimmed,
+            body: filteredBody,
             at,
         };
         append(channelId, message, def?.historyLimit ?? DEFAULT_CHAT_HISTORY_LIMIT);

package/dist/game/chatFilter.d.ts

@@ -0,0 +1,15 @@
+export interface ChatFilterConfig {
+    blockedWords: readonly string[];
+    mode?: "mask" | "reject";
+    mask?: string;
+}
+export interface ChatFilterResult {
+    ok: boolean;
+    body: string;
+    matched: readonly string[];
+}
+export interface ChatFilter {
+    apply(body: string): ChatFilterResult;
+}
+export declare function normalizeChatText(text: string): string;
+export declare function createChatFilter(config: ChatFilterConfig): ChatFilter;

package/dist/game/chatFilter.js

@@ -0,0 +1,55 @@
+const LEET_SUBSTITUTIONS = {
+    "0": "o",
+    "1": "i",
+    "3": "e",
+    "4": "a",
+    "5": "s",
+    "7": "t",
+    "@": "a",
+    $: "s",
+    "!": "i",
+};
+const TOKEN_PATTERN = /[\p{L}\p{N}@$!]+/gu;
+export function normalizeChatText(text) {
+    let normalized = "";
+    for (const char of text.toLowerCase()) {
+        normalized += LEET_SUBSTITUTIONS[char] ?? char;
+    }
+    return normalized;
+}
+export function createChatFilter(config) {
+    const mode = config.mode ?? "mask";
+    const mask = config.mask ?? "*";
+    const blockedByNormalized = new Map();
+    for (const word of config.blockedWords) {
+        blockedByNormalized.set(normalizeChatText(word), word);
+    }
+    return {
+        apply(body) {
+            if (blockedByNormalized.size === 0)
+                return { ok: true, body, matched: [] };
+            const hit = new Set();
+            let masked = "";
+            let cursor = 0;
+            for (const token of body.matchAll(TOKEN_PATTERN)) {
+                const word = token[0];
+                const start = token.index;
+                const blockedWord = blockedByNormalized.get(normalizeChatText(word));
+                if (blockedWord === undefined)
+                    continue;
+                hit.add(blockedWord);
+                if (mode === "reject")
+                    continue;
+                masked += body.slice(cursor, start) + mask.repeat(word.length);
+                cursor = start + word.length;
+            }
+            if (hit.size === 0)
+                return { ok: true, body, matched: [] };
+            const matched = [...new Set(config.blockedWords)].filter((word) => hit.has(word));
+            if (mode === "reject")
+                return { ok: false, body, matched };
+            masked += body.slice(cursor);
+            return { ok: true, body: masked, matched };
+        },
+    };
+}

package/dist/game/controlGate.d.ts

@@ -0,0 +1,4 @@
+import type { GameContext } from "../runtime/gameContext.js";
+export declare const PLAY_CONTROLS_STORE_KEY = "jg.playControls";
+export declare function setPlayControlsActive(ctx: GameContext, active: boolean): void;
+export declare function playControlsActive(ctx: GameContext): boolean;

package/dist/game/controlGate.js

@@ -0,0 +1,7 @@
+export const PLAY_CONTROLS_STORE_KEY = "jg.playControls";
+export function setPlayControlsActive(ctx, active) {
+    ctx.game.store.set(PLAY_CONTROLS_STORE_KEY, active);
+}
+export function playControlsActive(ctx) {
+    return ctx.game.store.get(PLAY_CONTROLS_STORE_KEY) !== false;
+}

package/dist/game/defineGame.d.ts

@@ -10,6 +10,8 @@ import type { WorldFeature } from "../world/features.js";
 export interface PhysicsConfig {
     gravity?: number;
     jumpVelocity?: number;
+    /** Opt placed scene objects into projectile raycasts as blocking cover AABBs. Default false — enabling changes where shots land. */
+    projectileObstacles?: boolean;
 }
 export interface InventoryDeclaration {
     slots: number;

package/dist/game/events.d.ts

@@ -109,6 +109,10 @@ export interface CombatTelegraphEvent {
     windupMs: number;
     kind: string;
 }
+export interface CombatTelegraphCancelledEvent {
+    /** The `combat.telegraph` event id whose decal should disappear early. */
+    id: number;
+}
 export interface CombatHitReactionEvent {
     instanceId?: string;
     position: [number, number, number];
@@ -156,10 +160,15 @@ export interface FormChangedEvent {
     instanceId: string;
     formId: string | null;
 }
+export interface AudioPlayEvent {
+    sound: string;
+    at?: readonly [number, number, number];
+}
 export interface GameEventMap {
     "entity.died": EntityDiedEvent;
     "entity.floatText": EntityFloatTextEvent;
     "combat.telegraph": CombatTelegraphEvent;
+    "combat.telegraphCancelled": CombatTelegraphCancelledEvent;
     "combat.hitReaction": CombatHitReactionEvent;
     "loot.granted": LootGrantedEvent;
     "inventory.added": InventoryAddedEvent;
@@ -180,6 +189,7 @@ export interface GameEventMap {
     "emote.played": EmotePlayedEvent;
     "possession.swapped": PossessionSwappedEvent;
     "form.changed": FormChangedEvent;
+    "audio.play": AudioPlayEvent;
 }
 export type GameEventHandler<TPayload> = (payload: TPayload) => void;
 export interface GameEvents<TMap extends GameEventMap = GameEventMap> {

package/dist/game/gamePhase.d.ts

@@ -0,0 +1,20 @@
+import type { GameContext } from "../runtime/gameContext.js";
+/**
+ * Canonical run phase every game moves through. `menu` (title/main menu),
+ * `playing` (live), `paused` (mid-run pause), `ended` (win/lose/results).
+ * Touch controls are shown only while `playing`; menus and results never paint
+ * the touch dock over themselves.
+ */
+export type GamePhase = "menu" | "playing" | "paused" | "ended";
+export declare const GAME_PHASE_STORE_KEY = "jg.phase";
+/**
+ * Set the current phase. Publishes it to `ctx.game.store` (React reads it via
+ * `useGamePhase`) and gates the shell's on-screen touch controls in one call —
+ * `playing` shows them, every other phase hides them. This is the whole
+ * "main menu shouldn't show touch controls" wiring: call it once per phase
+ * transition and the dock follows.
+ */
+export declare function setGamePhase(ctx: GameContext, phase: GamePhase): void;
+/** Current phase; defaults to `playing` when unset so always-live games need no wiring. */
+export declare function gamePhase(ctx: GameContext): GamePhase;
+export declare function isPlaying(ctx: GameContext): boolean;

package/dist/game/gamePhase.js

@@ -0,0 +1,21 @@
+import { setPlayControlsActive } from "./controlGate.js";
+export const GAME_PHASE_STORE_KEY = "jg.phase";
+/**
+ * Set the current phase. Publishes it to `ctx.game.store` (React reads it via
+ * `useGamePhase`) and gates the shell's on-screen touch controls in one call —
+ * `playing` shows them, every other phase hides them. This is the whole
+ * "main menu shouldn't show touch controls" wiring: call it once per phase
+ * transition and the dock follows.
+ */
+export function setGamePhase(ctx, phase) {
+    ctx.game.store.set(GAME_PHASE_STORE_KEY, phase);
+    setPlayControlsActive(ctx, phase === "playing");
+}
+/** Current phase; defaults to `playing` when unset so always-live games need no wiring. */
+export function gamePhase(ctx) {
+    const value = ctx.game.store.get(GAME_PHASE_STORE_KEY);
+    return value === "menu" || value === "paused" || value === "ended" ? value : "playing";
+}
+export function isPlaying(ctx) {
+    return gamePhase(ctx) === "playing";
+}

package/dist/game/lootTable.d.ts

@@ -2,11 +2,20 @@ export interface LootEntry {
     item?: string;
     currency?: string;
     count: number | [number, number];
-    weight: number;
+    /** Relative pick weight — required in `"weighted"` mode, forbidden in `"independent"` mode. */
+    weight?: number;
+    /** Per-entry drop probability in `(0, 1]` — required in `"independent"` mode, forbidden in `"weighted"` mode. */
+    chance?: number;
 }
 export interface LootTableDef {
     id: string;
     rolls?: number;
+    /**
+     * `"weighted"` (default): each roll picks exactly one entry by relative `weight`.
+     * `"independent"`: each roll gives every entry its own `chance` — classic drop lists
+     * where a kill can yield several items (or nothing) without filler entries.
+     */
+    mode?: "weighted" | "independent";
     entries: LootEntry[];
 }
 export interface Drop {

package/dist/game/lootTable.js

@@ -1,11 +1,23 @@
-function assertValidEntry(entry) {
+function assertValidEntry(entry, mode) {
     const hasItem = entry.item !== undefined;
     const hasCurrency = entry.currency !== undefined;
     if (hasItem === hasCurrency) {
         throw new Error("loot entry must have exactly one of item or currency");
     }
-    if (!(entry.weight > 0)) {
-        throw new Error(`loot entry weight must be positive, got ${entry.weight}`);
+    if (mode === "weighted") {
+        if (entry.chance !== undefined) {
+            throw new Error("loot entry chance is only valid in independent mode");
+        }
+        if (entry.weight === undefined || !(entry.weight > 0)) {
+            throw new Error(`loot entry weight must be positive, got ${entry.weight}`);
+        }
+        return;
+    }
+    if (entry.weight !== undefined) {
+        throw new Error("loot entry weight is only valid in weighted mode");
+    }
+    if (entry.chance === undefined || !(entry.chance > 0) || entry.chance > 1) {
+        throw new Error(`loot entry chance must be in (0, 1], got ${entry.chance}`);
     }
 }
 function assertValidDef(def) {
@@ -13,7 +25,7 @@ function assertValidDef(def) {
         throw new Error(`loot table "${def.id}" must have at least one entry`);
     }
     for (const entry of def.entries)
-        assertValidEntry(entry);
+        assertValidEntry(entry, def.mode ?? "weighted");
 }
 function resolveCount(count, rng) {
     if (typeof count === "number")
@@ -22,10 +34,10 @@ function resolveCount(count, rng) {
     return min + Math.floor(rng() * (max - min + 1));
 }
 function pickEntry(entries, rng) {
-    const total = entries.reduce((sum, entry) => sum + entry.weight, 0);
+    const total = entries.reduce((sum, entry) => sum + (entry.weight ?? 0), 0);
     let roll = rng() * total;
     for (const entry of entries) {
-        roll -= entry.weight;
+        roll -= entry.weight ?? 0;
         if (roll < 0)
             return entry;
     }
@@ -56,7 +68,15 @@ export function createLootRegistry() {
             const rolls = table.rolls ?? 1;
             const drops = [];
             for (let i = 0; i < rolls; i++) {
-                drops.push(rollEntry(pickEntry(table.entries, rng), rng));
+                if (table.mode === "independent") {
+                    for (const entry of table.entries) {
+                        if (rng() < (entry.chance ?? 0))
+                            drops.push(rollEntry(entry, rng));
+                    }
+                }
+                else {
+                    drops.push(rollEntry(pickEntry(table.entries, rng), rng));
+                }
             }
             return drops;
         },

package/dist/game/playableGame.d.ts

@@ -1,9 +1,12 @@
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
 import type { TouchControlsConfig } from "../input/touchScheme.js";
+import type { GameSettingsConfig } from "../settings/settingsModel.js";
+import type { HudPlatform, HudViewportConfig } from "../ui/hudScale.js";
 import type { PositionedPrompt } from "../interaction/proximityPrompt.js";
 import type { CatalogEntityRole, GameContext, GameContextContent } from "../runtime/gameContext.js";
 import type { ModelDims } from "../scene/assetCatalog.js";
 import type { SkyEnvironmentConfig } from "../world/features.js";
+import type { VisibilityConfig } from "../visibility/config.js";
 import type { GameDefinition, GameLoop } from "./defineGame.js";
 import type { LootFilterRule } from "./lootFilter.js";
 import type { RarityStyle } from "./worldItem.js";
@@ -75,6 +78,8 @@ export interface FirstPersonCameraConfig {
  * - `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". */
@@ -202,6 +207,17 @@ export interface ChaseCameraConfig {
     };
     /** 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;
+    };
     /** Which view to mount. Default "chase". */
     view?: ChaseView;
     /** Local offset for cockpit/hood/rear seats (relative to the vehicle, +z forward). */
@@ -354,16 +370,35 @@ 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;
+}
 export interface GameCameraConfig {
     /** Selects the rig. Overrides `perspective`; leave unset to fall back to `perspective`. */
     rig?: CameraRigKind;
-    /** 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. */
+    /** 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;
     /** "third" mounts the orbit camera (default); "first" mounts pointer-lock mouse-look. Shorthand for `rig: "orbit" | "first"`. */
     perspective?: "third" | "first";
     /** First-person tuning; only read when the rig resolves to "first". */
@@ -542,6 +577,8 @@ export interface PlayerMovementConfig {
     collideObjects?: boolean;
     /** Intercepts each frame's resolved position before the pose commits (and before onTick): return a replacement [x,y,z] to constrain or redirect the step, or nothing to accept it. */
     beforeCommit?: (frame: MovementCommitFrame) => readonly [number, number, number] | undefined | void;
+    /** Gates the built-in sprint (`runSpeedMultiplier`) behind live game state — a stamina stat, an encumbrance check (#282.3). Called each frame while sprint is held; `false` walks. */
+    canSprint?: (ctx: GameContext) => boolean;
 }
 /** One frame's movement resolution handed to `PlayerMovementConfig.beforeCommit`. */
 export interface MovementCommitFrame {
@@ -549,6 +586,8 @@ export interface MovementCommitFrame {
     current: readonly [number, number, number];
     next: readonly [number, number, number];
     dt: number;
+    /** The live game context (#282.2) — movement rules read stores/stats directly instead of module-level bridge objects. */
+    ctx: GameContext;
 }
 export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEntity = never, TRenderObject = never> {
     game: GameDefinition;
@@ -585,6 +624,12 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     pointer?: PointerConfig;
     /** Touch controls on coarse-pointer devices. Unset derives a scheme from `input` (virtual joystick for movement actions, on-screen buttons for the rest); a config refines it with gestures and curated buttons; `false` opts out. */
     touch?: TouchControlsConfig | false;
+    /** Preferred phone orientation. When a coarse-pointer device is held the other way the shell shows a dismissible rotate hint; purely advisory, never blocks play. */
+    orientation?: "landscape" | "portrait";
+    /** Where the game is meant to be played. Default `["web", "mobile"]` — design-resolution HUD fit is on for every game: `HudCanvas` auto-scales from `hudFit.designSize` down to the live viewport, so the desktop layout shrinks to fit a phone instead of overflowing it. Declare `["web"]` to opt a desktop-only game out (compact displays fall back to the legacy fixed 0.85 zoom). */
+    platforms?: readonly HudPlatform[];
+    /** HUD design resolution + scale clamps (default 1600×900, scale 0.4–1). `mobile` overrides tune the phone fit separately — the same resolution system drives desktop UI-scale and phone shrink. */
+    hudFit?: HudViewportConfig;
     /** Opt in to world-space health bars floating over non-local entities that carry the stat. `roles` restricts bars to entities whose catalog entry declares one of the given roles. */
     worldHealthBars?: boolean | {
         statId?: string;
@@ -611,5 +656,9 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     backdrop?: BackdropConfig;
     /** F2 debug overlay (frame/sim timing, logs, backend latency, keybinds, live tunables). On for every game by default; `false` disables the toggle. */
     devtools?: boolean;
+    /** Player settings menu. Auto-mounted for every game (Sound / Graphics / Gameplay / Controls); unset uses the defaults, `false` opts out. Add game-specific rows via `extra`, switch overlay/full-page via `mode`, or swap the gear for compact on-screen buttons via `surface: "quick"`. */
+    settings?: GameSettingsConfig | false;
+    /** Automatic camera frustum + distance culling and asset streaming. On by default with conservative margins; unset uses engine defaults, `{ enabled: false }` opts out. Override bounds/distance/pins per entity kind or object catalog id. */
+    visibility?: VisibilityConfig;
 }
 export declare function worldHealthBarAllowsRole(roles: readonly CatalogEntityRole[] | undefined, role: CatalogEntityRole | undefined): boolean;

package/dist/game/playableGame.js

@@ -1,4 +1,4 @@
-export const CAMERA_FRUSTUM_DEFAULTS = { fov: 55, near: 0.1, far: 300 };
+export const CAMERA_FRUSTUM_DEFAULTS = { fov: 55, near: 0.1, far: 300, zoom: 50 };
 export function worldHealthBarAllowsRole(roles, role) {
     if (roles === undefined)
         return true;

package/dist/game/quest.d.ts

@@ -65,7 +65,7 @@ export interface QuestJournalDeps {
     partyMembersNear?(userId: string, radius: number): string[];
 }
 export interface QuestJournal {
-    register(catalog: QuestDef[] | Record<string, QuestDef>): void;
+    register(catalog: readonly QuestDef[] | Record<string, QuestDef>): void;
     has(questId: string): boolean;
     canAccept(userId: string, questId: string): {
         reason: string;
@@ -126,7 +126,11 @@ export interface QuestEvaluator {
 export declare function applyQuestRewards(rewards: QuestRewards, appliers: {
     grantXp?(amount: number): void;
     grantEconomy?(currencyId: string, amount: number): void;
-    grantItem?(inventoryId: string, itemId: string, count: number): void;
+    grantItem?(inventoryId: string, itemId: string, count: number): {
+        reason: string;
+    } | null | void;
     grantUnlock?(unlockId: string): void;
-}): void;
+}): {
+    reason: string;
+} | null;
 export declare function createQuestEvaluator(defs: QuestDef[] | Record<string, QuestDef>): QuestEvaluator;