@jgengine/core 0.9.0 → 0.11.0

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,20 +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 { 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 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 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";
@@ -68,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;
@@ -94,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;
@@ -101,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;
@@ -113,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;
@@ -131,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;
@@ -142,11 +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;
@@ -163,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";
@@ -189,6 +260,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;
@@ -202,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;
@@ -228,6 +306,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,36 +325,75 @@ 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;
-        unlocks: Unlocks;
+        /** 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;
-        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;
+        /** 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;
-        cosmetics: Cosmetics;
-        /** Vertical-motion seam into the shell-owned FrameDriver (#162.4); see `MotionIntents`. */
+        /** 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;
@@ -282,5 +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. 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;
 }
 export declare function createGameContext<TAssetRef extends ModelAssetRef, TMultiplayer>(options: GameContextOptions<TAssetRef, TMultiplayer>): GameContext;