@rpgm-tools/neo-angband-core 0.10.0

package/dist/game/trap.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Live traps, ported from reference/src/trap.c (Angband 4.2.6): trap
+ * instances on squares (state.traps, the same GameState seam as floor
+ * piles and monster groups), placement (pick_trap / place_trap), reveal,
+ * activation (hit_trap running the kind's effect chains through the
+ * effect interpreter with a trap source), disable timeouts, door locks
+ * (the "door lock" trap kind), and the disarm command with the cmd-cave.c
+ * skill math.
+ *
+ * Knowledge simplifications (with #24): traps place with their upstream
+ * visibility (most are TRF_INVISIBLE until revealed or triggered);
+ * square_memorize_traps / the player's shadow cave are replaced by the
+ * VISIBLE instance flag the renderer reads. player_is_trapsafe and the
+ * OF_ save-flag checks ride on the playerHasFlag hook; a flag that saves
+ * is noticed on the equipment supplying it (equipLearnFlag, rune
+ * knowledge #13).
+ */
+import type { Loc } from "../loc.js";
+import type { Rng } from "../rng.js";
+import type { TrapKind } from "../world/trap.js";
+import type { GameState } from "./context.js";
+import type { ObjCmdDeps } from "./obj-cmd.js";
+import type { ActionRegistry } from "./player-turn.js";
+/** struct trap: one trap instance on a grid. */
+export interface Trap {
+    tidx: number;
+    kind: TrapKind;
+    grid: Loc;
+    /** Rolled from the kind's power at placement (vs SEARCH on reveal). */
+    power: number;
+    /** Turns this trap is disabled for (0 = armed). */
+    timeout: number;
+    /** Instance flags (a copy of the kind's; VISIBLE toggles here). */
+    flags: import("../bitflag.js").FlagSet;
+}
+/** Hooks for unported subsystems; all optional. */
+export interface TrapEnv {
+    msg?: (text: string) => void;
+    /** player_is_trapsafe / player_of_has(OF_TRAP_IMMUNE etc, #13/#24). */
+    playerHasFlag?: (ofFlag: number) => boolean;
+    /** is_quest(depth) for the trapdoor legality check. */
+    isQuest?: (depth: number) => boolean;
+    /** dungeon_change_level for TRF_DOWN (default: signal generateLevel). */
+    changeLevel?: (state: GameState) => void;
+    /** player_exp_gain on a successful disarm (experience system). */
+    expGain?: (amount: number) => void;
+    disturb?: () => void;
+}
+/** Everything the trap runtime needs beyond the state. */
+export interface TrapDeps {
+    kinds: readonly TrapKind[];
+    /** The effect stack (same registry/cast/envDeps bundle as obj-cmd). */
+    effects?: Pick<ObjCmdDeps, "registry" | "cast" | "envDeps" | "inject" | "teleport" | "general" | "item" | "summon">;
+    env?: TrapEnv;
+}
+/** player_is_trapsafe (player-util.c:1073-1077). */
+export declare function playerIsTrapsafe(state: GameState): boolean;
+/**
+ * The trap-backed TeleportEnv / FloorEnv predicates (square_isplayertrap,
+ * square_iswarded, square_iswebbed) for the modules that stubbed them.
+ */
+export declare function trapPredicates(state: GameState): {
+    isPlayerTrap: (grid: Loc) => boolean;
+    isWarded: (grid: Loc) => boolean;
+    isWebbed: (grid: Loc) => boolean;
+    isTrap: (grid: Loc) => boolean;
+};
+/** square_trap: the traps on a grid, newest first (place prepends). */
+export declare function squareTrap(state: GameState, grid: Loc): readonly Trap[];
+/** square_istrap-ish: any trap here? */
+export declare function squareIsTrap(state: GameState, grid: Loc): boolean;
+/** square_trap_flag: any trap here with the given TRF flag? */
+export declare function squareTrapFlag(state: GameState, grid: Loc, flag: number): boolean;
+/** square_isplayertrap. */
+export declare function squareIsPlayerTrap(state: GameState, grid: Loc): boolean;
+/** square_isvisibletrap. */
+export declare function squareIsVisibleTrap(state: GameState, grid: Loc): boolean;
+/**
+ * square_isdisabledtrap (cave-square.c L823): a known (visible) player trap that
+ * is currently on a disable timeout.
+ */
+export declare function squareIsDisabledTrap(state: GameState, grid: Loc): boolean;
+/**
+ * square_isdisarmabletrap (cave-square.c L832): a visible, enabled player trap -
+ * the gate KILL_TRAP and the disarm command require (not merely "visible").
+ */
+export declare function squareIsDisarmableTrap(state: GameState, grid: Loc): boolean;
+/**
+ * square_iswarded (cave-square.c:751-755): only the specific "glyph of
+ * warding" trap, not every TRF_GLYPH (decoys also carry GLYPH).
+ */
+export declare function squareIsWarded(state: GameState, grid: Loc): boolean;
+/** square_iswebbed (cave-square.c:763-767). */
+export declare function squareIsWebbed(state: GameState, grid: Loc): boolean;
+/**
+ * square_destroy_trap (cave-square.c:1391-1394): remove every trap on a grid.
+ */
+export declare function squareDestroyTrap(state: GameState, grid: Loc): void;
+/**
+ * Live square_set_feat trap half (cave-square.c:1256-1259): when the grid
+ * is no longer player-trap-allowed, destroy its traps. Wired as Chunk.onFeatSet.
+ */
+export declare function squareSetFeatTrapSideEffect(state: GameState, grid: Loc): void;
+/**
+ * Install the live character_dungeon set_feat hook on the current chunk
+ * (cave-square.c:1256-1259). Re-call after every state.chunk reassignment.
+ */
+export declare function installChunkFeatHook(state: GameState): void;
+/** square_trap_specific: a trap of the exact kind index here? */
+export declare function squareTrapSpecific(state: GameState, grid: Loc, tidx: number): boolean;
+/** square_remove_trap: remove one trap instance. */
+export declare function squareRemoveTrap(state: GameState, grid: Loc, trap: Trap): boolean;
+/** square_remove_all_traps / _of_type. */
+export declare function squareRemoveAllTraps(state: GameState, grid: Loc, tidx?: number): boolean;
+/**
+ * square_player_trap_allowed: no second trap, no objects, trappable
+ * terrain (TF TRAP on the feature).
+ */
+export declare function squarePlayerTrapAllowed(state: GameState, grid: Loc): boolean;
+/** The level context pick_trap reads for its trapdoor legality guards. */
+export interface TrapLevelCtx {
+    /** c->depth (player->depth): town has no traps. */
+    depth: number;
+    /** z_info->max_depth: no trap doors on the deepest level. */
+    maxDepth: number;
+    /** is_quest(player->depth): no trap doors on quest levels. */
+    isQuest: boolean;
+    /** OPT(player, birth_levels_persist): no trap doors with persistent levels. */
+    persist: boolean;
+}
+/**
+ * pick_trap core (trap.c:275-345): cumulative-rarity selection of a player
+ * trap kind at a trap level, drawing exactly one randint0. Pure - the caller
+ * supplies the RNG and level context, so both the live placer (pickTrap) and
+ * the generation-time placer (gen/util.ts placeTrap) share one implementation
+ * and one draw order. The feature is assumed floor / trap-holding in the
+ * ported subset, so C's `feat_is_floor(feat) && !TRF_FLOOR` branch reduces to
+ * an unconditional TRF_FLOOR requirement. Returns the t_idx or -1.
+ */
+export declare function pickTrapKind(rng: Rng, kinds: readonly TrapKind[], trapLevel: number, ctx: TrapLevelCtx): number;
+/**
+ * pick_trap: choose a player-trap kind for a feature at a trap level, by
+ * cumulative rarity. Returns the t_idx or -1.
+ */
+export declare function pickTrap(state: GameState, feat: number, trapLevel: number, deps: TrapDeps): number;
+/**
+ * place_trap: make a new trap of the given type (or a random player trap
+ * when the index is not legal).
+ */
+export declare function placeTrap(state: GameState, grid: Loc, tIdx: number, trapLevel: number, deps: TrapDeps): void;
+/**
+ * place_trap's allocation half (trap.c:376-393) with the kind and power
+ * already chosen: prepend a new trap instance to the grid's list. Used by
+ * placeTrap after its pick_trap / randcalc draws, and directly by the level
+ * populate path when the kind and power were rolled at generation time
+ * (gen/util.ts placeTrap), so those draws are not spent twice.
+ *
+ * square_set_trap (cave-square.c:1299) has no counterpart by design: upstream
+ * keeps a per-square singly-linked trap list and that setter writes its HEAD
+ * pointer. The port stores an array per grid in state.traps, so head-pointer
+ * assignment becomes unshift here, splice in squareRemoveTrap and delete in
+ * squareRemoveAllTraps.
+ */
+export declare function installTrap(state: GameState, grid: Loc, tIdx: number, power: number, deps: TrapDeps): void;
+/**
+ * square_reveal_trap: mark unnoticed player traps visible when the SEARCH
+ * skill beats their power (or always). Returns whether any were found.
+ */
+export declare function squareRevealTrap(state: GameState, grid: Loc, always: boolean, deps: TrapDeps): boolean;
+/**
+ * square_note_spot's secret-trap revelation (cave-map.c:236-238) and the
+ * per-grid update_one pass (cave-view.c:840-842): when a grid becomes seen, a
+ * secret player trap on it is revealed if the SEARCH skill beats its power
+ * (always=false). Called from the note_spot pass (game/known.ts noteSpots) so
+ * invisible traps are spotted before being stepped on, matching upstream. The
+ * "You have found a trap" message rides the game's message seam (state.msg);
+ * squareRevealTrap reads only that env hook, never deps.kinds here.
+ */
+export declare function noteSpotRevealTrap(state: GameState, grid: Loc): void;
+/**
+ * hit_trap: trigger the player traps on a grid. `delayed` selects
+ * TRF_DELAY traps (1), immediate traps (0), or all (-1).
+ */
+export declare function hitTrap(state: GameState, grid: Loc, delayed: number, deps: TrapDeps): void;
+/**
+ * square_set_trap_timeout (trap.c:625): disable traps here for `time` turns.
+ *
+ * `domsg` is DEAD IN THE C. square_set_trap_timeout has exactly one caller in
+ * all of 4.2.6 - square_disable_trap at cave-square.c:1399 - and it passes
+ * false, so trap.c:653's "You have disabled the %s." can never reach a player
+ * upstream. It is ported anyway, behind the same parameter and the same
+ * default, so the port is a complete translation of the function rather than a
+ * translation of the reachable half; a mod that calls this with domsg on gets
+ * upstream's message rather than silence.
+ */
+export declare function squareSetTrapTimeout(state: GameState, grid: Loc, tIdx: number, time: number, domsg?: boolean, msg?: (text: string) => void): boolean;
+/** square_trap_timeout: the first matching trap's remaining disable time. */
+export declare function squareTrapTimeout(state: GameState, grid: Loc, tIdx: number): number;
+/** square_set_door_lock: lock a closed door to a power. */
+export declare function squareSetDoorLock(state: GameState, grid: Loc, power: number, deps: TrapDeps): void;
+/** square_door_power: the lock power on a closed door (0 = unlocked). */
+export declare function squareDoorPower(state: GameState, grid: Loc, deps: TrapDeps): number;
+/**
+ * calc_unlocking_chance (player-calcs.c L1676): DISARM_PHYS vs 4x lock
+ * power, tenth-ed while blind / confused / hallucinating, floor of 2.
+ */
+export declare function calcUnlockingChance(state: GameState, lockPower: number): number;
+/**
+ * do_cmd_disarm_aux: one disarm attempt on the first player trap at a
+ * grid. Returns whether the command may repeat.
+ */
+export declare function disarmAux(state: GameState, grid: Loc, deps: TrapDeps): boolean;
+/**
+ * Register the disarm command and wire the trap hooks: walk onto a player
+ * trap triggers it, and the door-lock seams back cave-cmd's open command.
+ */
+export declare function installTraps(state: GameState, registry: ActionRegistry, deps: TrapDeps): void;
+//# sourceMappingURL=trap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trap.d.ts","sourceRoot":"","sources":["../../src/game/trap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAErC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAMrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAIjD,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,cAAc,CAAC;AAI7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD,gDAAgD;AAChD,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,GAAG,CAAC;IACV,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,KAAK,EAAE,OAAO,eAAe,EAAE,OAAO,CAAC;CACxC;AAED,mDAAmD;AACnD,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,uDAAuD;IACvD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IACrC,yEAAyE;IACzE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,kEAAkE;IAClE,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,0DAA0D;AAC1D,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,uEAAuE;IACvE,OAAO,CAAC,EAAE,IAAI,CACZ,UAAU,EACR,UAAU,GACV,MAAM,GACN,SAAS,GACT,QAAQ,GACR,UAAU,GACV,SAAS,GACT,MAAM,GACN,QAAQ,CACX,CAAC;IACF,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,oDAAoD;AACpD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAS1D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG;IAChD,YAAY,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC;IACrC,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC;IACjC,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC;IACjC,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC;CAChC,CAOA;AAMD,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,SAAS,IAAI,EAAE,CAEvE;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAEjE;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,IAAI,EAAE,MAAM,GACX,OAAO,CAET;AAED,2BAA2B;AAC3B,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAEvE;AAED,4BAA4B;AAC5B,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAExE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAIzE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAG3E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CASnE;AACD,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAEnE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI,CAEnE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI,CAI7E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAI3D;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,IAAI,EAAE,MAAM,GACX,OAAO,CAET;AAED,oDAAoD;AACpD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,IAAI,EAAE,IAAI,GACT,OAAO,CAST;AAED,0CAA0C;AAC1C,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,IAAI,SAAK,GACR,OAAO,CAaT;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,GACR,OAAO,CAKT;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,YAAY,GAChB,MAAM,CAkCR;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GACb,MAAM,CASR;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GACb,IAAI,CAYN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,QAAQ,GACb,IAAI,CAeN;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,QAAQ,GACb,OAAO,CAkBT;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI,CAUpE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,QAAQ,GACb,IAAI,CAmFN;AAkCD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,KAAK,UAAQ,EACb,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC3B,OAAO,CAUT;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,IAAI,EAAE,MAAM,GACX,MAAM,CAMR;AAMD,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,QAAQ,GACb,IAAI,CASN;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,IAAI,EAAE,QAAQ,GACb,MAAM,CAOR;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAWR;AAMD;;;GAGG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,GAAG,EACT,IAAI,EAAE,QAAQ,GACb,OAAO,CAyCT;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,QAAQ,GACb,IAAI,CAsCN"}