@jgengine/core 0.9.0 → 0.10.0

package/dist/game/connectedPlayers.d.ts

@@ -0,0 +1,28 @@
+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`. */
+export interface ConnectedPlayer {
+    userId: string;
+    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;
+}
+/**
+ * The set of players connected to one hosted world. A single-player game uses `ctx.player`; a shared-world loop
+ * reads `ctx.game.players` so `onTick` can advance every connected hero, not just the one local player. The host
+ * (`HostedGameRunner`) drives `join`/`leave`/`setInput`; game code reads `list`/`ids`/`has`/`count`/`input`.
+ */
+export interface ConnectedPlayers {
+    join(userId: string, isNew: boolean): void;
+    leave(userId: string): boolean;
+    has(userId: string): boolean;
+    get(userId: string): ConnectedPlayer | null;
+    list(): readonly ConnectedPlayer[];
+    ids(): readonly string[];
+    count(): number;
+    /** Record a player's latest input frame (host-driven); a no-op for a player that hasn't joined. */
+    setInput(userId: string, frame: InputFrame): void;
+    /** This player's latest input frame, or `null` if they haven't joined or no frame has arrived yet. */
+    input(userId: string): InputFrame | null;
+}
+/** Build an empty {@link ConnectedPlayers} registry — the host joins/leaves players; the game loop reads them. */
+export declare function createConnectedPlayers(): ConnectedPlayers;

package/dist/game/connectedPlayers.js

@@ -0,0 +1,21 @@
+/** Build an empty {@link ConnectedPlayers} registry — the host joins/leaves players; the game loop reads them. */
+export function createConnectedPlayers() {
+    const players = new Map();
+    return {
+        join(userId, isNew) {
+            players.set(userId, { userId, isNew, input: null });
+        },
+        leave: (userId) => players.delete(userId),
+        has: (userId) => players.has(userId),
+        get: (userId) => players.get(userId) ?? null,
+        list: () => Array.from(players.values()),
+        ids: () => Array.from(players.keys()),
+        count: () => players.size,
+        setInput(userId, frame) {
+            const player = players.get(userId);
+            if (player !== undefined)
+                player.input = frame;
+        },
+        input: (userId) => players.get(userId)?.input ?? null,
+    };
+}

package/dist/game/defineGame.d.ts

@@ -7,12 +7,14 @@ import { type AssetCatalog, type ModelAssetRef } from "../scene/assetCatalog.js"
 import { type EntityStore } from "../scene/entityStore.js";
 import type { TimeConfig } from "../time/simClock.js";
 import type { WorldFeature } from "../world/features.js";
+/** World gravity and jump tuning, plus scene-object collision opt-ins, for the game's physics step. */
 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;
 }
+/** Shape of one named inventory a game declares — slot count, accepted item types, HUD binding. */
 export interface InventoryDeclaration {
     slots: number;
     hud?: string;
@@ -21,20 +23,57 @@ export interface InventoryDeclaration {
     applyModifiers?: boolean;
     tier?: StorageTier;
 }
+/** Hosting mode for a game's multiplayer server: `"persistent"`, or a custom mode with its own options. */
 export type GameServerConfig = "persistent" | {
     mode: string;
     [key: string]: unknown;
 };
+/** Identity of a player joining or leaving a hosted world — passed to the multiplayer loop hooks. */
+export interface LoopPlayer {
+    userId: string;
+    isNew: boolean;
+}
+/** Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave. */
 export interface GameLoop<TContext = unknown> {
     onInit?(ctx: TContext): void;
-    onNewPlayer?(ctx: TContext): void;
+    /** Once per join. `player` identifies the joiner in a hosted world; single-player callers may omit it. */
+    onNewPlayer?(ctx: TContext, player?: LoopPlayer): void;
     onTick?(ctx: TContext, dt: number): void;
+    /** Once per leave in a hosted world (never fired single-player). Despawn the player's entities / release their slots here. */
+    onPlayerLeave?(ctx: TContext, player: LoopPlayer): void;
+}
+/**
+ * Opt-in `ctx.game.*` subsystems. Absent = off: the game doesn't carry (or expose) it, and `ctx.game.<name>`
+ * is `undefined`. Present (`true`) builds it. The universal base — `commands`, `events`, `store`, `feed` — is
+ * always on and not listed here. This is what keeps core genre-agnostic: a puzzle game isn't handed an MMO's
+ * leaderboard/roster/turn plumbing it never asked for.
+ */
+export interface GameFeatures {
+    /** Owned/captured entity roster (`ctx.game.roster`) — pet/monster collection games. */
+    roster?: boolean;
+    /** Card pile zones (`ctx.game.cards`) — deckbuilders, card games. */
+    cards?: boolean;
+    /** Turn/phase loop (`ctx.game.turn`) — turn-based games. */
+    turn?: boolean;
+    /** Lap/checkpoint race state (`ctx.game.race`) — racers. */
+    race?: boolean;
+    /** Competitive score tracking (`ctx.game.leaderboard`) — ranked/arcade games. */
+    leaderboard?: boolean;
+    /** Friends/party/presence/emotes/world-invites (`ctx.game.social`) — social/MMO games. */
+    social?: boolean;
+    /** Channels + messages (`ctx.game.chat`) — implies `social`; multiplayer/social games. */
+    chat?: boolean;
+    /** Connected-player set (`ctx.game.players`) — shared-world hosts whose loop ticks every player, not just `ctx.player`. */
+    players?: boolean;
 }
+/** Fully-resolved game description produced by {@link defineGame} — assets, scene, and opted-in subsystems. */
 export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> {
     name: string;
     assets: AssetCatalog<TAssetRef>;
     multiplayer: TMultiplayer;
     scene: EntityStore;
+    /** Opt-in `ctx.game.*` subsystems beyond the always-on base; omitted systems are `undefined` on `ctx.game`. */
+    features?: GameFeatures;
     world?: WorldFeature;
     physics?: PhysicsConfig;
     /** Simulation clock: real→game time scale, selectable speeds, calendar. Exposed as `ctx.time`; the shell feeds its scaled dt to `loop.onTick`. */
@@ -48,7 +87,9 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     ui?: unknown;
     loop?: GameLoop<any>;
 }
+/** Input to {@link defineGame} — a `GameDefinition` with `scene` derived and `assets` optional. */
 export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & {
     assets?: AssetCatalog<TAssetRef>;
 };
+/** Task-first entry point for authoring a game: fills in `scene` and default `assets`, validates `name`. */
 export declare function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer>;

package/dist/game/defineGame.js

@@ -1,5 +1,6 @@
 import { createAssetCatalog } from "../scene/assetCatalog.js";
 import { createEntityStore } from "../scene/entityStore.js";
+/** Task-first entry point for authoring a game: fills in `scene` and default `assets`, validates `name`. */
 export function defineGame(config) {
     if (config.name.trim().length === 0) {
         throw new Error("defineGame: name must be non-empty");

package/dist/game/events.d.ts

@@ -22,6 +22,11 @@ export interface EntityDiedEvent {
     position: [number, number, number];
     serverId?: string;
 }
+/** Request that an entity's rig play a one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an "attack" swing); the shell resolves the clip and plays it once over the locomotion state. */
+export interface EntityAnimationEvent {
+    instanceId: string;
+    event: string;
+}
 export interface LootGrantedEvent {
     userId: string;
     drops: {
@@ -164,6 +169,13 @@ export interface AudioPlayEvent {
     sound: string;
     at?: readonly [number, number, number];
 }
+/** Request that the shell's audio engine resume its (browser-gesture-suspended) context; carries no payload. */
+export type AudioResumeEvent = Record<string, never>;
+/** Crossfade the procedural soundtrack to `theme` (null fades out), optionally transposing the incoming theme by `transpose` semitones. */
+export interface AudioMusicEvent {
+    theme: string | null;
+    transpose?: number;
+}
 export interface GameEventMap {
     "entity.died": EntityDiedEvent;
     "entity.floatText": EntityFloatTextEvent;
@@ -190,6 +202,9 @@ export interface GameEventMap {
     "possession.swapped": PossessionSwappedEvent;
     "form.changed": FormChangedEvent;
     "audio.play": AudioPlayEvent;
+    "audio.music": AudioMusicEvent;
+    "audio.resume": AudioResumeEvent;
+    "entity.animation": EntityAnimationEvent;
 }
 export type GameEventHandler<TPayload> = (payload: TPayload) => void;
 export interface GameEvents<TMap extends GameEventMap = GameEventMap> {

package/dist/game/keyValueStore.d.ts

@@ -0,0 +1,25 @@
+/** Structural, DOM-free storage backend: the browser `localStorage` satisfies it, as does a test stub or `null`. The one storage seam core primitives target so persistence code never needs the DOM `Storage` lib. */
+export interface KeyValueStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** The ambient `localStorage` as a {@link KeyValueStorage} when one exists (browser), otherwise `null` (server/tests) — never references the DOM `Storage` type, so it is safe in core. */
+export declare function defaultKeyValueStorage(): KeyValueStorage | null;
+/** A single persisted, mutable cell: read the current value, overwrite it, or read-modify-write with {@link KeyValueStore.update}. Unlike a record book it has no monotonic guard — the value goes wherever you set it. */
+export interface KeyValueStore<T> {
+    get(): T;
+    set(value: T): void;
+    update(mutate: (previous: T) => T): T;
+    clear(): void;
+}
+/** Config for {@link createKeyValueStore}: the storage `key`, the `initial` value used before anything is saved, an optional `storage` backend (defaults to `localStorage`, pass `null` for memory-only), and optional custom `serialize`/`deserialize` (default JSON). */
+export interface KeyValueStoreConfig<T> {
+    readonly key: string;
+    readonly initial: T;
+    readonly storage?: KeyValueStorage | null;
+    readonly serialize?: (value: T) => string;
+    readonly deserialize?: (raw: string) => T;
+}
+/** A lightweight mutable local save cell for single-player state (a credit bank, a settings blob, level progress) — the read-modify-write counterpart to the monotonic `recordBook`. Persists through a {@link KeyValueStorage} (browser `localStorage` by default); corrupt or unavailable storage degrades to in-memory and never throws into a game tick. */
+export declare function createKeyValueStore<T>(config: KeyValueStoreConfig<T>): KeyValueStore<T>;

package/dist/game/keyValueStore.js

@@ -0,0 +1,61 @@
+/** The ambient `localStorage` as a {@link KeyValueStorage} when one exists (browser), otherwise `null` (server/tests) — never references the DOM `Storage` type, so it is safe in core. */
+export function defaultKeyValueStorage() {
+    try {
+        if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+            return globalThis.localStorage ?? null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/** A lightweight mutable local save cell for single-player state (a credit bank, a settings blob, level progress) — the read-modify-write counterpart to the monotonic `recordBook`. Persists through a {@link KeyValueStorage} (browser `localStorage` by default); corrupt or unavailable storage degrades to in-memory and never throws into a game tick. */
+export function createKeyValueStore(config) {
+    const storage = config.storage === undefined ? defaultKeyValueStorage() : config.storage;
+    const serialize = config.serialize ?? ((value) => JSON.stringify(value));
+    const deserialize = config.deserialize ?? ((raw) => JSON.parse(raw));
+    const read = () => {
+        if (storage === null)
+            return config.initial;
+        try {
+            const raw = storage.getItem(config.key);
+            return raw === null ? config.initial : deserialize(raw);
+        }
+        catch {
+            return config.initial;
+        }
+    };
+    let current = read();
+    const write = (value) => {
+        current = value;
+        if (storage === null)
+            return;
+        try {
+            storage.setItem(config.key, serialize(value));
+        }
+        catch {
+            // storage rejected the write; keep the value in memory for this session
+        }
+    };
+    return {
+        get: () => current,
+        set: (value) => write(value),
+        update: (mutate) => {
+            const next = mutate(current);
+            write(next);
+            return next;
+        },
+        clear: () => {
+            current = config.initial;
+            if (storage === null)
+                return;
+            try {
+                storage.removeItem(config.key);
+            }
+            catch {
+                // ignore removal failure; in-memory value already reset
+            }
+        },
+    };
+}

package/dist/game/levelSequence.d.ts

@@ -1,11 +1,23 @@
+import { type KeyValueStorage } from "./keyValueStore.js";
 export interface LevelDescriptor<TLevelConfig> {
     id: string;
     config: TLevelConfig;
 }
+/** A level's star rating, 0 (cleared, no stars) to 3. */
+export type LevelStars = 0 | 1 | 2 | 3;
+/** Persisted per-level outcome: whether it has ever been cleared and the best star rating achieved. */
+export interface LevelRecord {
+    cleared: boolean;
+    stars: LevelStars;
+}
 export interface LevelSequenceConfig<TLevelConfig> {
     levels: readonly LevelDescriptor<TLevelConfig>[];
     /** Extra attempts granted after the first per level. Defaults to 0 (a single attempt, no retries). */
     retriesPerLevel?: number;
+    /** Persistence key for per-level completion/stars. Omit to keep records in-memory only. */
+    key?: string;
+    /** Storage backend for the records (browser `localStorage` by default when `key` is set); pass `null` for memory-only. */
+    storage?: KeyValueStorage | null;
 }
 export type LevelSequenceStatus = "idle" | "playing" | "cleared" | "failed" | "complete";
 export interface CurrentLevel<TLevelConfig> {
@@ -24,15 +36,25 @@ export interface LevelSequence<TLevelConfig> {
     status(): LevelSequenceStatus;
     /** Enters level 0. A no-op on an empty level list, which leaves `status()` at "idle" forever. */
     start(): void;
-    /** Marks the current level cleared; call `advance()` to move to the next one. */
-    clear(): void;
+    /** Marks the current level cleared, recording its best star rating; call `advance()` to move to the next one. */
+    clear(stars?: LevelStars): void;
     /** Consumes an attempt on the current level. Returns "retry" while attempts remain, else "failed". */
     fail(): "retry" | "failed";
     /** Restarts the current level after a "retry"-eligible failure. Returns false if there was nothing to retry. */
     retry(): boolean;
     /** Moves past a cleared level, or to "complete" if it was the last one. Returns false unless status is "cleared". */
     advance(): boolean;
+    /** Jumps directly to an unlocked level and starts it. Returns false for an unknown or still-locked level. */
+    select(level: string): boolean;
+    /** Whether a level can be entered: the first level always, later ones once the preceding level has a cleared record. */
+    isUnlocked(level: string): boolean;
+    /** The persisted record for a level, or `null` if it has never been cleared. */
+    record(level: string): LevelRecord | null;
+    /** A snapshot of every persisted level record, keyed by level id. */
+    records(): Readonly<Record<string, LevelRecord>>;
     reset(): void;
+    /** Wipes all persisted completion/star records (and the frontier), returning to a fresh campaign. */
+    clearRecords(): void;
     progress(): LevelSequenceProgress;
 }
 /**

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,3 +1,4 @@
+/** One possible drop in a {@link LootTableDef} — an item or currency, its count range, and its odds. */
 export interface LootEntry {
     item?: string;
     currency?: string;
@@ -7,6 +8,7 @@ export interface LootEntry {
     /** 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;
@@ -18,6 +20,7 @@ export interface LootTableDef {
     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;
@@ -29,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

@@ -82,6 +82,7 @@ export function createLootRegistry() {
         },
     };
 }
+/** 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,6 +1,9 @@
 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";
@@ -455,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;
@@ -492,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. */
@@ -504,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 {
@@ -513,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";
@@ -525,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;
@@ -540,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;
@@ -592,7 +650,7 @@ export interface MovementCommitFrame {
 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";
@@ -624,21 +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;
-    /** 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";
+    /** 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. */
+    /** 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>;
@@ -654,6 +715,8 @@ 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"`. */

package/dist/game/recordBook.d.ts

@@ -1,8 +1,6 @@
-export interface RecordStorage {
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
-    removeItem(key: string): void;
-}
+import type { KeyValueStorage } from "./keyValueStore.js";
+/** The structural storage backend a record book persists through — an alias of the shared {@link KeyValueStorage} seam (browser `localStorage`, a test stub, or `null`). */
+export type RecordStorage = KeyValueStorage;
 export type RecordDirection = "lower" | "higher";
 export interface RecordBookConfig<K extends string> {
     readonly key: string;

package/dist/index.d.ts

@@ -1,5 +1,12 @@
 export * from "./runtime/save.js";
 export * from "./runtime/snapshot.js";
+export * from "./runtime/worldSnapshot.js";
+export * from "./runtime/worldReplication.js";
+export * from "./game/connectedPlayers.js";
+export * from "./runtime/hostedGameRunner.js";
+export * from "./runtime/hostedWorldSession.js";
+export * from "./runtime/worldMirror.js";
+export * from "./runtime/worldChannel.js";
 export * from "./runtime/commandRunner.js";
 export * from "./runtime/gameRuntime.js";
 export * from "./runtime/adapter.js";