@jgengine/core 0.8.0 → 0.10.0

package/dist/game/levelSequence.js

@@ -1,3 +1,4 @@
+import { createKeyValueStore } from "./keyValueStore.js";
 /**
  * A pure, deterministic level campaign: an ordered list of levels, each with its own opaque config, played
  * through a `start` → (`clear` → `advance`)* → `complete` happy path, with `fail`/`retry` handling per-level
@@ -7,10 +8,32 @@
 export function createLevelSequence(config) {
     const levels = config.levels;
     const maxAttempts = 1 + Math.max(0, Math.floor(config.retriesPerLevel ?? 0));
+    const store = config.key === undefined
+        ? null
+        : createKeyValueStore({
+            key: config.key,
+            initial: {},
+            storage: config.storage,
+        });
     let index = 0;
     let attempt = 1;
     let status = "idle";
     const clearedIds = [];
+    const levelRecords = store === null ? {} : { ...store.get() };
+    function persistRecords() {
+        store?.set({ ...levelRecords });
+    }
+    function indexOfLevel(id) {
+        return levels.findIndex((level) => level.id === id);
+    }
+    function isUnlocked(id) {
+        const idx = indexOfLevel(id);
+        if (idx < 0)
+            return false;
+        if (idx === 0)
+            return true;
+        return levelRecords[levels[idx - 1].id]?.cleared === true;
+    }
     function current() {
         if (status === "idle" || status === "complete")
             return null;
@@ -30,12 +53,38 @@ export function createLevelSequence(config) {
             clearedIds.length = 0;
             status = "playing";
         },
-        clear() {
+        clear(stars) {
             if (status !== "playing" || current() === null)
                 return;
-            clearedIds.push(levels[index].id);
+            const id = levels[index].id;
+            clearedIds.push(id);
+            const previousStars = levelRecords[id]?.stars ?? 0;
+            const bestStars = Math.max(previousStars, stars ?? 0);
+            levelRecords[id] = { cleared: true, stars: bestStars };
+            persistRecords();
             status = "cleared";
         },
+        select(level) {
+            const idx = indexOfLevel(level);
+            if (idx < 0 || !isUnlocked(level))
+                return false;
+            index = idx;
+            attempt = 1;
+            status = "playing";
+            return true;
+        },
+        isUnlocked,
+        record: (level) => levelRecords[level] ?? null,
+        records: () => ({ ...levelRecords }),
+        clearRecords() {
+            for (const id of Object.keys(levelRecords))
+                delete levelRecords[id];
+            store?.clear();
+            index = 0;
+            attempt = 1;
+            clearedIds.length = 0;
+            status = "idle";
+        },
         fail() {
             if (status !== "playing" || current() === null)
                 return "failed";

package/dist/game/lootTable.d.ts

@@ -1,14 +1,26 @@
+/** One possible drop in a {@link LootTableDef} — an item or currency, its count range, and its odds. */
 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;
 }
+/** A named, validated loot table — its roll count, weighted-vs-independent mode, and candidate entries. */
 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[];
 }
+/** A resolved loot outcome — one item or currency grant with its rolled count. */
 export interface Drop {
     item?: string;
     currency?: string;
@@ -20,6 +32,7 @@ export interface LootRegistry {
     roll(id: string, rng?: () => number): Drop[];
 }
 export declare function createLootRegistry(): LootRegistry;
+/** Validates a loot table definition and returns it unchanged, for use with {@link createLootRegistry}. */
 export declare function lootTable(def: LootTableDef): LootTableDef;
 export declare function grantDrops(drops: Drop[], appliers: {
     putItem: (itemId: string, count: number) => unknown;

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,12 +68,21 @@ 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;
         },
     };
 }
+/** Validates a loot table definition and returns it unchanged, for use with {@link createLootRegistry}. */
 export function lootTable(def) {
     assertValidDef(def);
     return def;

package/dist/game/modelAnimation.d.ts

@@ -0,0 +1,8 @@
+/** The two one-shot events the shell fires automatically for an entity, from `combat.hitReaction` and `entity.died`. */
+export declare const AUTO_ONE_SHOT_EVENTS: readonly ["hit", "death"];
+/**
+ * Resolves the clip name a one-shot `event` should play from a model's `animation.oneShots` map, or `null`
+ * if the event isn't bound. A `string[]` binding picks a variant by `roll` (a value in `[0, 1)`), so combat
+ * can vary attack swings. Pure and deterministic given `roll` — the shell supplies the randomness.
+ */
+export declare function resolveOneShotClip(oneShots: Record<string, string | readonly string[]> | undefined, event: string, roll: number): string | null;

package/dist/game/modelAnimation.js

@@ -0,0 +1,18 @@
+/** The two one-shot events the shell fires automatically for an entity, from `combat.hitReaction` and `entity.died`. */
+export const AUTO_ONE_SHOT_EVENTS = ["hit", "death"];
+/**
+ * Resolves the clip name a one-shot `event` should play from a model's `animation.oneShots` map, or `null`
+ * if the event isn't bound. A `string[]` binding picks a variant by `roll` (a value in `[0, 1)`), so combat
+ * can vary attack swings. Pure and deterministic given `roll` — the shell supplies the randomness.
+ */
+export function resolveOneShotClip(oneShots, event, roll) {
+    const spec = oneShots?.[event];
+    if (spec === undefined)
+        return null;
+    if (typeof spec === "string")
+        return spec;
+    if (spec.length === 0)
+        return null;
+    const index = Math.min(spec.length - 1, Math.max(0, Math.floor(roll * spec.length)));
+    return spec[index] ?? null;
+}

package/dist/game/playableGame.d.ts

@@ -1,9 +1,15 @@
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
+import type { MusicTheme } from "../audio/music.js";
+import type { PostProcessingConfig } from "../render/postProcessing.js";
 import type { TouchControlsConfig } from "../input/touchScheme.js";
+import type { GameSettingsConfig } from "../settings/settingsModel.js";
+import type { GameOrientation } from "../ui/orientation.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 +81,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 +210,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 +373,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". */
@@ -420,6 +458,12 @@ export interface GameCameraConfig {
     /** 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;
+    /** 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;
+    };
 }
 export interface EntitySpriteConfig {
     url: string;
@@ -457,6 +501,21 @@ export interface VoxelCollisionConfig {
     /** Tallest ledge walked up without jumping. Default 0.6. */
     stepHeight?: number;
 }
+/** Movement-state clip set for `ModelAnimationConfig.states`: the shell reads the entity's live speed each frame and crossfades between these clips, so a walking mob animates without any game-side driver. */
+export interface ModelAnimationStates {
+    /** Clip name while the entity is stationary. */
+    idle: string;
+    /** Clip name while the entity is moving. */
+    walk: string;
+    /** Clip name above `runSpeed`; omit to keep `walk` at any speed. */
+    run?: string;
+    /** Speed (world units/sec) above which the entity counts as moving. Default 0.5. */
+    walkSpeed?: number;
+    /** Speed above which `run` plays when provided. Default 6. */
+    runSpeed?: number;
+    /** Crossfade duration in seconds when the state changes. Default 0.2. */
+    fadeSec?: number;
+}
 /** Rig playback for a `ModelConfig`'s GLTF animation clips — looping idles, one-shots, and held poses. */
 export interface ModelAnimationConfig {
     /** Clip name to play; defaults to the GLB's first clip. */
@@ -469,6 +528,15 @@ export interface ModelAnimationConfig {
     paused?: boolean;
     /** Seek the clip to this time in seconds; combine with `paused: true` to hold a specific pose ("pose library" usage). */
     time?: number;
+    /** Speed-driven idle/walk/run clip switching, crossfaded by the shell from the entity's live movement; overrides `clip` while set. */
+    states?: ModelAnimationStates;
+    /**
+     * One-shot clips keyed by event name, each played once over the locomotion state then released back to it.
+     * Reserved keys `hit` and `death` auto-fire on this entity's `combat.hitReaction` / `entity.died`; any other
+     * key fires when the game emits `entity.animation` (`ctx.game.playEntityAnimation(instanceId, event)`). A
+     * `string[]` picks a random variant per trigger. `death` clamps on its final frame instead of returning.
+     */
+    oneShots?: Record<string, string | readonly string[]>;
 }
 /** Per-entity PBR material override (#151.3) applied to every `MeshStandardMaterial` in the model's cloned scene graph. */
 export interface ModelMaterialOverride {
@@ -478,9 +546,24 @@ export interface ModelMaterialOverride {
     emissive?: string;
     emissiveIntensity?: number;
 }
+/** Parents a prop/weapon model to a named bone or node on the host model's rig — a sword on `handslot.r`, a spellbook offhand — following the bone's animated transform each frame. */
+export interface ModelAttachment {
+    /** Bone or node name in the rig to parent to (e.g. `"handslot.r"`). */
+    slot: string;
+    /** The attached model — a catalog asset id or an inline `ModelConfig`. */
+    model: string | ModelConfig;
+    /** Local position offset at the bone, in the attached model's own space. */
+    position?: [number, number, number];
+    /** Local Euler rotation (radians) applied at the bone. */
+    rotation?: [number, number, number];
+    /** Uniform scale of the attached model at the bone. Default 1. */
+    scale?: number;
+}
 export interface ModelConfig {
     url: string;
     scale?: number;
+    /** Normalize the rendered model to this world-unit height: the shell measures the loaded scene's bounding box, scales it so its height matches, and grounds its lowest point at the placement Y. Composes with `scale` as a multiplier. */
+    targetHeight?: number;
     y?: number;
     /** How the model registers on its placement point. `"center"` (default) horizontally centers the measured footprint on the point and ground-snaps its lowest vertex to the point's Y — the correct behavior for corner-pivot modular kits. `"origin"` renders at the raw GLB origin (legacy). */
     anchor?: "center" | "origin";
@@ -490,6 +573,8 @@ export interface ModelConfig {
     material?: ModelMaterialOverride;
     /** Plays a GLTF animation clip on the model when the source has any (skinned or not); omit to render the rig's bind pose. */
     animation?: ModelAnimationConfig;
+    /** Props/weapons parented to named bones on this model's rig; each follows its bone through animation. */
+    attachments?: readonly ModelAttachment[];
 }
 export interface ObjectStyle {
     color?: string;
@@ -505,6 +590,14 @@ export interface DirectionalLightingConfig {
     intensity?: number;
     position: readonly [number, number, number];
     castShadow?: boolean;
+    /** Shadow map resolution in px (square) when `castShadow`. Higher = crisper, costlier. Default 1024. */
+    shadowMapSize?: number;
+    /** Half-extent of the orthographic shadow camera in world units — sized to the shadowed area. Default 40. */
+    shadowCameraSize?: number;
+    /** Shadow depth bias to fight acne. Default -0.0004. */
+    shadowBias?: number;
+    /** Shadow normal bias to fight peter-panning. Default 0.02. */
+    shadowNormalBias?: number;
 }
 export interface HemisphereLightingConfig {
     skyColor?: string;
@@ -542,6 +635,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,11 +644,13 @@ 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;
     content: GameContextContent;
-    loop: Required<GameLoop<GameContext>>;
+    loop: Required<Omit<GameLoop<GameContext>, "onPlayerLeave">> & Pick<GameLoop<GameContext>, "onPlayerLeave">;
     GameUI: TUi;
     /** Which shell mount to use. Default `"3d"` (canvas, camera rig, pointer, world rendering). `"hud"` mounts no 3D canvas, camera rig, or pointer — the game is `GameUI` plus the command/input loop, for board/card/menu games. */
     presentation?: "3d" | "hud";
@@ -585,15 +682,24 @@ 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;
-    /** 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. */
+    /** Phone orientation contract. Legacy `"landscape"`/`"portrait"` stays advisory (a dismissible rotate hint). The object form `{ mobile: "landscape-required" }` is strict — the shell shows an engine-owned rotate screen and blocks gameplay until the device is turned. See `GameOrientation`. */
+    orientation?: GameOrientation;
+    /** 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; `maxDistance` hides bars beyond this many world units from the player (default 60). */
     worldHealthBars?: boolean | {
         statId?: string;
         roles?: readonly CatalogEntityRole[];
+        maxDistance?: number;
     };
-    /** Sound catalog + mix buses (music/sfx/ambient/…) the shell's Web Audio glue plays from. Catalog-first — no per-game audio wiring. */
+    /** Sound catalog + mix buses (music/sfx/ambient/…) the shell's Web Audio glue plays from. Catalog-first — no per-game audio wiring. `sounds` may be sample (`url`) or procedural (`synth`); `music` holds procedural themes crossfaded via `ctx.game.audio.music(id)`. */
     audio?: {
         sounds: Record<string, SoundDef>;
         buses?: Record<string, AudioBusDef>;
+        music?: Record<string, MusicTheme>;
+        musicBus?: string;
     };
     /** Continuous positional emitter keyed by entity kind name: while a matching entity exists, the shell plays and repositions the mapped `audio.sounds` id (looping engine hum, campfire crackle, footstep loop) with listener-distance falloff. */
     entitySounds?: Record<string, string>;
@@ -609,7 +715,13 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     lighting?: LightingConfig;
     /** Generic background/sky/fog (#207.6), applied for any world kind including a custom `environment` component. */
     backdrop?: BackdropConfig;
+    /** Declarative post-processing chain (AO/bloom/tone-map/grade). When set, the shell mounts an EffectComposer and owns the render; absent leaves the renderer drawing directly (unchanged). */
+    postProcessing?: PostProcessingConfig;
     /** 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;

package/dist/game/quest.js

@@ -72,17 +72,20 @@ export function createQuestJournal(deps) {
         return null;
     }
     function applyRewards(userId, rewards) {
+        for (const entry of rewards.items ?? []) {
+            const fail = deps.rewards.grantItem(userId, entry.inventory, entry.item, entry.count);
+            if (fail !== null)
+                return fail;
+        }
         if (rewards.xp)
             deps.rewards.grantXp(userId, rewards.xp.amount);
         for (const [currencyId, amount] of Object.entries(rewards.economy ?? {})) {
             deps.rewards.grantEconomy(userId, currencyId, amount);
         }
-        for (const entry of rewards.items ?? []) {
-            deps.rewards.grantItem(userId, entry.inventory, entry.item, entry.count);
-        }
         for (const unlockId of rewards.unlocks ?? []) {
             deps.rewards.grantUnlock(userId, unlockId);
         }
+        return null;
     }
     function turnIn(userId, questId) {
         const denied = canTurnIn(userId, questId);
@@ -90,9 +93,12 @@ export function createQuestJournal(deps) {
             return denied;
         const def = catalog.get(questId);
         const state = users.get(userId).get(questId);
+        if (def.rewards) {
+            const fail = applyRewards(userId, def.rewards);
+            if (fail !== null)
+                return fail;
+        }
         state.status = "completed";
-        if (def.rewards)
-            applyRewards(userId, def.rewards);
         deps.events.emit("quest.completed", { userId, questId });
         for (const nextQuestId of def.rewards?.quests ?? []) {
             if (canAccept(userId, nextQuestId) === null)
@@ -227,17 +233,20 @@ export function createQuestJournal(deps) {
     };
 }
 export function applyQuestRewards(rewards, appliers) {
+    for (const entry of rewards.items ?? []) {
+        const fail = appliers.grantItem?.(entry.inventory, entry.item, entry.count);
+        if (fail != null && typeof fail === "object" && "reason" in fail)
+            return fail;
+    }
     if (rewards.xp)
         appliers.grantXp?.(rewards.xp.amount);
     for (const [currencyId, amount] of Object.entries(rewards.economy ?? {})) {
         appliers.grantEconomy?.(currencyId, amount);
     }
-    for (const entry of rewards.items ?? []) {
-        appliers.grantItem?.(entry.inventory, entry.item, entry.count);
-    }
     for (const unlockId of rewards.unlocks ?? []) {
         appliers.grantUnlock?.(unlockId);
     }
+    return null;
 }
 function toWorking(state) {
     const working = new Map();

package/dist/game/race.d.ts

@@ -3,18 +3,36 @@ export interface Checkpoint {
     center: readonly [number, number, number];
     half: readonly [number, number, number];
 }
+export interface RaceForkRoute {
+    id: string;
+    checkpoints: readonly Checkpoint[];
+}
+/**
+ * An alternate-route section (#286.3): after passing mainline checkpoint `afterIndex`, a racer commits
+ * to whichever route's first checkpoint they hit, runs its checkpoints in order, and rejoins at
+ * mainline `afterIndex + 1`. Every completed route contributes exactly one checkpoint of `progress`
+ * regardless of length, and each hit records a split — so route time accounting comes for free.
+ */
+export interface RaceFork {
+    id: string;
+    /** Mainline checkpoint index the fork opens after; must be before the finish line. */
+    afterIndex: number;
+    routes: readonly RaceForkRoute[];
+}
 export interface RaceTrackConfig {
     checkpoints: readonly Checkpoint[];
     laps?: number;
+    forks?: readonly RaceFork[];
 }
 export interface RaceTrack {
     readonly checkpoints: readonly Checkpoint[];
     readonly laps: number;
+    readonly forks: readonly RaceFork[];
 }
 /**
  * A race track is an ordered ring of checkpoint trigger volumes plus a lap count. The final checkpoint
  * is the lap/finish line: a racer completes a lap by passing all checkpoints in order and hitting the
- * last one.
+ * last one. `forks` splice alternate route segments between mainline checkpoints.
  */
 export declare function raceTrack(config: RaceTrackConfig): RaceTrack;
 export interface RacerProgress {
@@ -28,6 +46,13 @@ export interface RacerProgress {
     finishTime: number | null;
     eliminated: boolean;
     splits: readonly number[];
+    /** Fork id → route id last taken through it. */
+    routesTaken: Readonly<Record<string, string>>;
+    /** Route the racer is currently inside, or `null` on the mainline. */
+    activeRoute: {
+        forkId: string;
+        routeId: string;
+    } | null;
 }
 export type RaceEvent = {
     type: "checkpoint.hit";
@@ -35,6 +60,18 @@ export type RaceEvent = {
     checkpoint: number;
     lap: number;
     time: number;
+    /** Set when the hit is a fork-route checkpoint (`checkpoint` is then the fork's `afterIndex`). */
+    fork?: {
+        forkId: string;
+        routeId: string;
+        index: number;
+    };
+} | {
+    type: "fork.taken";
+    racerId: string;
+    forkId: string;
+    routeId: string;
+    time: number;
 } | {
     type: "lap.completed";
     racerId: string;
@@ -90,6 +127,7 @@ export declare class RaceState {
     progressOf(racerId: string): RacerProgress | null;
     private snapshot;
     standings(): readonly RacerProgress[];
+    private expectedCheckpoint;
     resetToCheckpoint(racerId: string): {
         position: [number, number, number];
         heading: number;