@rpgm-tools/neo-angband-core 0.10.0

package/dist/session/game.d.ts

@@ -0,0 +1,257 @@
+/**
+ * New-game assembly: pack in, a live GameState the turn loop can run.
+ *
+ * bootLevel (boot.ts) produces the world and the spot the player would
+ * occupy; this adds the missing half - birthing a player character and
+ * wiring it, the generated monsters, and the action registry into the
+ * GameState the loop operates on. It is the smallest "start a playable
+ * game" entry point and, like the rest of the boot seam, is headless and
+ * takes already-parsed pack JSON so it serves tests and any front end.
+ *
+ * It composes public domain APIs only and adds no rules: generatePlayer
+ * (birth), calcBonuses (derived combat/defence), and the context helpers
+ * that place the player and register the monsters.
+ *
+ * Race and class default to Human Warrior; pass raceName/className to
+ * override. Decision 6.2 stream order matches C player-birth.c:1269-1292 +
+ * ui-game.c:757-760: store_reset, seed_randart, seed_flavor (back-to-back),
+ * then prepare_next_level generation.
+ */
+import type { PlayerPackRecords, PlayerRegistry } from "../player/bind.js";
+import type { GameState } from "../game/context.js";
+import { EffectRegistry } from "../effects/interpreter.js";
+import type { ItemRequest } from "../game/effect-item.js";
+import type { WizardDeps } from "../game/wizard.js";
+import type { Store } from "../store/store.js";
+import type { BuyResult, SellResult } from "../store/transact.js";
+import { FlavorKnowledge, EverseenKnowledge } from "../obj/knowledge.js";
+import type { GameObject } from "../obj/object.js";
+import type { ActionRegistry } from "../game/player-turn.js";
+import type { BootedLevel, BootLevelOptions, CorePack } from "./boot.js";
+import { OptionState } from "../player/options.js";
+import type { OptionName } from "../player/options.js";
+import type { SavedGame } from "./save.js";
+import type { ModBag, OrphanStore, SaveManifest } from "../mod/save-blocks.js";
+/**
+ * The getItem seam body (cmd_get_item's "tgtitem" fast path, cmd-core.c L1060):
+ * resolve the shell's preset target (a gear handle or a floor-pile index) to a
+ * live object. If it resolves and passes the request's tester, consume the
+ * one-shot preset and return it; otherwise record the unfulfilled request and
+ * return null - the faithful cancel/abort (C falls through a filter-failing
+ * preset to the blocking prompt, which the port cannot do mid-turn). Draws no
+ * RNG.
+ */
+export declare function resolveTargetItem(state: GameState, req: ItemRequest): GameObject | null;
+/**
+ * The chooseCurse seam body (get_curse, effect-handler-general.c): return the
+ * shell's preset curse index when it is one of the removable curses, else the
+ * first removable one (upstream get_curse's default highlight), else null. No
+ * RNG - get_curse is a pure menu.
+ */
+export declare function resolveTargetCurse(state: GameState, removable: readonly number[]): number | null;
+/** A pack that also carries the player-domain records (races, classes, ...). */
+export interface GamePack extends CorePack {
+    player: PlayerPackRecords;
+}
+/** Options for starting a new game. */
+export interface StartGameOptions extends BootLevelOptions {
+    /** Race name (case-insensitive). Default "Human". */
+    raceName?: string;
+    /** Class name (case-insensitive). Default "Warrior". */
+    className?: string;
+    /**
+     * Stat roller method (ui-birth.c BIRTH_ROLLER_CHOICE). "point" applies the
+     * point-based allocation in `birthStats` (no stat RNG); "roller" (the
+     * default when omitted) runs the classic get_stats roller.
+     */
+    roller?: "point" | "roller";
+    /**
+     * Point-based allocated base stats (STAT_MAX values), used only when
+     * `roller` is "point". Threaded into generatePlayer so the character is born
+     * with these stats and the stat stage draws no RNG.
+     */
+    birthStats?: readonly number[];
+    /**
+     * A standard-roller result the shell's roller UI rolled and the player
+     * accepted (do_cmd_roll_stats, player-birth.c:1159-1193): the STAT_MAX natural
+     * stat values, applied VERBATIM by generatePlayer (no point-buy clamp, no
+     * stat RNG). Used when `roller` is "roller"/omitted; wins over `birthStats`.
+     */
+    rolledStats?: readonly number[];
+    /**
+     * An edited character background the shell's history stage produced
+     * (do_cmd_choose_history, player-birth.c:1219-1230). Replaces the get_history
+     * text on the player; the history walk still runs so the RNG order is intact.
+     */
+    history?: string;
+    /**
+     * Birth / interface option choices, applied over the table defaults at
+     * character creation (option.c options_init_defaults). Birth options become
+     * the immutable birth snapshot; the rest seed the live option store.
+     */
+    optionOverrides?: Partial<Record<OptionName, boolean>>;
+    /** op_ptr->hitpoint_warn (0..9). Default 3 (DEFAULT_HITPOINT_WARN). */
+    hitpointWarn?: number;
+    /**
+     * The player's per-patch choices, resolved by the host from each enabled mod's
+     * manifest `rules`. Recorded on GameState.modRules and saved, so a save says
+     * which patches a character was played with. OPAQUE to core - see the field's
+     * note in game/context.ts.
+     */
+    modRules?: Readonly<Record<string, boolean>>;
+    /**
+     * The behaviour every enabled mod supplies, already folded into one object by
+     * the host (mod/hooks.ts composeModHooks). Absent - the case with no mod
+     * enabled - leaves core byte-identical to faithful 4.2.6.
+     */
+    modHooks?: import("../mod/hooks.js").ModHooks;
+    /**
+     * The host's own FOV refresh, installed BEFORE the initial level-entry flood.
+     *
+     * Core installs a default when this is absent, so a host needs this only when it
+     * wants its own - the web shell routes the view's events at its sound bus. It is
+     * an option rather than a post-boot assignment because the level-entry flood runs
+     * inside startGame: a seam installed afterwards misses it, which is how the web
+     * build came to do its first view build with `onlyPartial` already cleared.
+     */
+    updateFov?: (state: GameState) => void;
+}
+/** A started game: the loop's state and registry, plus what a renderer needs. */
+export interface StartedGame {
+    state: GameState;
+    registry: ActionRegistry;
+    /**
+     * The effect interpreter (null on a worldless boot). Surfaced so a host can
+     * build the trusted-mod registry facade (mod/registry-host.ts, W2.2) for
+     * effect-handler overrides. The room registry lives on booted.registries.rooms
+     * and the command seam is `registry` above.
+     */
+    effects: EffectRegistry | null;
+    /** The generated world (features, placed objects, registries) for rendering. */
+    booted: BootedLevel;
+    players: PlayerRegistry;
+    /** Per-game flavor knowledge (aware/tried), for the save format. */
+    flavor: FlavorKnowledge;
+    /**
+     * Per-game everseen knowledge (kind/ego "ever seen"), for the object + ego
+     * knowledge browsers and the save format.
+     */
+    everseen: EverseenKnowledge;
+    /** seed_flavor: the seed flavor_init used, persisted so a reload matches. */
+    seedFlavor: number;
+    /**
+     * The mod manifest (save-blocks.ts, P7.2): the pack set + resolved load order
+     * + core-owned determinism mode. A core-only game carries coreOnlyManifest();
+     * a loaded game carries the manifest the save was written with.
+     */
+    manifest: SaveManifest;
+    /** Per-mod private save bags (mod:<id>), round-tripped verbatim. */
+    mods: Record<string, ModBag>;
+    /**
+     * Quarantined entities (missing/shadowed packs), preserved across save/load
+     * so reinstalling a pack rehydrates its content. Empty for a core-only game.
+     */
+    orphans: OrphanStore;
+    /** decision-8: whether the one-time orphan keep/purge prompt has been shown. */
+    orphansAcknowledged: boolean;
+    /** The player option store (option.c), persisted in the save. */
+    options: OptionState;
+    /**
+     * randart_seed (obj-randart.c): the seed do_randart used when birth_randarts
+     * is on, persisted so a reload reproduces the same random artifact set. 0
+     * when birth_randarts is off (no randart set was generated).
+     */
+    randartSeed: number;
+    /**
+     * dungeon_change_level + prepare_next_level: generate a fresh level at
+     * `depth` from the game's own RNG stream and repopulate the state in
+     * place (same GameState object, so installed commands keep working).
+     * The caller clears state.generateLevel and refreshes FOV/render.
+     */
+    changeLevel: (depth: number) => void;
+    /**
+     * The wizard/debug engine bundles (WP-14 / gap 15.2): effect interpreter,
+     * ExpDeps, TrapDeps, live MonPlaceDeps and MakeDeps for the interactive debug
+     * command menu. Assembled inside wireGame (single source of truth).
+     */
+    wizardBundles: WizardBundle;
+    /**
+     * do_cmd_buy: purchase `amt` of a store-stock object into the player's pack
+     * (store/transact.ts), with the deps and knowledge closed over. Town only.
+     */
+    buy: (store: Store, obj: GameObject, amt: number) => BuyResult;
+    /**
+     * do_cmd_sell: sell `amt` of the gear object at `handle` to the store. The
+     * handle may name a pack, equipped, or quiver object (ui-store.c L487 get_mode
+     * USE_INVEN|USE_EQUIP|USE_QUIVER); a stuck equipped item is refused.
+     */
+    sell: (store: Store, handle: number, amt: number) => SellResult;
+    /**
+     * do_cmd_sell for a FLOOR object (ui-store.c L487 USE_FLOOR): sell `amt` of the
+     * floor pile object `obj` (at the player's grid) to the store. Detached via
+     * floor_object_for_use rather than a gear handle.
+     */
+    sellFloor: (store: Store, obj: GameObject, amt: number) => SellResult;
+    /**
+     * price_item for display: the per-item price the player pays (storeBuying
+     * false) or is offered (storeBuying true).
+     */
+    price: (store: Store, obj: GameObject, storeBuying: boolean, qty: number) => number;
+    /**
+     * store_will_buy (store.c L524): whether `store` would purchase `obj`, for the
+     * sell picker's pre-filter (ui-store.c store_sell get_item tester). Uses the
+     * same knowledge the sell transaction does so the picker and the sale agree.
+     */
+    willBuy: (store: Store, obj: GameObject) => boolean;
+}
+/**
+ * The wizard/debug engine bundles (WP-14 / gap 15.2): the effect interpreter,
+ * ExpDeps, TrapDeps, the live MonPlaceDeps and MakeDeps that the interactive
+ * wizard commands (game/wizard.ts) dispatch through. Assembled once inside
+ * wireGame - the single source of truth for this wiring - and surfaced on
+ * StartedGame so the web debug menu (packages/web wizard.ts) never re-derives
+ * them. A subset of WizardDeps: the shell adds the wizard flag, msg, the
+ * markNoscore hook and the pure registry data (races/artifacts/curses).
+ */
+export type WizardBundle = Pick<WizardDeps, "makeDeps" | "expDeps" | "effect" | "trapDeps" | "monPlace">;
+/**
+ * Assemble a runnable GameState from a pack: generate a level, birth a
+ * character, derive its bonuses, and register the placed monsters. The
+ * caller wires state.nextCommand (input) and state.updateFov (FOV) and then
+ * drives runGameLoop; on LOOP_STATUS.LEVEL_CHANGE it calls
+ * game.changeLevel(state.targetDepth) and clears state.generateLevel.
+ */
+export declare function startGame(pack: GamePack, opts?: StartGameOptions): StartedGame;
+/** Serialize a started game into the JSON save format (decision 9). */
+export declare function saveGame(game: StartedGame): SavedGame;
+/**
+ * Rebuild a running game from a save: bind the pack, restore every entity
+ * store and the RNG stream (decision 22: reloading resumes the exact
+ * stream, the anti-save-scum posture), rewire the commands, and derive the
+ * combat state from the restored player and gear.
+ */
+/** Options for loadGame (client settings not stored in the savefile). */
+export interface LoadGameOptions {
+    /**
+     * The effective "mod rule" flags to seed GameState.modRules with, recomputed
+     * by the host from the enabled mods' manifest `rules` and the player's saved
+     * choices (the same resolution startGame uses). A client setting, not part of
+     * the save; absent/empty = faithful 4.2.6.
+     */
+    modRules?: Readonly<Record<string, boolean>>;
+    /**
+     * The composed behaviour of every enabled mod (mod/hooks.ts). A client setting
+     * like the flags above; absent = faithful 4.2.6.
+     */
+    modHooks?: import("../mod/hooks.js").ModHooks;
+    /**
+     * arg_wizard (savefile.c:631 savefile_load's cheat_death parameter): the game
+     * was launched in wizard mode. Loading a DEAD character this way resurrects it
+     * (savefile.c:647-651) and marks it NOSCORE_WIZARD so it stays off the score
+     * table. A client/launch setting, not part of the save. The web wizard-mode
+     * entry (WP-14) passes this; a normal load leaves it false.
+     */
+    wizard?: boolean;
+}
+export declare function loadGame(pack: GamePack, saveIn: SavedGame, present?: ReadonlySet<string>, opts?: LoadGameOptions): StartedGame;
+//# sourceMappingURL=game.d.ts.map

package/dist/session/game.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game.d.ts","sourceRoot":"","sources":["../../src/session/game.ts"],"names":[],"mappings":"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"}