@jgengine/core 0.10.0 → 0.11.0

package/dist/runtime/descriptors/features.d.ts

@@ -0,0 +1,74 @@
+import type { CardPile, CardPileConfig } from "../../cards/cardPile.js";
+import type { CommandRegistry } from "../../commands/commandRegistry.js";
+import { type WalletState } from "../../economy/wallet.js";
+import type { GameFeatures } from "../../game/defineGame.js";
+import type { GameEvents } from "../../game/events.js";
+import { type Social } from "../../game/social.js";
+import type { InventoryLayout, InventorySet } from "../../inventory/inventoryModel.js";
+import type { StatValueMap } from "../../scene/entityStats.js";
+import type { EntityStore } from "../../scene/entityStore.js";
+import type { SpatialApi } from "../../scene/spatial.js";
+import type { ObservableKeyedStore } from "../../store/observableKeyedStore.js";
+import type { SnapshotModule } from "../worldSnapshot.js";
+import type { TurnLoop, TurnLoopConfig } from "../../turn/turnLoop.js";
+import type { RaceState, RaceStateConfig } from "../../game/race.js";
+import type { GameContext, GameContextContent, GameContextEconomy } from "../gameContext.js";
+/**
+ * Shared wiring every optional-feature descriptor draws from — the live core subsystems (entities,
+ * spatial, economy, inventory) plus reactive plumbing (`signalNotify`) and a `feature` reader for the
+ * few features that reference another (quest reads unlocks). Handed to each {@link FeatureDescriptor}'s
+ * `create` so a new opt-in subsystem plugs into one registration, never a new `features.x ?` branch.
+ * @internal
+ */
+export interface FeatureDeps {
+    features: GameFeatures;
+    signalNotify: () => void;
+    events: GameEvents;
+    now: () => number;
+    entities: EntityStore;
+    spatial: SpatialApi;
+    store: ObservableKeyedStore<unknown>;
+    commandRegistry: CommandRegistry<GameContext>;
+    economy: GameContextEconomy;
+    content: GameContextContent;
+    activeUserId: () => string;
+    walletOf: (userId: string) => WalletState;
+    setWallet: (userId: string, state: WalletState) => void;
+    layouts: Record<string, InventoryLayout>;
+    inventoryFor: (userId: string) => InventorySet<string>;
+    ensureInstanceStats: (instanceId: string) => StatValueMap;
+    seedUserPool: (userId: string, statId: string, pool: {
+        current: number;
+        max?: number;
+        min?: number;
+    }) => void;
+    sharedSocial: () => Social;
+    pile: (id: string, config?: CardPileConfig) => CardPile;
+    loop: (id: string, config?: TurnLoopConfig) => TurnLoop;
+    cardPiles: ReadonlyMap<string, CardPile>;
+    turnLoops: ReadonlyMap<string, TurnLoop>;
+    raceState: (id: string, config?: RaceStateConfig) => RaceState;
+    feature: <T>(key: keyof GameFeatures) => T | undefined;
+}
+/** @internal What a descriptor produces: the `ctx`-facing value plus its optional replication/save modules. */
+export interface FeatureBuild {
+    value: unknown;
+    /** Registered into the host→client replication set when present (`ctx.snapshot`/`ctx.hydrate`). */
+    replicate?: SnapshotModule;
+    /** Registered into the whole-world save-only set when present (`ctx.game.save`). */
+    save?: SnapshotModule;
+}
+/**
+ * One opt-in subsystem expressed as data: which `features` flag turns it on, how it wires itself from
+ * {@link FeatureDeps}, and whether it replicates or persists. `createGameContext` iterates the
+ * descriptor list instead of hand-wiring each `features.x ? create : undefined` branch — the seam a
+ * new feature extends through.
+ * @internal
+ */
+export interface FeatureDescriptor {
+    readonly key: keyof GameFeatures;
+    enabled(features: GameFeatures): boolean;
+    create(deps: FeatureDeps): FeatureBuild;
+}
+/** @internal */
+export declare const featureDescriptors: readonly FeatureDescriptor[];

package/dist/runtime/descriptors/features.js

@@ -0,0 +1,281 @@
+import { canAfford as walletCanAfford, chargeAll as walletChargeAll, } from "../../economy/wallet.js";
+import { createCosmetics } from "../../game/cosmetics.js";
+import { createLeaderboard } from "../../game/leaderboard.js";
+import { createGameDialogue } from "../../game/dialogue.js";
+import { createQuestJournal } from "../../game/quest.js";
+import { createChat } from "../../game/chat.js";
+import {} from "../../game/social.js";
+import { createTradeSystem } from "../../game/trade.js";
+import { createUnlocks } from "../../game/unlocks.js";
+import { createRoster } from "../../scene/roster.js";
+import { createConnectedPlayers } from "../../game/connectedPlayers.js";
+import { notifyAfter } from "../../store/changeSignal.js";
+/** @internal */
+export const featureDescriptors = [
+    {
+        key: "unlocks",
+        enabled: (f) => f.unlocks === true,
+        create(d) {
+            const unlocks = notifyAfter(createUnlocks(), ["grant", "hydrate"], d.signalNotify);
+            return {
+                value: unlocks,
+                save: {
+                    key: "unlocks",
+                    snapshot: () => unlocks.snapshotAll(),
+                    hydrate: (data) => unlocks.hydrateAll(data),
+                },
+            };
+        },
+    },
+    {
+        key: "social",
+        enabled: (f) => f.social === true,
+        create(d) {
+            const raw = d.sharedSocial();
+            const social = {
+                friends: notifyAfter(raw.friends, ["request", "accept", "decline", "remove", "block", "hydrate"], d.signalNotify),
+                party: notifyAfter(raw.party, ["invite", "accept", "decline", "kick", "leave", "promote"], d.signalNotify),
+                presence: raw.presence,
+                emotes: raw.emotes,
+                worldInvites: notifyAfter(raw.worldInvites, ["invite", "accept", "decline"], d.signalNotify),
+                snapshot: raw.snapshot,
+                hydrate: (data) => {
+                    raw.hydrate(data);
+                    d.signalNotify();
+                },
+            };
+            return {
+                value: social,
+                replicate: {
+                    key: "social",
+                    snapshot: () => social.snapshot(),
+                    hydrate: (data) => social.hydrate(data),
+                },
+            };
+        },
+    },
+    {
+        key: "chat",
+        enabled: (f) => f.chat === true,
+        create(d) {
+            const raw = d.sharedSocial();
+            const chat = notifyAfter(createChat({
+                events: d.events,
+                now: d.now,
+                party: raw.party,
+                proximity: {
+                    entities: { get: (id) => d.entities.get(id) },
+                    spatial: { inRadius: (center, radius, filter) => d.spatial.inRadius(center, radius, filter) },
+                },
+                blockedBy: (userId) => raw.friends.snapshot(userId).blocked,
+            }), ["register", "send", "whisper", "hydrate"], d.signalNotify);
+            return {
+                value: chat,
+                replicate: {
+                    key: "chat",
+                    snapshot: () => chat.snapshot(),
+                    hydrate: (data) => chat.hydrate(data),
+                },
+            };
+        },
+    },
+    {
+        key: "leaderboard",
+        enabled: (f) => f.leaderboard === true,
+        create(d) {
+            const leaderboard = notifyAfter(createLeaderboard(), ["increment", "hydrate"], d.signalNotify);
+            return {
+                value: leaderboard,
+                replicate: {
+                    key: "leaderboard",
+                    snapshot: () => leaderboard.snapshot(),
+                    hydrate: (data) => leaderboard.hydrate(data),
+                },
+            };
+        },
+    },
+    {
+        key: "roster",
+        enabled: (f) => f.roster === true,
+        create(d) {
+            const roster = notifyAfter(createRoster({ now: d.now }), ["capture", "release", "setEquipped", "hydrate"], d.signalNotify);
+            return {
+                value: roster,
+                save: {
+                    key: "roster",
+                    snapshot: () => roster.snapshotAll(),
+                    hydrate: (data) => roster.hydrateAll(data),
+                },
+            };
+        },
+    },
+    {
+        key: "cosmetics",
+        enabled: (f) => f.cosmetics === true,
+        create(d) {
+            const cosmetics = notifyAfter(createCosmetics({ events: d.events }), ["apply", "equip", "hydrate"], d.signalNotify);
+            return {
+                value: cosmetics,
+                save: {
+                    key: "cosmetics",
+                    snapshot: () => cosmetics.snapshotAll(),
+                    hydrate: (data) => cosmetics.hydrateAll(data),
+                },
+            };
+        },
+    },
+    {
+        key: "trade",
+        enabled: (f) => f.trade === true,
+        create(d) {
+            return {
+                value: createTradeSystem({
+                    resolveTrade: (itemId) => d.content.itemById?.(itemId)?.trade,
+                    wallet: {
+                        canAfford: (costs) => walletCanAfford(d.walletOf(d.activeUserId()), costs) ? null : "insufficient-funds",
+                        charge(costs) {
+                            const result = walletChargeAll(d.walletOf(d.activeUserId()), costs);
+                            if (result.status === "ok") {
+                                d.setWallet(d.activeUserId(), result.state);
+                                d.signalNotify();
+                            }
+                        },
+                        grant(gains) {
+                            for (const [currencyId, amount] of Object.entries(gains)) {
+                                d.economy.grant(d.activeUserId(), currencyId, amount);
+                            }
+                        },
+                    },
+                    inventory: {
+                        put(inventoryId, itemId, count) {
+                            if (d.layouts[inventoryId] === undefined)
+                                return { reason: `unknown inventory "${inventoryId}"` };
+                            const result = d.inventoryFor(d.activeUserId()).put(inventoryId, itemId, count);
+                            return result.status === "ok" ? null : { reason: result.reason };
+                        },
+                        take(inventoryId, itemId, count) {
+                            if (d.layouts[inventoryId] === undefined)
+                                return { reason: `unknown inventory "${inventoryId}"` };
+                            const result = d.inventoryFor(d.activeUserId()).take(inventoryId, itemId, count);
+                            return result.status === "ok" ? null : { reason: result.reason };
+                        },
+                        count: (inventoryId, itemId) => d.inventoryFor(d.activeUserId()).count(inventoryId, itemId),
+                    },
+                }),
+            };
+        },
+    },
+    {
+        key: "quest",
+        enabled: (f) => f.quest === true,
+        create(d) {
+            const quest = notifyAfter(createQuestJournal({
+                events: d.events,
+                rewards: {
+                    grantXp(userId, amount) {
+                        const existing = d.ensureInstanceStats(userId)["xp"];
+                        const current = (existing?.current ?? 0) + amount;
+                        d.seedUserPool(userId, "xp", { current, max: Math.max(existing?.max ?? 0, current) });
+                    },
+                    grantEconomy: (userId, currencyId, amount) => d.economy.grant(userId, currencyId, amount),
+                    grantItem(userId, inventoryId, itemId, count) {
+                        if (d.layouts[inventoryId] === undefined)
+                            return { reason: `unknown inventory "${inventoryId}"` };
+                        const result = d.inventoryFor(userId).put(inventoryId, itemId, count);
+                        return result.status === "ok" ? null : { reason: result.reason };
+                    },
+                    grantUnlock: (userId, unlockId) => d.feature("unlocks")?.grant(userId, unlockId),
+                },
+                hasUnlock: (userId, id) => d.feature("unlocks")?.has(userId, id) ?? false,
+            }), ["accept", "abandon", "progress", "turnIn", "grant", "revoke", "hydrate"], d.signalNotify);
+            return {
+                value: quest,
+                save: {
+                    key: "quest",
+                    snapshot: () => quest.snapshotAll(),
+                    hydrate: (data) => quest.hydrateAll(data),
+                },
+            };
+        },
+    },
+    {
+        key: "dialogue",
+        enabled: (f) => f.dialogue === true,
+        create(d) {
+            const dialogue = createGameDialogue(d.store);
+            d.commandRegistry.define("dialogue.open", {
+                apply(state, input) {
+                    const id = input.id;
+                    if (id !== undefined)
+                        state.game.dialogue?.open(id);
+                },
+            });
+            d.commandRegistry.define("dialogue.close", {
+                apply(state) {
+                    state.game.dialogue?.close();
+                },
+            });
+            return { value: dialogue };
+        },
+    },
+    {
+        key: "players",
+        enabled: (f) => f.players === true,
+        create(d) {
+            return { value: notifyAfter(createConnectedPlayers(), ["join", "leave"], d.signalNotify) };
+        },
+    },
+    {
+        key: "cards",
+        enabled: (f) => f.cards === true,
+        create(d) {
+            return {
+                value: { pile: d.pile },
+                save: {
+                    key: "cards",
+                    snapshot: () => {
+                        const out = {};
+                        for (const [id, cardPile] of d.cardPiles)
+                            out[id] = cardPile.state();
+                        return out;
+                    },
+                    hydrate: (data) => {
+                        for (const [id, state] of Object.entries(data)) {
+                            d.cardPiles.get(id)?.reset(state);
+                        }
+                    },
+                },
+            };
+        },
+    },
+    {
+        key: "turn",
+        enabled: (f) => f.turn === true,
+        create(d) {
+            return {
+                value: { loop: d.loop },
+                save: {
+                    key: "turn",
+                    snapshot: () => {
+                        const out = {};
+                        for (const [id, turnLoop] of d.turnLoops)
+                            out[id] = turnLoop.capture();
+                        return out;
+                    },
+                    hydrate: (data) => {
+                        for (const [id, state] of Object.entries(data)) {
+                            d.turnLoops.get(id)?.restore(state);
+                        }
+                    },
+                },
+            };
+        },
+    },
+    {
+        key: "race",
+        enabled: (f) => f.race === true,
+        create(d) {
+            return { value: { state: d.raceState } };
+        },
+    },
+];

package/dist/runtime/gameContext.d.ts

@@ -2,17 +2,20 @@ import { type CardPile, type CardPileConfig } from "../cards/cardPile.js";
 import { type OnDeathSpec } from "../combat/death.js";
 import { type EffectInput, type EffectResult, type EffectVia, type ReceiveMap, type SingleTargetEffectInput } from "../combat/effects.js";
 import { type ProjectileSystem } from "../combat/projectiles.js";
-import { type HitReaction, type HitReactionConfig } from "../combat/hitReaction.js";
+import { type HitReaction, type HitReactionConfig, type ImpactPresetName } from "../combat/hitReaction.js";
 import { type TelegraphShape } from "../combat/telegraph.js";
 import { type CommandDefinition, type 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, type GameEvents } from "../game/events.js";
+import { type GameEventMap, type GameEvents, type 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, type LootTableDef } from "../game/lootTable.js";
+import { type GameDialogue } from "../game/dialogue.js";
 import { type QuestJournal } from "../game/quest.js";
 import { type WorldItemRecord, type WorldItemSpawnInput } from "../game/worldItem.js";
 import { type Chat } from "../game/chat.js";
@@ -26,22 +29,26 @@ import { type ItemUseHandler, type ItemUseInput, type ItemUseRejection, type Ite
 import { type WeaponStats } from "../item/weapon.js";
 import { type PoseAllowedStates, type 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, type StatCatalog } from "../scene/entityStats.js";
-import type { EntityBlackboard, EntityPose, EntityPosition, EntityStore, SceneEntity, SpawnOptions, SpawnPose } from "../scene/entityStore.js";
+import { type EntityBlackboard, type EntityPose, type EntityPosition, type EntityStore, type SceneEntity, type SpawnOptions, type SpawnPose } from "../scene/entityStore.js";
 import { type Forms } from "../scene/form.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 SelectionSet } from "../scene/selection.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 MoveTowardOptions, 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 SnapshotModule, type SnapshotViewer, type WorldSnapshot } from "./worldSnapshot.js";
+import { type ReplicationPolicy } from "./worldProjection.js";
+import { type RuntimeSave, type RuntimeSaveOptions } from "./runtimeSave.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";
@@ -70,6 +77,8 @@ export interface GameContextEntityEntry {
     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;
@@ -96,6 +105,14 @@ export interface GameContextOptions<TAssetRef extends ModelAssetRef = ModelAsset
     };
     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;
 }
 export interface SceneObjectContext extends ObjectStore {
     catalog(instanceId: string): GameContextObjectEntry | null;
@@ -103,6 +120,15 @@ export interface SceneObjectContext extends ObjectStore {
     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;
@@ -115,6 +141,15 @@ export interface FloatTextInput {
     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;
@@ -133,9 +168,14 @@ export interface TelegraphInput {
 export interface HitReactionInput {
     from: string;
     to: string;
-    config: HitReactionConfig;
+    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;
@@ -144,12 +184,22 @@ export interface SceneEntityContext {
     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;
@@ -166,11 +216,29 @@ export interface SceneEntityContext {
     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";
@@ -209,9 +277,12 @@ export interface GameContextLoot {
 export interface GameContextEconomy {
     balance(userId: string, currencyId: string): number;
     grant(userId: string, currencyId: string, amount: number): void;
-    charge(userId: string, currencyId: string, amount: number): {
+    /** `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;
@@ -259,13 +330,18 @@ export interface GameContext {
         playEntityAnimation(instanceId: string, event: string): void;
         feed: GameContextFeed;
         loot: GameContextLoot;
-        trade: TradeSystem;
-        quest: QuestJournal;
+        /** 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;
-        unlocks: Unlocks;
+        /** 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;
@@ -281,6 +357,18 @@ export interface GameContext {
         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. */
@@ -300,7 +388,8 @@ export interface GameContext {
         } | null;
         movement: PoseState;
         possession: Possession;
-        cosmetics: Cosmetics;
+        /** 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. */
@@ -317,13 +406,25 @@ export interface GameContext {
     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.
+     * 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(): WorldSnapshot;
+    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;
 }
 export declare function createGameContext<TAssetRef extends ModelAssetRef, TMultiplayer>(options: GameContextOptions<TAssetRef, TMultiplayer>): GameContext;