@jgengine/core 0.10.0 → 0.12.0

package/dist/runtime/gameContextTypes.d.ts

@@ -0,0 +1,467 @@
+import type { CardPile, CardPileConfig } from "../cards/cardPile.js";
+import type { EffectInput, EffectResult, EffectVia, ReceiveMap, SingleTargetEffectInput } from "../combat/effects.js";
+import type { ProjectileSystem } from "../combat/projectiles.js";
+import type { HitReaction, HitReactionConfig, ImpactPresetName } from "../combat/hitReaction.js";
+import type { TelegraphShape } from "../combat/telegraph.js";
+import type { CommandDefinition, CommandResult } from "../commands/commandRegistry.js";
+import type { ChargeOptions as WalletChargeOptions } from "../economy/wallet.js";
+import type { Cosmetics } from "../game/cosmetics.js";
+import type { GameDefinition } from "../game/defineGame.js";
+import type { TerrainField } from "../world/terrain.js";
+import type { GameEventMap, GameEvents, VfxKind } from "../game/events.js";
+import type { VfxInstanceStore } from "../game/vfxInstance.js";
+import type { GameFeed } from "../game/feed.js";
+import type { Leaderboard } from "../game/leaderboard.js";
+import type { Loadouts } from "../game/loadout.js";
+import type { Drop, LootTableDef } from "../game/lootTable.js";
+import type { GameDialogue } from "../game/dialogue.js";
+import type { QuestJournal } from "../game/quest.js";
+import type { WorldItemRecord, WorldItemSpawnInput } from "../game/worldItem.js";
+import type { Chat } from "../game/chat.js";
+import type { Social } from "../game/social.js";
+import type { TradeField, TradeSystem } from "../game/trade.js";
+import type { Unlocks } from "../game/unlocks.js";
+import type { InventoryLayout, InventorySet } from "../inventory/inventoryModel.js";
+import type { ContextVerb } from "../interaction/contextMenu.js";
+import type { ProximityPrompt } from "../interaction/proximityPrompt.js";
+import type { ItemUseHandler, ItemUseInput, ItemUseRejection, ItemUseResult } from "../item/use.js";
+import type { WeaponStats } from "../item/weapon.js";
+import type { PoseAllowedStates, PoseState } from "../movement/poseState.js";
+import type { ModelAssetRef } from "../scene/assetCatalog.js";
+import type { BodyBind } from "../scene/bodyBind.js";
+import type { PaintLayer } from "../scene/paintLayer.js";
+import type { EntityStatsApi, StatCatalog } from "../scene/entityStats.js";
+import type { EntityBlackboard, EntityPose, EntityPosition, EntityStore, SceneEntity, SpawnOptions, SpawnPose } from "../scene/entityStore.js";
+import type { Forms } from "../scene/form.js";
+import type { EntityColliderSet, ModelBodySource } from "../scene/colliders.js";
+import type { ObjectRaycastHit, ObjectRaycastInput } from "../scene/objectQuery.js";
+import type { ObjectStore } from "../scene/objectStore.js";
+import type { Roster } from "../scene/roster.js";
+import type { SelectionSet } from "../scene/selection.js";
+import type { ConnectedPlayers } from "../game/connectedPlayers.js";
+import type { Possession } from "../scene/possession.js";
+import type { SceneRaycastHit, SceneRaycastInput } from "../scene/sceneRaycast.js";
+import type { MoveTowardOptions, SpatialApi } from "../scene/spatial.js";
+import type { CycleTargetOptions } from "../scene/targeting.js";
+import type { Stats } from "../stats/statModifiers.js";
+import type { ObservableKeyedStore } from "../store/observableKeyedStore.js";
+import type { SnapshotModule, SnapshotViewer, WorldSnapshot } from "./worldSnapshot.js";
+import type { ReplicationPolicy } from "./worldProjection.js";
+import type { RuntimeSave, RuntimeSaveOptions } from "./runtimeSave.js";
+import type { SimClock } from "../time/simClock.js";
+import type { TurnLoop, TurnLoopConfig } from "../turn/turnLoop.js";
+import type { RaceState, RaceStateConfig } from "../game/race.js";
+import type { CameraDirector } from "./cameraDirector.js";
+import type { InputSnapshot } from "./inputSnapshot.js";
+import type { MotionIntents } from "./motionIntents.js";
+import type { OnDeathSpec } from "../combat/death.js";
+export interface GameContextItemEntry {
+    use?: string;
+    weapon?: Record<string, unknown>;
+    trade?: TradeField;
+    /** Rarity id read by the `worldItem` loot-filter/render binding when this item drops to the ground (#32/#33). */
+    rarity?: string;
+    /** Base item type read by the loot-filter rule evaluator (#33); defaults to the item id when absent. */
+    baseType?: string;
+}
+export type CatalogEntityRole = "player" | "enemy" | "hostile" | "npc" | "vehicle";
+export interface GameContextEntityEntry {
+    stats?: StatCatalog;
+    receive?: ReceiveMap;
+    onDeath?: OnDeathSpec;
+    movement?: PoseAllowedStates & {
+        walkSpeed?: number;
+    };
+    role?: CatalogEntityRole;
+    /** Right-click context-menu verbs for this entity (#31). */
+    verbs?: readonly ContextVerb[];
+    /** Purpose-specific colliders (physical body + named damage hitboxes). */
+    colliders?: EntityColliderSet;
+    /** Uniform visual scale of the rendered mesh; derives a matching hitbox (and eye-height) when no explicit `colliders` are set. */
+    scale?: number;
+}
+export interface GameContextObjectEntry {
+    proximityPrompt?: ProximityPrompt;
+    breakable?: false | {
+        baseBreakTime: number;
+    };
+    slotInventory?: InventoryLayout;
+    /** Right-click context-menu verbs for this object (#31). */
+    verbs?: readonly ContextVerb[];
+    colliders?: EntityColliderSet;
+    halfExtents?: readonly [number, number, number];
+}
+export interface GameContextContent {
+    itemById?(itemId: string): GameContextItemEntry | null | undefined;
+    entityById?(catalogId: string): GameContextEntityEntry | null | undefined;
+    objectById?(catalogId: string): GameContextObjectEntry | null | undefined;
+}
+export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> {
+    definition: GameDefinition<TAssetRef, TMultiplayer>;
+    content: GameContextContent;
+    player: {
+        userId: string;
+        isNew: boolean;
+    };
+    now?: () => number;
+    occluder?: (from: EntityPosition, to: EntityPosition) => boolean;
+    /** Bind `ctx.game.save` to a pluggable backend (offline/single-player whole-world save). The shell resolves this from `defineGame({ save })`; multiplayer leaves it off (the host persists). */
+    save?: RuntimeSaveOptions;
+    /**
+     * Host-side per-viewer replication policy — private-state and area-of-interest projection over the
+     * wire. Bound on the authoritative host only. Unset (the default) replicates the whole world to every
+     * client, exactly as before; the simulation is identical either way, so a game plays the same.
+     */
+    replication?: ReplicationPolicy;
+    /**
+     * Render-model lookup feeding collider auto-fit: what each entity kind / object catalog id renders as
+     * (resolved `entityModels`/`objectModels` — the shell wires this automatically). When set, entities and
+     * objects without authored `colliders` get hitboxes fitted to their model's measured bounds instead of
+     * the humanoid/unit-cube defaults. A multiplayer host should receive the same lookup as its clients so
+     * both resolve identical colliders.
+     */
+    models?: GameContextModels;
+}
+/** Per-kind render-model lookup for {@link GameContextOptions.models}; a resolved `ModelConfig` satisfies {@link ModelBodySource} structurally.
+ * @capability collider-autofit hitboxes and physical bodies fit each kind's rendered model bounds automatically — no hand-tuned sizes
+ */
+export interface GameContextModels {
+    entity?(kind: string): ModelBodySource | null | undefined;
+    object?(catalogId: string): ModelBodySource | null | undefined;
+}
+export interface SceneObjectContext extends ObjectStore {
+    catalog(instanceId: string): GameContextObjectEntry | null;
+    raycast(input: ObjectRaycastInput): ObjectRaycastHit | null;
+    raycastAll(input: ObjectRaycastInput): readonly ObjectRaycastHit[];
+    setColliders(instanceId: string, colliders: EntityColliderSet | null): void;
+    collidersOf(instanceId: string): EntityColliderSet | null;
+    /**
+     * Per-instance selection/highlight state for placed objects — the reactive counterpart to
+     * `worldHealthBars`/`nameplates` (entities), so a build-mode or RTS selection ring reads
+     * `ctx.scene.object.selection` instead of hand-rolling one through `WorldOverlay` against external
+     * state. Mutations (`add`/`remove`/`toggle`/`replace`/`clear`) bump `ctx.version()`/notify
+     * `ctx.subscribe` like every other `ctx` surface. Render it with `WorldObjectHighlights`
+     * (`@jgengine/shell/world/WorldHud`).
+     */
+    selection: SelectionSet;
+}
+export interface FloatTextInput {
+    instanceId?: string;
+    position?: [number, number, number];
+    text?: string;
+    kind?: string;
+    amount?: number;
+    hitType?: string;
+    element?: string;
+    crit?: boolean;
+    scale?: number;
+}
+/** Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`. */
+export interface VfxInput {
+    kind: VfxKind;
+    color: number;
+    from?: string | readonly [number, number, number];
+    to?: string | readonly [number, number, number];
+    radius?: number;
+    durationMs?: number;
+}
+export interface TelegraphInput {
+    from: string;
+    shape: TelegraphShape;
+    at: [number, number, number];
+    dir?: number;
+    windupMs: number;
+    kind?: string;
+    effect?: {
+        effect: string;
+        via?: EffectVia;
+        radius?: number;
+        falloff?: "linear" | "none";
+        los?: boolean;
+    };
+}
+export interface HitReactionInput {
+    from: string;
+    to: string;
+    config: HitReactionConfig | ImpactPresetName;
+    power?: number;
+}
+/** Options for {@link SceneEntityContext.moveTowardCommit}: {@link MoveTowardOptions} plus an optional facing turn. */
+export interface MoveTowardCommitOptions extends MoveTowardOptions {
+    /** Rotate the entity to face its direction of travel instead of preserving its current `rotationY`. Default false. */
+    face?: boolean;
+}
+export interface SceneEntityContext {
+    spawn(name: string, options?: SpawnOptions): string;
+    despawn(instanceId: string): boolean;
+    update: EntityStore["update"];
+    setPose(instanceId: string, pose: EntityPose): boolean;
+    setPoseConstraint: EntityStore["setPoseConstraint"];
+    get(instanceId: string): SceneEntity | null;
+    list(): readonly SceneEntity[];
+    ids: EntityStore["ids"];
+    subscribeMembership: EntityStore["subscribeMembership"];
+    spawnPoseOf(instanceId: string): SpawnPose | null;
+    resetToSpawn(instanceId: string): boolean;
+    resetAllToSpawn(filter?: (entity: SceneEntity) => boolean): number;
+    blackboard: EntityBlackboard;
+    stats: EntityStatsApi;
+    floatText(input: FloatTextInput): void;
+    vfx(input: VfxInput): void;
+    /**
+     * Retained VFX registry for long-lived, updatable effects (held beams, tethers, zones, target lines) whose
+     * endpoints and params change over time — the persistent complement to the one-shot {@link SceneEntityContext.vfx}
+     * burst. `upsert` creates/replaces by stable id, `update` nudges dynamic params, `stop` disposes with an optional
+     * fade; endpoints given as an entity instance id are followed live by the renderer without per-frame commands.
+     */
+    vfxInstance: VfxInstanceStore;
+    telegraph(input: TelegraphInput): () => void;
+    hitReaction(input: HitReactionInput): HitReaction | null;
+    setTarget(fromId: string, toId: string | null): void;
+    getTarget(fromId: string): string | null;
+    cycleTarget(fromId: string, options?: CycleTargetOptions): string | null;
+    canReceive(instanceId: string, effect: string, magnitude?: number): string | null;
+    preview(input: SingleTargetEffectInput): number;
+    effect(input: EffectInput): EffectResult[];
+    willHitProjectile: ProjectileSystem["willHitProjectile"];
+    fireProjectile: ProjectileSystem["fireProjectile"];
+    settleProjectile: ProjectileSystem["settleProjectile"];
+    distance: SpatialApi["distance"];
+    inRadius: SpatialApi["inRadius"];
+    hasLineOfSight: SpatialApi["hasLineOfSight"];
+    queryArc: SpatialApi["queryArc"];
+    moveToward: SpatialApi["moveToward"];
+    /**
+     * `moveToward` plus commit: steps `instanceId` toward `target` and immediately `setPose`s the
+     * result, so a per-tick mover no longer pairs `moveToward` with a hand-written `setPose`.
+     * `options.face` turns the entity to its direction of travel; omitted preserves the current
+     * `rotationY`. Returns the committed position (`null`, committing nothing, when `moveToward` would
+     * — unknown instance/target).
+     */
+    moveTowardCommit(instanceId: string, target: EntityPosition | string, options: MoveTowardCommitOptions): EntityPosition | null;
+    invalidateSpatial: SpatialApi["invalidate"];
+    setColliders(instanceId: string, colliders: EntityColliderSet | null): void;
+    collidersOf(instanceId: string): EntityColliderSet | null;
+    /** Uniform visual scale from the entity's catalog entry (1 when unscaled). */
+    visualScaleOf(instanceId: string): number;
+    form: Forms;
+    paint: PaintLayer;
+    /**
+     * Lazily creates (on first call) or returns the existing declarative bind for `key` — the sim-snapshot →
+     * scene-entity pose mirror (#673). Call `bind(key).sync(bodies, dt)` once per tick with every sim body's
+     * current snapshot instead of hand-writing `setPose` per body: an id seen for the first time is spawned
+     * from its `kind`, an id already bound is posed, and a previously-bound id absent from this tick's
+     * `bodies` is despawned — no per-game spawn/despawn dance.
+     */
+    bind(key: string): BodyBind;
+}
+export type WorldItemPickupResult = {
+    status: "ok";
+    record: WorldItemRecord;
+} | {
+    status: "rejected";
+    reason: string;
+};
+export interface SceneWorldItemContext {
+    spawn(input: WorldItemSpawnInput): WorldItemRecord;
+    get(instanceId: string): WorldItemRecord | null;
+    list(): readonly WorldItemRecord[];
+    nearestInRadius(from: EntityPosition, radius: number, filter?: (record: WorldItemRecord) => boolean): string | null;
+    pickup(instanceId: string, userId: string): WorldItemPickupResult;
+    consume(instanceId: string): WorldItemRecord | null;
+}
+export interface GameContextCommands {
+    define<TInput>(name: string, definition: CommandDefinition<GameContext, TInput>): void;
+    has(name: string): boolean;
+    names(): string[];
+    run(name: string, input: unknown): CommandResult<GameContext>;
+    /** Run a command attributed to `actorUserId` — a shared-world host routes each client's command through this so the handler can read {@link actor}. */
+    runAs(actorUserId: string, name: string, input: unknown): CommandResult<GameContext>;
+    /** The user a command is running on behalf of, or `null` outside a {@link runAs} call — commands default to `ctx.player.userId` when this is `null`. */
+    actor(): string | null;
+}
+export interface GameContextFeed extends Omit<GameFeed, "bind"> {
+    bind(action: keyof GameEventMap): () => void;
+}
+export interface GameContextLoot {
+    register(def: LootTableDef): void;
+    has(id: string): boolean;
+    roll(id: string, rng?: () => number): Drop[];
+    grantToPlayer(userId: string, drops: Drop[], source?: string): void;
+}
+export interface GameContextEconomy {
+    balance(userId: string, currencyId: string): number;
+    grant(userId: string, currencyId: string, amount: number): void;
+    /** `options.overdraft` opts this charge into carrying a negative balance (`true` unlimited, `{ max }` capped) — omitted keeps the strict no-debt default. */
+    charge(userId: string, currencyId: string, amount: number, options?: WalletChargeOptions): {
+        reason: string;
+    } | null;
+    /** True once `balance(userId, currencyId)` has gone negative under an overdraft-enabled charge. */
+    isOverdrawn(userId: string, currencyId: string): boolean;
+}
+export interface GameContextItemUse {
+    register(handlers: Record<string, ItemUseHandler<GameContext>>): void;
+    registered(): string[];
+    can(input: ItemUseInput): ItemUseRejection | null;
+    use(input: ItemUseInput): ItemUseResult<GameContext>;
+}
+export interface GameContextWorld {
+    ground: TerrainField;
+    groundHeightAt(x: number, z: number): number;
+}
+export interface GameContextCards {
+    /** Lazily creates (on first call, `config` required) or returns the existing notify-wrapped pile for `id`. */
+    pile(id: string, config?: CardPileConfig): CardPile;
+}
+export interface GameContextTurn {
+    /** Lazily creates (on first call, `config` required) or returns the existing notify-wrapped turn loop for `id`. */
+    loop(id: string, config?: TurnLoopConfig): TurnLoop;
+}
+export interface GameContextRace {
+    /** Lazily creates (on first call, `config` required) or returns the existing reactive race for `id` — discrete mutations and eventful `update` calls bump `ctx.version()`, so HUDs stop hand-managing `store.set` (#286.2). */
+    state(id: string, config?: RaceStateConfig): RaceState;
+}
+/** Reachable audio seam on `ctx.game`: `play`, `music`, and `resume` route through the `audio.play`/`audio.music`/`audio.resume` events the shell's audio engine listens on, so game code triggers sound without importing the shell. Retained `loop`/`setLoop`/`stopLoop` add id-keyed loops with live pitch/gain control over `audio.loopStart`/`audio.loopSet`/`audio.loopStop` (#1051). */
+export interface GameAudio {
+    play(sound: string, at?: readonly [number, number, number]): void;
+    /** Crossfade the procedural soundtrack to `theme` (null fades out); `transpose` shifts the incoming theme's key in semitones. */
+    music(theme: string | null, transpose?: number): void;
+    resume(): void;
+    /**
+     * Start — or idempotently keep — the retained, id-keyed loop `id` playing catalog `sound`, emitting
+     * `audio.loopStart`. Re-calling with the same `sound` does not restart it (no click); a different `sound`
+     * replaces the source. Pair with {@link GameAudio.setLoop} to track a live signal — an RPM-pitched engine
+     * loop, a slip-scaled tire squeal (#1051) — and {@link GameAudio.stopLoop} to end it.
+     */
+    loop(id: string, sound: string, options?: {
+        at?: readonly [number, number, number];
+    }): void;
+    /**
+     * Live-update retained loop `id` via `audio.loopSet`: `rate` re-pitches it (1 = authored pitch, clamped
+     * 0.25–4 by the shell), `gain` rescales volume (0–1), `at` repositions its emitter. Cheap to call every
+     * tick (~60 Hz) — the shell ramps rate/gain over ~20 ms to avoid zipper noise. A no-op when `id` is not a
+     * live loop (an update may race a stop) (#1051).
+     */
+    setLoop(id: string, params: {
+        rate?: number;
+        gain?: number;
+        at?: readonly [number, number, number];
+    }): void;
+    /** Stop and dispose retained loop `id` (emits `audio.loopStop`); an unknown `id` is ignored (#1051). */
+    stopLoop(id: string): void;
+}
+/** The live engine handle a game's loop, systems, commands, and UI read and mutate — entities, objects, the reactive store, opted-in `game.*` subsystems, world queries, and the sim clock. One context = one running world. */
+export interface GameContext {
+    scene: {
+        object: SceneObjectContext;
+        entity: SceneEntityContext;
+        worldItem: SceneWorldItemContext;
+        raycast(input: SceneRaycastInput): SceneRaycastHit | null;
+        raycastAll(input: SceneRaycastInput): readonly SceneRaycastHit[];
+    };
+    world: GameContextWorld;
+    game: {
+        commands: GameContextCommands;
+        events: GameEvents;
+        audio: GameAudio;
+        /** Play a model's one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an attack swing) — emits `entity.animation` for the shell to pick up. */
+        playEntityAnimation(instanceId: string, event: string): void;
+        feed: GameContextFeed;
+        loot: GameContextLoot;
+        /** Shop/vendor barter — present only when `features.trade` is set. */
+        trade?: TradeSystem;
+        /** Quest/mission journal — present only when `features.quest` is set. */
+        quest?: QuestJournal;
+        /** Talkable-NPC dialogue open/close bridge — present only when `features.dialogue` is set. */
+        dialogue?: GameDialogue;
+        /** Friends/party/presence/emotes/world-invites — present only when `features.social` is set. */
+        social?: Social;
+        /** Channels + messages — present only when `features.chat` is set (implies `social`). */
+        chat?: Chat;
+        /** Earned unlockable content — present only when `features.unlocks` is set. */
+        unlocks?: Unlocks;
+        economy: GameContextEconomy;
+        /** Competitive score tracking — present only when `features.leaderboard` is set. */
+        leaderboard?: Leaderboard;
+        /** Owned-entity roster — present only when `features.roster` is set. */
+        roster?: Roster;
+        /** Game-defined keyed reactive store slot (#163.1); mutations bump `ctx.version()`/notify `ctx.subscribe`. */
+        store: ObservableKeyedStore<unknown>;
+        /** Card pile zones — present only when `features.cards` is set. */
+        cards?: GameContextCards;
+        /** Turn/phase loop — present only when `features.turn` is set. */
+        turn?: GameContextTurn;
+        /** Lap/checkpoint race state — present only when `features.race` is set. */
+        race?: GameContextRace;
+        /** Connected-player set for a shared world — present only when `features.players` is set. */
+        players?: ConnectedPlayers;
+        /** Whole-world save/load bound to a pluggable backend — present only when `defineGame({ save })` is set (offline/single-player). Drive save points and quest/area checkpoints with `checkpoint()`, restore on boot with `load()`. */
+        save?: RuntimeSave;
+        /**
+         * Register a save-only snapshot module after boot (system-owned persistence).
+         * Used by `composeGameLoop` / `installSystems` when a system declares `save`.
+         */
+        registerSave?(module: SnapshotModule): void;
+        /**
+         * Register a host→client replication module after boot (system-owned replication).
+         * Used by `composeGameLoop` / `installSystems` when a system declares `replicate`.
+         */
+        registerReplicate?(module: SnapshotModule): void;
+    };
+    player: {
+        /** The acting player's id — the command actor inside `runAs`, the local player everywhere else. */
+        userId: string;
+        isNew: boolean;
+        /** The acting player's inventory set — the command actor's bags inside `runAs`, the local player's everywhere else. */
+        inventory: InventorySet<string>;
+        /** A specific player's inventory set — how a host reads or grants into any connected player's bags. */
+        inventoryFor(userId: string): InventorySet<string>;
+        /** The acting player's stat modifiers — the command actor's inside `runAs`, the local player's everywhere else. */
+        stats: Stats<string>;
+        /** A specific player's stat modifiers — how a host reads or buffs any connected player's stats. */
+        statsFor(userId: string): Stats<string>;
+        loadout: Loadouts;
+        applyLoadout(userId: string, loadoutId: string): {
+            reason: string;
+        } | null;
+        movement: PoseState;
+        possession: Possession;
+        /** Cosmetic skins/customization — present only when `features.cosmetics` is set. */
+        cosmetics?: Cosmetics;
+        /** Motion seam into the movement integrator (#162.4); routes to the command actor's queue (or the local player outside a command), so a command's impulse lands on whoever ran it. See `MotionIntents`. */
+        motion: MotionIntents;
+        /** A specific player's motion queue — how the host-side per-player movement integrator drains each connected player's impulses. */
+        motionFor(userId: string): MotionIntents;
+    };
+    item: {
+        use: GameContextItemUse;
+        weapon: WeaponStats;
+    };
+    time: SimClock;
+    /** Runtime camera-follow/cinematic override (#196.2); the shell reads `followedEntityId()` each frame. */
+    camera: CameraDirector;
+    /** Held-input snapshot published by the shell each frame before `onTick` (#164.1). */
+    input: InputSnapshot;
+    subscribe(listener: () => void): () => void;
+    version(): number;
+    /**
+     * Bump {@link version}/notify {@link subscribe} directly — the escape hatch for a command that only
+     * mutates game-owned state outside the entity/object/economy/store layers (an external session map,
+     * a plain closure variable) and needs to force a reactive HUD refresh without faking a `ctx.game.store.set`.
+     */
+    touch(): void;
+    /**
+     * Gather every opted-in live subsystem into one {@link WorldSnapshot} — entities, entity stats, the
+     * keyed store, the action feed, plus leaderboard/chat when those features are on. The full-world
+     * baseline a host sends a joining client; {@link hydrate} is its inverse. Pass a `viewer` and the host
+     * projects the snapshot to only what that viewer may see (private state, area of interest) when a
+     * {@link GameContextOptions.replication} policy is set; without one the viewer argument is a no-op.
+     */
+    snapshot(viewer?: SnapshotViewer): WorldSnapshot;
+    /** Apply a {@link WorldSnapshot} from an authoritative host, hydrating each subsystem key present in it. */
+    hydrate(snapshot: WorldSnapshot): void;
+    /** Aggregate world-dirty version summed across replicated modules; the host replicator skips an unchanged commit. @internal */
+    replicationVersion(): number;
+    /** True when a {@link GameContextOptions.replication} policy makes {@link snapshot} viewer-dependent (private/AOI projection is active). @internal */
+    replicatesPerViewer(): boolean;
+}

package/dist/runtime/gameContextTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/gameRuntime.d.ts

@@ -43,4 +43,5 @@ export type GameRuntime = {
     joinPlayer: (snapshot: GameRuntimeSnapshot, userId: string, isNew: boolean) => GameRuntimeSnapshot;
     toProfileRow: (snapshot: GameRuntimeSnapshot, userId: string) => RuntimeProfileRow | null;
 };
+/** @internal */
 export declare function createGameRuntime(definition: GameRuntimeDefinition): GameRuntime;

package/dist/runtime/gameRuntime.js

@@ -1,5 +1,6 @@
 import { runCommand } from "./commandRunner.js";
 import { createEmptyPlayerRow, createRuntimeSnapshot, } from "./snapshot.js";
+/** @internal */
 export function createGameRuntime(definition) {
     const loop = definition.loop;
     let initialized = false;

package/dist/runtime/headlessRunner.d.ts

@@ -0,0 +1,62 @@
+import type { GameDefinition, GameLoop } from "../game/defineGame.js";
+import type { PointerAxisState } from "../input/pointerAxis.js";
+import type { ModelAssetRef } from "../scene/assetCatalog.js";
+import { type GameContext, type GameContextContent, type GameContextModels } from "./gameContext.js";
+import type { InputSnapshot } from "./inputSnapshot.js";
+/** One step's worth of player intent handed to {@link HeadlessRunner.step} — the held-action set and pointer state the shell would otherwise publish from the browser each frame. */
+export interface HeadlessInput {
+    /** Replaces the held-action set for this step; edge detection (`justPressed`/`justReleased`) rolls the previous set forward. Omit to keep the last published set. */
+    held?: readonly string[];
+    /** Replaces the normalized pointer state; omit to leave the last pointer unchanged (pass `null` to clear it). */
+    pointer?: PointerAxisState | null;
+}
+export interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> {
+    definition: GameDefinition<TAssetRef, TMultiplayer>;
+    /** Catalog resolvers (`entityById`/`objectById`) the context uses; defaults to an empty catalog. */
+    content?: GameContextContent;
+    /** Lifecycle hooks — `onInit`/`onNewPlayer` fire at construction, `onTick` on every {@link HeadlessRunner.step}. The shell keeps this separate from `definition` (presentation wraps it); a headless caller passes it directly. */
+    loop?: GameLoop<GameContext>;
+    /** The single local player; defaults to `{ userId: "player", isNew: true }`. */
+    player?: {
+        userId: string;
+        isNew: boolean;
+    };
+    /** Wall-clock source for the sim clock — inject a deterministic counter for reproducible runs. */
+    now?: () => number;
+    /** Per-step real-dt clamp in seconds, matching the shell's frame cap so one long stall can't fast-forward the sim. Default `0.05`. */
+    maxStepSeconds?: number;
+    /**
+     * Drive the built-in keyboard player-movement controller from the held-action set each step, exactly as the shell's
+     * FrameDriver does for pose-driven games. Off by default — tick-driven games move their own entities inside
+     * `onTick` and don't need it.
+     */
+    playerMovement?: boolean;
+    /** Yaw heading (radians) fed to the movement controller when `playerMovement` is on; the shell supplies its camera yaw. */
+    heading?: number;
+    /** Render-model lookup for collider auto-fit — pass what the shell would derive from `entityModels`/`objectModels` so headless raycasts hit the same boxes as play. */
+    models?: GameContextModels;
+}
+/**
+ * A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init
+ * hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole
+ * play path (time, input, `onTick`, behaviour nav, optional player movement) runs from `core` primitives alone, so a
+ * non-React host (a server tick, a test, a CLI replay) can play a real game and read its world snapshot. The shell's
+ * FrameDriver is one such driver bolted to `useFrame`; this is the same step distilled out of the render tree.
+ *
+ * @capability headless-runner play a real game loop with no renderer — tick, feed input, read the world snapshot
+ */
+export interface HeadlessRunner {
+    /** The live game context — read `ctx.scene.entity.list()`, `ctx.game.store`, `ctx.subscribe`/`ctx.version()` for the world snapshot. */
+    readonly ctx: GameContext;
+    /** The per-frame input the loop reads; the same object exposed as `ctx.input`. */
+    readonly input: InputSnapshot;
+    readonly userId: string;
+    /**
+     * Advance the simulation one step. Publishes `input` (if given), advances the sim clock by the clamped real dt,
+     * runs optional player movement, then `loop.onTick` and behaviour nav. Returns the scaled game dt `onTick` saw.
+     */
+    step(dtSeconds: number, input?: HeadlessInput): number;
+    /** Publish input without advancing — for pre-seeding the held set before the first {@link step}. */
+    publishInput(input: HeadlessInput): void;
+}
+export declare function createHeadlessRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HeadlessRunnerOptions<TAssetRef, TMultiplayer>): HeadlessRunner;

package/dist/runtime/headlessRunner.js

@@ -0,0 +1,45 @@
+import { resolvePlayerMovementTuning, stepPlayerMovement, } from "../movement/playerMovement.js";
+import { advanceBehaviors } from "../scene/behaviorRuntime.js";
+import { createGameContext } from "./gameContext.js";
+export function createHeadlessRunner(options) {
+    const { definition, loop } = options;
+    const content = options.content ?? {};
+    const player = options.player ?? { userId: "player", isNew: true };
+    const maxStep = options.maxStepSeconds ?? 0.05;
+    const ctx = createGameContext({
+        definition,
+        content,
+        player,
+        ...(options.now === undefined ? {} : { now: options.now }),
+        ...(options.models === undefined ? {} : { models: options.models }),
+    });
+    loop?.onInit?.(ctx);
+    loop?.onNewPlayer?.(ctx);
+    const tuning = options.playerMovement === true
+        ? resolvePlayerMovementTuning({ physics: definition.physics, world: definition.world })
+        : null;
+    function publishInput(input) {
+        if (input.held !== undefined)
+            ctx.input.publish(input.held);
+        if (input.pointer !== undefined)
+            ctx.input.publishPointer(input.pointer);
+    }
+    return {
+        ctx,
+        input: ctx.input,
+        userId: player.userId,
+        publishInput,
+        step(dtSeconds, input) {
+            if (input !== undefined)
+                publishInput(input);
+            const dt = Math.min(dtSeconds, maxStep);
+            const gameDt = ctx.time.advance(dt);
+            if (tuning !== null) {
+                stepPlayerMovement(ctx, player.userId, { held: ctx.input.held(), pointer: ctx.input.pointer() }, dt, tuning, options.heading);
+            }
+            loop?.onTick?.(ctx, gameDt);
+            advanceBehaviors(ctx, gameDt);
+            return gameDt;
+        },
+    };
+}

package/dist/runtime/hostPersistence.d.ts

@@ -58,11 +58,13 @@ export type LeaderboardEntry = {
     value: number;
 };
 export declare const LEADERBOARD_PENDING_KEY = "leaderboardPending";
+/** @internal */
 export declare function drainPendingLeaderboardIncrements(session: Record<string, unknown>): {
     increments: LeaderboardIncrement[];
     session: Record<string, unknown>;
 };
 export declare const LEADERBOARD_TOP_LIMIT = 100;
+/** @internal */
 export declare function clampLimit(value: number | undefined, fallback: number, max: number): number;
 export type LeaderboardRow = {
     gameId: string;
@@ -73,8 +75,11 @@ export type LeaderboardRow = {
     value: number;
     updatedAt: number;
 };
+/** @internal */
 export declare function leaderboardRowKey(row: Omit<LeaderboardRow, "value" | "updatedAt">): string;
+/** @internal */
 export declare function applyLeaderboardRows(rows: Map<string, LeaderboardRow>, gameId: string, entries: LeaderboardIncrement[], now: number): void;
+/** @internal */
 export declare function topLeaderboardRows(rows: Iterable<LeaderboardRow>, args: {
     gameId: string;
     stat: string;
@@ -82,9 +87,12 @@ export declare function topLeaderboardRows(rows: Iterable<LeaderboardRow>, args:
     serverId?: string;
     limit?: number;
 }): LeaderboardEntry[];
+/** @internal */
 export declare function profileLeaderboardStats(rows: Iterable<LeaderboardRow>, gameId: string, userId: string): Record<string, number>;
 export declare const FEED_RING_LIMIT = 20;
+/** @internal */
 export declare function trimFeedEntries<T>(entries: T[], limit?: number): T[];
+/** @internal */
 export declare function shouldAutoSave(save: SaveConfig, dirtyAt: number | undefined, lastSavedAt: number | undefined, now: number): boolean;
 export type ServerListing = {
     serverId: string;
@@ -101,9 +109,11 @@ export type ServerListing = {
 export type ToServerListingOptions = {
     includeJoinCode?: boolean;
 };
+/** @internal */
 export declare function toServerListing(record: GameServerRecord, options?: ToServerListingOptions): ServerListing;
 export declare const OPEN_SERVER_LISTING_LIMIT = 20;
 export declare const OPEN_SERVER_LISTING_MAX = 100;
+/** @internal */
 export declare function toOpenServerListings(listings: Iterable<ServerListing>, limit?: number): ServerListing[];
 export type HostPersistence = {
     savePlan?: (plan: ServerPersistPlan) => Promise<void>;
@@ -141,6 +151,7 @@ export type HostPersistence = {
         userId: string;
     }) => Promise<Record<string, number>>;
 };
+/** @internal */
 export declare function buildHydratePlayers(server: GameServerRecord, profiles: Record<string, PlayerProfileRecord | null>): Record<string, RuntimePlayerRow>;
 export type ServerPersistPlan = {
     server: GameServerRecord;
@@ -149,4 +160,5 @@ export type ServerPersistPlan = {
     deletedChunks: string[];
     leaderboard: LeaderboardIncrement[];
 };
+/** @internal */
 export declare function planServerPersist(server: GameServerRecord, snapshot: GameRuntimeSnapshot, save: SaveConfig, now: number): ServerPersistPlan;