@jgengine/core 0.9.0 → 0.10.0

package/dist/runtime/gameContext.d.ts

@@ -28,18 +28,20 @@ import { type PoseAllowedStates, type PoseState } from "../movement/poseState.js
 import type { ModelAssetRef } from "../scene/assetCatalog.js";
 import { type PaintLayer } from "../scene/paintLayer.js";
 import { type EntityStatsApi, type StatCatalog } from "../scene/entityStats.js";
-import type { EntityPose, EntityPosition, EntityStore, SceneEntity, SpawnOptions, SpawnPose } from "../scene/entityStore.js";
+import type { EntityBlackboard, EntityPose, EntityPosition, EntityStore, SceneEntity, SpawnOptions, SpawnPose } from "../scene/entityStore.js";
 import { type Forms } from "../scene/form.js";
-import type { EntityColliderSet } from "../scene/colliders.js";
+import { type EntityColliderSet } from "../scene/colliders.js";
 import { type ObjectRaycastHit, type ObjectRaycastInput } from "../scene/objectQuery.js";
 import { type ObjectStore } from "../scene/objectStore.js";
 import { type Roster } from "../scene/roster.js";
+import { type ConnectedPlayers } from "../game/connectedPlayers.js";
 import { type Possession } from "../scene/possession.js";
 import { type SceneRaycastHit, type SceneRaycastInput } from "../scene/sceneRaycast.js";
 import { type 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 WorldSnapshot } from "./worldSnapshot.js";
 import { type SimClock } from "../time/simClock.js";
 import { type TurnLoop, type TurnLoopConfig } from "../turn/turnLoop.js";
 import { RaceState, type RaceStateConfig } from "../game/race.js";
@@ -145,6 +147,7 @@ export interface SceneEntityContext {
     spawnPoseOf(instanceId: string): SpawnPose | null;
     resetToSpawn(instanceId: string): boolean;
     resetAllToSpawn(filter?: (entity: SceneEntity) => boolean): number;
+    blackboard: EntityBlackboard;
     stats: EntityStatsApi;
     floatText(input: FloatTextInput): void;
     telegraph(input: TelegraphInput): () => void;
@@ -189,6 +192,10 @@ export interface GameContextCommands {
     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;
@@ -228,6 +235,13 @@ 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. */
+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;
+}
 export interface GameContext {
     scene: {
         object: SceneObjectContext;
@@ -240,27 +254,46 @@ export interface GameContext {
     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;
         trade: TradeSystem;
         quest: QuestJournal;
-        social: Social;
-        chat: Chat;
+        /** 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;
         unlocks: Unlocks;
         economy: GameContextEconomy;
-        leaderboard: Leaderboard;
-        roster: Roster;
+        /** 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>;
-        cards: GameContextCards;
-        turn: GameContextTurn;
-        race: GameContextRace;
+        /** 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;
     };
     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;
@@ -268,8 +301,10 @@ export interface GameContext {
         movement: PoseState;
         possession: Possession;
         cosmetics: Cosmetics;
-        /** Vertical-motion seam into the shell-owned FrameDriver (#162.4); see `MotionIntents`. */
+        /** 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;
@@ -282,5 +317,13 @@ export interface GameContext {
     input: InputSnapshot;
     subscribe(listener: () => void): () => void;
     version(): number;
+    /**
+     * 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.
+     */
+    snapshot(): WorldSnapshot;
+    /** Apply a {@link WorldSnapshot} from an authoritative host, hydrating each subsystem key present in it. */
+    hydrate(snapshot: WorldSnapshot): void;
 }
 export declare function createGameContext<TAssetRef extends ModelAssetRef, TMultiplayer>(options: GameContextOptions<TAssetRef, TMultiplayer>): GameContext;

package/dist/runtime/gameContext.js

@@ -24,11 +24,13 @@ import { createItemUse, } from "../item/use.js";
 import { createWeaponStats } from "../item/weapon.js";
 import { createPoseState } from "../movement/poseState.js";
 import { createPaintLayer } from "../scene/paintLayer.js";
-import { createEntityStatsApi, seedStatValues, setStatValue, } from "../scene/entityStats.js";
+import { createEntityStatsApi, hydrateEntityStats, seedStatValues, setStatValue, snapshotEntityStats, } from "../scene/entityStats.js";
 import { createForms } from "../scene/form.js";
+import { scaledObjectColliders } from "../scene/colliders.js";
 import { raycastObjects, raycastObjectsAll } from "../scene/objectQuery.js";
-import { createObjectStore } from "../scene/objectStore.js";
+import { createObjectStore, objectVisualScale } from "../scene/objectStore.js";
 import { createRoster } from "../scene/roster.js";
+import { createConnectedPlayers } from "../game/connectedPlayers.js";
 import { createPossession } from "../scene/possession.js";
 import { createSceneRaycast, } from "../scene/sceneRaycast.js";
 import { createSpatialApi } from "../scene/spatial.js";
@@ -36,6 +38,7 @@ import { createTargeting } from "../scene/targeting.js";
 import { createStats } from "../stats/statModifiers.js";
 import { createChangeSignal, notifyAfter } from "../store/changeSignal.js";
 import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
+import { applyWorldSnapshot, composeWorldSnapshot, } from "./worldSnapshot.js";
 import { createSimClock } from "../time/simClock.js";
 import { createTurnLoop } from "../turn/turnLoop.js";
 import { RaceState } from "../game/race.js";
@@ -47,6 +50,8 @@ export function createGameContext(options) {
     const now = options.now ?? Date.now;
     const occluder = options.occluder;
     const signal = createChangeSignal();
+    let actingUserId = null;
+    const activeUserId = () => actingUserId ?? player.userId;
     const time = createSimClock({ config: definition.time, onChange: signal.notify });
     const ground = groundFieldFor(definition.world);
     const entities = definition.scene;
@@ -107,7 +112,15 @@ export function createGameContext(options) {
         const override = objectColliders.get(instanceId);
         if (override !== undefined)
             return override;
-        return catalogObject(instanceId)?.colliders ?? null;
+        const catalog = catalogObject(instanceId);
+        if (catalog?.colliders !== undefined)
+            return catalog.colliders;
+        if (catalog?.halfExtents !== undefined)
+            return null;
+        const object = objects.get(instanceId);
+        if (object === null || object.visual?.scale === undefined)
+            return null;
+        return scaledObjectColliders(objectVisualScale(object.visual));
     }
     const targeting = notifyAfter(createTargeting({
         candidates: () => [...refreshCandidateIds()],
@@ -169,34 +182,55 @@ export function createGameContext(options) {
     const feed = createGameFeed(definition.feed);
     const lootRegistry = createLootRegistry();
     const unlocks = notifyAfter(createUnlocks(), ["grant", "hydrate"], signal.notify);
-    const rawSocial = createSocial({
-        events,
-        now,
-        emotes: {
-            entities: { get: (id) => entities.get(id) },
-            spatial: { inRadius: (center, radius, filter) => spatial.inRadius(center, radius, filter) },
-        },
-    });
-    const social = {
-        friends: notifyAfter(rawSocial.friends, ["request", "accept", "decline", "remove", "block", "hydrate"], signal.notify),
-        party: notifyAfter(rawSocial.party, ["invite", "accept", "decline", "kick", "leave", "promote"], signal.notify),
-        presence: rawSocial.presence,
-        emotes: rawSocial.emotes,
-        worldInvites: notifyAfter(rawSocial.worldInvites, ["invite", "accept", "decline"], signal.notify),
-    };
-    const chat = notifyAfter(createChat({
-        events,
-        now,
-        party: rawSocial.party,
-        proximity: {
-            entities: { get: (id) => entities.get(id) },
-            spatial: { inRadius: (center, radius, filter) => spatial.inRadius(center, radius, filter) },
-        },
-        blockedBy: (userId) => rawSocial.friends.snapshot(userId).blocked,
-    }), ["register", "send", "whisper", "hydrate"], signal.notify);
-    const leaderboard = notifyAfter(createLeaderboard(), ["increment", "hydrate"], signal.notify);
-    const roster = notifyAfter(createRoster({ now }), ["capture", "release", "setEquipped", "hydrate"], signal.notify);
-    const playerStats = createStats({});
+    const features = definition.features ?? {};
+    const rawSocial = features.social || features.chat
+        ? createSocial({
+            events,
+            now,
+            emotes: {
+                entities: { get: (id) => entities.get(id) },
+                spatial: { inRadius: (center, radius, filter) => spatial.inRadius(center, radius, filter) },
+            },
+        })
+        : null;
+    let social;
+    if (features.social && rawSocial !== null) {
+        social = {
+            friends: notifyAfter(rawSocial.friends, ["request", "accept", "decline", "remove", "block", "hydrate"], signal.notify),
+            party: notifyAfter(rawSocial.party, ["invite", "accept", "decline", "kick", "leave", "promote"], signal.notify),
+            presence: rawSocial.presence,
+            emotes: rawSocial.emotes,
+            worldInvites: notifyAfter(rawSocial.worldInvites, ["invite", "accept", "decline"], signal.notify),
+        };
+    }
+    let chat;
+    if (features.chat && rawSocial !== null) {
+        chat = notifyAfter(createChat({
+            events,
+            now,
+            party: rawSocial.party,
+            proximity: {
+                entities: { get: (id) => entities.get(id) },
+                spatial: { inRadius: (center, radius, filter) => spatial.inRadius(center, radius, filter) },
+            },
+            blockedBy: (userId) => rawSocial.friends.snapshot(userId).blocked,
+        }), ["register", "send", "whisper", "hydrate"], signal.notify);
+    }
+    const leaderboard = features.leaderboard
+        ? notifyAfter(createLeaderboard(), ["increment", "hydrate"], signal.notify)
+        : undefined;
+    const roster = features.roster
+        ? notifyAfter(createRoster({ now }), ["capture", "release", "setEquipped", "hydrate"], signal.notify)
+        : undefined;
+    const playerStatsByUser = new Map();
+    function playerStatsFor(userId) {
+        let stats = playerStatsByUser.get(userId);
+        if (stats === undefined) {
+            stats = createStats({});
+            playerStatsByUser.set(userId, stats);
+        }
+        return stats;
+    }
     const pose = createPoseState((instanceId) => catalogEntry(instanceId)?.movement);
     const commandRegistry = createCommandRegistry();
     const itemUse = createItemUse((itemId) => content.itemById?.(itemId)?.use);
@@ -211,7 +245,15 @@ export function createGameContext(options) {
         layouts[inventoryId] = { slots: declaration.slots, accepts: declaration.accepts };
     }
     const traits = Object.values(inventoryDeclarations).find((declaration) => declaration.traits !== undefined)?.traits ?? { stackLimit: () => Number.POSITIVE_INFINITY };
-    const inventory = notifyAfter(createInventorySet(layouts, traits), ["put", "take", "move", "replaceState"], signal.notify);
+    const inventoryByUser = new Map();
+    function inventoryFor(userId) {
+        let set = inventoryByUser.get(userId);
+        if (set === undefined) {
+            set = notifyAfter(createInventorySet(layouts, traits), ["put", "take", "move", "replaceState"], signal.notify);
+            inventoryByUser.set(userId, set);
+        }
+        return set;
+    }
     const wallets = new Map();
     const walletOf = (userId) => wallets.get(userId) ?? createEmptyWallet();
     const economy = {
@@ -229,7 +271,8 @@ export function createGameContext(options) {
             return null;
         },
     };
-    function putIntoAnyInventory(itemId, count) {
+    function putIntoAnyInventory(userId, itemId, count) {
+        const inventory = inventoryFor(userId);
         for (const inventoryId of inventoryIds) {
             if (inventory.put(inventoryId, itemId, count).status === "ok")
                 return;
@@ -241,7 +284,7 @@ export function createGameContext(options) {
         roll: lootRegistry.roll,
         grantToPlayer(userId, drops, source) {
             grantDrops(drops, {
-                putItem: (itemId, count) => putIntoAnyInventory(itemId, count),
+                putItem: (itemId, count) => putIntoAnyInventory(userId, itemId, count),
                 grantCurrency: (currencyId, amount) => economy.grant(userId, currencyId, amount),
             });
             const event = { userId, drops };
@@ -253,17 +296,17 @@ export function createGameContext(options) {
     const trade = createTradeSystem({
         resolveTrade: (itemId) => content.itemById?.(itemId)?.trade,
         wallet: {
-            canAfford: (costs) => (walletCanAfford(walletOf(player.userId), costs) ? null : "insufficient-funds"),
+            canAfford: (costs) => (walletCanAfford(walletOf(activeUserId()), costs) ? null : "insufficient-funds"),
             charge(costs) {
-                const result = walletChargeAll(walletOf(player.userId), costs);
+                const result = walletChargeAll(walletOf(activeUserId()), costs);
                 if (result.status === "ok") {
-                    wallets.set(player.userId, result.state);
+                    wallets.set(activeUserId(), result.state);
                     signal.notify();
                 }
             },
             grant(gains) {
                 for (const [currencyId, amount] of Object.entries(gains)) {
-                    economy.grant(player.userId, currencyId, amount);
+                    economy.grant(activeUserId(), currencyId, amount);
                 }
             },
         },
@@ -271,16 +314,16 @@ export function createGameContext(options) {
             put(inventoryId, itemId, count) {
                 if (layouts[inventoryId] === undefined)
                     return { reason: `unknown inventory "${inventoryId}"` };
-                const result = inventory.put(inventoryId, itemId, count);
+                const result = inventoryFor(activeUserId()).put(inventoryId, itemId, count);
                 return result.status === "ok" ? null : { reason: result.reason };
             },
             take(inventoryId, itemId, count) {
                 if (layouts[inventoryId] === undefined)
                     return { reason: `unknown inventory "${inventoryId}"` };
-                const result = inventory.take(inventoryId, itemId, count);
+                const result = inventoryFor(activeUserId()).take(inventoryId, itemId, count);
                 return result.status === "ok" ? null : { reason: result.reason };
             },
-            count: (inventoryId, itemId) => inventory.count(inventoryId, itemId),
+            count: (inventoryId, itemId) => inventoryFor(activeUserId()).count(inventoryId, itemId),
         },
     });
     function seedUserPool(userId, statId, pool) {
@@ -298,11 +341,9 @@ export function createGameContext(options) {
             },
             grantEconomy: (userId, currencyId, amount) => economy.grant(userId, currencyId, amount),
             grantItem(userId, inventoryId, itemId, count) {
-                if (userId !== player.userId)
-                    return { reason: `unknown user "${userId}"` };
                 if (layouts[inventoryId] === undefined)
                     return { reason: `unknown inventory "${inventoryId}"` };
-                const result = inventory.put(inventoryId, itemId, count);
+                const result = inventoryFor(userId).put(inventoryId, itemId, count);
                 return result.status === "ok" ? null : { reason: result.reason };
             },
             grantUnlock: (userId, unlockId) => unlocks.grant(userId, unlockId),
@@ -312,7 +353,8 @@ export function createGameContext(options) {
     const quest = notifyAfter(rawQuest, ["accept", "abandon", "progress", "turnIn", "grant", "revoke", "hydrate"], signal.notify);
     const loadouts = notifyAfter(createLoadouts({
         inventory: {
-            begin() {
+            begin(userId) {
+                const inventory = inventoryFor(userId);
                 const staged = new Map();
                 return {
                     put(inventoryId, itemId, count, slot) {
@@ -646,7 +688,10 @@ export function createGameContext(options) {
         },
         collidersOf: objectCollidersOf,
     };
-    const store = notifyAfter(createObservableKeyedStore(), ["set", "delete"], signal.notify);
+    const store = notifyAfter(createObservableKeyedStore(), ["set", "delete", "hydrate"], signal.notify);
+    const players = features.players
+        ? notifyAfter(createConnectedPlayers(), ["join", "leave"], signal.notify)
+        : undefined;
     const cardPiles = new Map();
     function pile(id, config) {
         const existing = cardPiles.get(id);
@@ -725,7 +770,63 @@ export function createGameContext(options) {
     }
     const camera = notifyAfter(createCameraDirector(), ["follow", "setCinematic", "setChaseTuning"], signal.notify);
     const input = createInputSnapshot();
-    const motion = createMotionIntents();
+    const motionByUser = new Map();
+    function motionFor(userId) {
+        let queue = motionByUser.get(userId);
+        if (queue === undefined) {
+            queue = createMotionIntents();
+            motionByUser.set(userId, queue);
+        }
+        return queue;
+    }
+    const snapshotModules = [
+        { key: "entities", snapshot: () => entities.snapshot(), hydrate: (data) => entities.hydrate(data) },
+        {
+            key: "stats",
+            snapshot: () => snapshotEntityStats(statsByInstance),
+            hydrate: (data) => hydrateEntityStats(statsByInstance, data),
+        },
+        {
+            key: "store",
+            snapshot: () => store.snapshot(),
+            hydrate: (data) => store.hydrate(data),
+        },
+        { key: "feed", snapshot: () => feed.snapshot(), hydrate: (data) => feed.hydrate(data) },
+        {
+            key: "inventory",
+            snapshot: () => {
+                const byUser = {};
+                for (const [userId, set] of inventoryByUser) {
+                    const states = {};
+                    for (const inventoryId of inventoryIds)
+                        states[inventoryId] = set.state(inventoryId);
+                    byUser[userId] = states;
+                }
+                return byUser;
+            },
+            hydrate: (data) => {
+                for (const [userId, states] of Object.entries(data)) {
+                    const set = inventoryFor(userId);
+                    for (const [inventoryId, state] of Object.entries(states))
+                        set.replaceState(inventoryId, state);
+                }
+            },
+        },
+    ];
+    if (leaderboard) {
+        snapshotModules.push({
+            key: "leaderboard",
+            snapshot: () => leaderboard.snapshot(),
+            hydrate: (data) => leaderboard.hydrate(data),
+        });
+    }
+    if (chat) {
+        snapshotModules.push({
+            key: "chat",
+            snapshot: () => chat.snapshot(),
+            hydrate: (data) => chat.hydrate(data),
+        });
+    }
     const ctx = {
         scene: {
             object: sceneObjects,
@@ -740,6 +841,7 @@ export function createGameContext(options) {
                 spawnPoseOf: entities.spawnPoseOf,
                 resetToSpawn: entities.resetToSpawn,
                 resetAllToSpawn,
+                blackboard: entities.blackboard,
                 stats: entityStats,
                 floatText: emitFloatText,
                 telegraph: fireTelegraph,
@@ -795,8 +897,27 @@ export function createGameContext(options) {
                     signal.notify();
                     return result;
                 },
+                runAs(actorUserId, name, input) {
+                    const previous = actingUserId;
+                    actingUserId = actorUserId;
+                    try {
+                        const result = commandRegistry.run(ctx, name, input);
+                        signal.notify();
+                        return result;
+                    }
+                    finally {
+                        actingUserId = previous;
+                    }
+                },
+                actor: () => actingUserId,
             },
             events,
+            playEntityAnimation: (instanceId, event) => events.emit("entity.animation", { instanceId, event }),
+            audio: {
+                play: (sound, at) => events.emit("audio.play", at === undefined ? { sound } : { sound, at }),
+                music: (theme, transpose) => events.emit("audio.music", transpose === undefined ? { theme } : { theme, transpose }),
+                resume: () => events.emit("audio.resume", {}),
+            },
             feed: {
                 bind: (action) => feed.bind(action, events),
                 push(action, entry) {
@@ -821,21 +942,33 @@ export function createGameContext(options) {
             leaderboard,
             roster,
             store,
-            cards: { pile },
-            turn: { loop },
-            race: { state: raceState },
+            cards: features.cards ? { pile } : undefined,
+            turn: features.turn ? { loop } : undefined,
+            race: features.race ? { state: raceState } : undefined,
+            players,
         },
         player: {
-            userId: player.userId,
+            get userId() {
+                return activeUserId();
+            },
             isNew: player.isNew,
-            inventory,
-            stats: playerStats,
+            get inventory() {
+                return inventoryFor(activeUserId());
+            },
+            inventoryFor,
+            get stats() {
+                return playerStatsFor(activeUserId());
+            },
+            statsFor: playerStatsFor,
             loadout: loadouts,
             applyLoadout: loadouts.applyLoadout,
             movement: pose,
             possession,
             cosmetics,
-            motion,
+            get motion() {
+                return motionFor(activeUserId());
+            },
+            motionFor,
         },
         item: {
             use: {
@@ -855,6 +988,11 @@ export function createGameContext(options) {
         input,
         subscribe: signal.subscribe,
         version: signal.version,
+        snapshot: () => composeWorldSnapshot(snapshotModules),
+        hydrate(snapshot) {
+            applyWorldSnapshot(snapshotModules, snapshot);
+            signal.notify();
+        },
     };
     return ctx;
 }

package/dist/runtime/hostedGameRunner.d.ts

@@ -0,0 +1,49 @@
+import type { CommandResult } from "../commands/commandRegistry.js";
+import type { GameDefinition, LoopPlayer } from "../game/defineGame.js";
+import type { ModelAssetRef } from "../scene/assetCatalog.js";
+import { type GameContext, type GameContextContent } from "./gameContext.js";
+import { type InputFrame } from "./inputSnapshot.js";
+import { type WorldDiff } from "./worldReplication.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+export type { InputFrame };
+/** Reserved command name the authoritative host intercepts on the existing `runCommand` transport to route a client's {@link InputFrame} to `session.input`, so per-tick input needs no separate wire. */
+export declare const INPUT_COMMAND = "engine.input";
+/** Config for {@link createHostedGameRunner}: the game definition, its content lookup, and an optional host identity. */
+export interface HostedGameRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> {
+    definition: GameDefinition<TAssetRef, TMultiplayer>;
+    content: GameContextContent;
+    /** The world's own authoritative identity (`ctx.player` server-side); real players join as members. */
+    host?: LoopPlayer;
+    now?: () => number;
+    /**
+     * Rehydrate a persisted world instead of booting a fresh one — for stateless hosts (Convex) that reconstruct
+     * the runner each invocation. `onInit` still runs (so commands and systems it registers exist), then this
+     * snapshot overlays the world state it seeded. Omit for a long-lived stateful host (ws) that keeps one runner.
+     */
+    restore?: WorldSnapshot;
+}
+/**
+ * The GameContext-loop equivalent of the pure-reducer `createGameHost`: one authoritative `createGameContext`
+ * per world, driven server-side. `onInit` runs once at construction; `onNewPlayer`/`onPlayerLeave` fire per
+ * join/leave; `tick` advances `onTick` then commits a revision. Clients pull a full {@link WorldSnapshot}
+ * baseline once, then per-tick {@link WorldDiff}s from their last revision. Games ship only normal GameContext
+ * code — the runner adds no per-game surface.
+ */
+export interface HostedGameRunner {
+    join(userId: string, isNew: boolean): void;
+    /** Re-attach an already-joined member on a reconstructed runner — restores membership and `ctx.game.players` without re-firing `onNewPlayer`. Stateless hosts call it once per persisted member after `restore`. */
+    resume(userId: string): void;
+    leave(userId: string): void;
+    /** Record a client's latest input frame — stashed for {@link heldInput} and mirrored onto `ctx.game.players` so the movement seam reads each player's intent in `onTick`. */
+    input(userId: string, frame: InputFrame): void;
+    heldInput(userId: string): InputFrame | null;
+    command(userId: string, name: string, input: unknown): CommandResult<GameContext>;
+    tick(dt: number): number;
+    diff(sinceRevision: number): WorldDiff;
+    revision(): number;
+    snapshot(): WorldSnapshot;
+    members(): readonly string[];
+    context(): GameContext;
+}
+/** Build a {@link HostedGameRunner} — one authoritative GameContext world driven server-side from the game's own loop. */
+export declare function createHostedGameRunner<TAssetRef extends ModelAssetRef, TMultiplayer>(options: HostedGameRunnerOptions<TAssetRef, TMultiplayer>): HostedGameRunner;

package/dist/runtime/hostedGameRunner.js

@@ -0,0 +1,62 @@
+import { createGameContext } from "./gameContext.js";
+import {} from "./inputSnapshot.js";
+import { createWorldReplicator } from "./worldReplication.js";
+/** Reserved command name the authoritative host intercepts on the existing `runCommand` transport to route a client's {@link InputFrame} to `session.input`, so per-tick input needs no separate wire. */
+export const INPUT_COMMAND = "engine.input";
+/** Build a {@link HostedGameRunner} — one authoritative GameContext world driven server-side from the game's own loop. */
+export function createHostedGameRunner(options) {
+    const { definition, content, host, now, restore } = options;
+    const ctx = createGameContext({
+        definition,
+        content,
+        player: host ?? { userId: "host", isNew: true },
+        ...(now === undefined ? {} : { now }),
+    });
+    const loop = definition.loop ?? {};
+    const replicator = createWorldReplicator(() => ctx.snapshot());
+    const members = new Map();
+    const inputs = new Map();
+    loop.onInit?.(ctx);
+    if (restore !== undefined)
+        ctx.hydrate(restore);
+    return {
+        join(userId, isNew) {
+            const player = { userId, isNew };
+            members.set(userId, player);
+            ctx.game.players?.join(userId, isNew);
+            loop.onNewPlayer?.(ctx, player);
+        },
+        resume(userId) {
+            members.set(userId, { userId, isNew: false });
+            ctx.game.players?.join(userId, false);
+        },
+        leave(userId) {
+            const player = members.get(userId);
+            if (player === undefined)
+                return;
+            members.delete(userId);
+            inputs.delete(userId);
+            loop.onPlayerLeave?.(ctx, player);
+            ctx.game.players?.leave(userId);
+        },
+        input(userId, frame) {
+            inputs.set(userId, frame);
+            ctx.game.players?.setInput(userId, frame);
+        },
+        heldInput(userId) {
+            return inputs.get(userId) ?? null;
+        },
+        command(userId, name, input) {
+            return ctx.game.commands.runAs(userId, name, input);
+        },
+        tick(dt) {
+            loop.onTick?.(ctx, dt);
+            return replicator.commit();
+        },
+        diff: (sinceRevision) => replicator.diff(sinceRevision),
+        revision: () => replicator.revision(),
+        snapshot: () => ctx.snapshot(),
+        members: () => Array.from(members.keys()),
+        context: () => ctx,
+    };
+}