@rpgm-tools/neo-angband-core 0.10.0

package/src/game/harness.ts

@@ -0,0 +1,270 @@
+/**
+ * Shared test fixtures for the game turn-loop suites. Not part of the public
+ * API; it binds the content pack once and builds GameState instances so the
+ * colocated *.test.ts files stay focused on behaviour rather than setup.
+ */
+
+import { readFileSync } from "node:fs";
+import { FlagSet } from "../bitflag.js";
+import { Dice } from "../dice.js";
+import { Rng } from "../rng.js";
+import { loc } from "../loc.js";
+import type { Loc } from "../loc.js";
+import { SKILL } from "../player/types.js";
+import { RF_SIZE } from "../mon/types.js";
+import type { MonsterBlow, MonsterDrop, MonsterRace } from "../mon/types.js";
+import { blankMonster } from "../mon/monster.js";
+import type { Monster } from "../mon/monster.js";
+import { bindMonsters } from "../mon/bind.js";
+import type { MonsterPackRecords } from "../mon/bind.js";
+import { bindPlayer } from "../player/bind.js";
+import type { PlayerPackRecords } from "../player/bind.js";
+import { blankPlayer } from "../player/player.js";
+import type { Player } from "../player/player.js";
+import { Chunk } from "../world/chunk.js";
+import { FeatureRegistry } from "../world/feature.js";
+import type { TerrainRecordJson } from "../world/feature.js";
+import type { PlayerCombatState } from "../combat/melee.js";
+import type { DefenderState } from "../combat/mon-melee.js";
+import { DEFAULT_GAME_CONSTANTS, addMonster, placePlayer } from "./context.js";
+import type { GameState, PlayerActor, PlayerCommand } from "./context.js";
+import { newGear } from "./gear.js";
+import { newKnownMap } from "./known.js";
+import { newTargetState } from "./target.js";
+import { IgnoreSettings } from "../obj/ignore.js";
+import { makeRuneEnv } from "../obj/knowledge.js";
+
+function load(name: string): unknown {
+  return JSON.parse(
+    readFileSync(
+      new URL(`../../../content/pack/${name}.json`, import.meta.url),
+      "utf8",
+    ),
+  );
+}
+function packJson<T>(name: string): T[] {
+  return (load(name) as { records: T[] }).records;
+}
+
+const terrain = load("terrain") as { records: TerrainRecordJson[] };
+export const featureReg = new FeatureRegistry(terrain.records);
+export const FLOOR = featureReg.byCodeName("FLOOR").fidx;
+export const GRANITE = featureReg.byCodeName("GRANITE").fidx;
+
+export const monReg = bindMonsters({
+  pain: packJson("pain"),
+  blowMethods: packJson("blow_methods"),
+  blowEffects: packJson("blow_effects"),
+  monsterSpells: packJson("monster_spell"),
+  monsterBases: packJson("monster_base"),
+  monsters: packJson("monster"),
+  summons: packJson("summon"),
+  pits: packJson("pit"),
+} as MonsterPackRecords);
+
+export const plReg = bindPlayer({
+  races: packJson("p_race"),
+  classes: packJson("class"),
+  properties: packJson("player_property"),
+  timed: packJson("player_timed"),
+  shapes: packJson("shape"),
+  bodies: packJson("body"),
+  history: packJson("history"),
+  realms: packJson("realm"),
+} as PlayerPackRecords);
+
+/** A real race carrying a base and at least one blow, used as a template. */
+const baseRace = monReg.races.find(
+  (r) => r.base && r.blows.length > 0,
+) as MonsterRace;
+
+/** Build a monster blow from named pack method/effect and a dice string. */
+export function makeBlow(
+  methodName: string,
+  effectName: string,
+  diceStr: string,
+): MonsterBlow {
+  const method = monReg.blowMethods.get(methodName);
+  const effect = monReg.blowEffects.get(effectName);
+  if (!method || !effect) throw new Error(`missing blow ${methodName}/${effectName}`);
+  const d = new Dice();
+  d.parseString(diceStr);
+  return { method, effect, dice: d, diceRaw: diceStr };
+}
+
+export interface RaceOverrides {
+  level?: number;
+  speed?: number;
+  hearing?: number;
+  smell?: number;
+  mexp?: number;
+  ac?: number;
+  flags?: number[];
+  blows?: MonsterBlow[];
+  drops?: MonsterDrop[];
+}
+
+/** A MonsterRace derived from the template, with a fresh flag set. */
+export function makeRace(overrides: RaceOverrides = {}): MonsterRace {
+  const flags = new FlagSet(RF_SIZE);
+  for (const f of overrides.flags ?? []) flags.on(f);
+  return {
+    ...baseRace,
+    level: overrides.level ?? 5,
+    speed: overrides.speed ?? 110,
+    hearing: overrides.hearing ?? 20,
+    smell: overrides.smell ?? 0,
+    mexp: overrides.mexp ?? 100,
+    ac: overrides.ac ?? 10,
+    flags,
+    blows: overrides.blows ?? baseRace.blows,
+    drops: overrides.drops ?? [],
+  };
+}
+
+/** A level-1 player with full HP. */
+export function makePlayer(): Player {
+  const p = blankPlayer(
+    plReg.races[0] as (typeof plReg.races)[number],
+    plReg.classes[0] as (typeof plReg.classes)[number],
+    plReg.bodies[0] as (typeof plReg.bodies)[number],
+  );
+  p.lev = 1;
+  p.mhp = 1000;
+  p.chp = 1000;
+  return p;
+}
+
+/** A player combat state that hits reliably (calc_bonuses is deferred). */
+export function defaultCombat(): PlayerCombatState {
+  const skills = new Array<number>(SKILL.DIGGING + 1).fill(20);
+  return {
+    toH: 20,
+    toD: 10,
+    ac: 0,
+    toA: 0,
+    skills,
+    numBlows: 100,
+    ammoMult: 1,
+    numShots: 0,
+    ammoTval: 0,
+    blessWield: false,
+  };
+}
+
+export function defaultDefense(): DefenderState {
+  return { ac: 0, toA: 0 };
+}
+
+/** An open floor field enclosed by granite, like the flow test's fixture. */
+export function openField(w: number, h: number): Chunk {
+  const c = new Chunk(featureReg, h, w);
+  c.fill(GRANITE);
+  for (let y = 1; y < h - 1; y++) {
+    for (let x = 1; x < w - 1; x++) {
+      c.setFeat(loc(x, y), FLOOR);
+    }
+  }
+  return c;
+}
+
+export interface StateOptions {
+  seed?: number;
+  w?: number;
+  h?: number;
+  playerGrid?: Loc;
+  speed?: number;
+  stealth?: number;
+  commands?: PlayerCommand[];
+  updateFov?: (state: GameState) => void;
+  /** Collector for the world-clock messages (grade, wear-off, take_hit, etc.). */
+  worldMsgs?: string[];
+}
+
+/** Build a GameState on an open field with the player placed and marked. */
+export function makeState(opts: StateOptions = {}): GameState {
+  const w = opts.w ?? 40;
+  const h = opts.h ?? 25;
+  const chunk = openField(w, h);
+  const playerGrid = opts.playerGrid ?? loc(Math.floor(w / 2), Math.floor(h / 2));
+  const commands = opts.commands ?? [];
+
+  const actor: PlayerActor = {
+    player: makePlayer(),
+    grid: playerGrid,
+    energy: 0,
+    speed: opts.speed ?? 110,
+    totalEnergy: 0,
+    combat: defaultCombat(),
+    defense: defaultDefense(),
+    weapon: null,
+    stealth: opts.stealth ?? 0,
+    light: 0,
+    unlight: false,
+  };
+
+  const rng = new Rng(opts.seed ?? 1);
+  const gear = newGear();
+  const state: GameState = {
+    rng,
+    chunk,
+    actor,
+    gear,
+    monsters: [null],
+    groups: [null],
+    floor: new Map(),
+    traps: new Map(),
+    known: newKnownMap(w, h),
+    target: newTargetState(),
+    ignore: new IgnoreSettings(),
+    lore: new Map(),
+    turn: 0,
+    z: { ...DEFAULT_GAME_CONSTANTS },
+    brands: [null],
+    slays: [null],
+    runeEnv: makeRuneEnv(
+      (slot) => gear.store.get(actor.player.equipment[slot] ?? 0) ?? null,
+      (v) => rng.randcalcVaries(v),
+    ),
+    playing: true,
+    isDead: false,
+    generateLevel: false,
+    nextCommand: () => commands.shift() ?? null,
+    ...(opts.updateFov ? { updateFov: opts.updateFov } : {}),
+  };
+
+  /* A default process_world upkeep env: the bound timed table so decrements
+   * route through the grade / message machinery, and message sinks (grade,
+   * wear-off, take_hit) collected into opts.worldMsgs when supplied. */
+  const worldMsgs = opts.worldMsgs;
+  const push = (t: string): void => {
+    if (worldMsgs) worldMsgs.push(t);
+  };
+  state.world = {
+    timedTable: plReg.timed,
+    timedHooks: { onMessage: (t) => push(t) },
+    takeHitHooks: { rng, onMessage: (t) => push(t) },
+    expDeps: { rng },
+  };
+
+  placePlayer(state, playerGrid);
+  return state;
+}
+
+/** Create a monster of `race` at `grid`, awake, and register it in the state. */
+export function addMon(
+  state: GameState,
+  race: MonsterRace,
+  grid: Loc,
+  opts: { energy?: number; hp?: number } = {},
+): Monster {
+  const mon = blankMonster(race);
+  mon.grid = grid;
+  mon.maxhp = opts.hp ?? race.avgHp ?? 30;
+  mon.hp = mon.maxhp;
+  mon.mspeed = race.speed;
+  mon.energy = opts.energy ?? 0;
+  mon.mTimed[0] = 0; /* MON_TMD.SLEEP: awake. */
+  addMonster(state, mon);
+  return mon;
+}

package/src/game/history.ts

@@ -0,0 +1,78 @@
+/**
+ * Game-layer glue for the character history log (player/history.ts is the
+ * pure module; this supplies the two things only live GameState can give it:
+ * the dlev/clev/turn stamp and the artifact fake-name builder).
+ *
+ * Ported from player-history.c:
+ * - history_add_with_flags (L115-121): stamps every entry with p->depth,
+ *   p->lev and p->total_energy/100 - matched here by state.chunk.depth,
+ *   state.actor.player.lev and trunc(state.actor.totalEnergy/100). The
+ *   turn stamp is deliberately total_energy/100 (what ui-history.c
+ *   displays), not state.turn.
+ * - get_artifact_name (L197-215), which is obj-make.c's make_fake_artifact
+ *   (object_prep(kind, 0, MAXIMISE) then copy_artifact_data) followed by
+ *   object_desc(ODESC_PREFIX|ODESC_BASE|ODESC_SPOIL).
+ *
+ * RNG SAFETY: objectPrep's "maximise" aspect draws nothing (damcalc/
+ * mBonusCalc's maximise branches are pure arithmetic - see rng.ts). Unlike
+ * make_fake_artifact, this builder deliberately does NOT call
+ * copyArtifactData: that helper's copy_curses step always rolls the curse
+ * timeout with the "randomise" aspect regardless of the caller's aspect
+ * (obj-curse.c:67, ported faithfully in obj/object.ts copyCurses) - a
+ * property upstream itself has. Since object_desc's PREFIX|BASE|SPOIL mode
+ * never reads modifiers/combat bonuses/curses (only ODESC_COMBAT's
+ * objDescCombat does, via env), only obj.kind and obj.artifact feed the
+ * name text, so copying the rest is both unnecessary and would risk an RNG
+ * draw for the one artifact in the game data that carries a curse
+ * (artifact.txt's "curse:air swing:30"). A golden test in
+ * game/history.test.ts pins the exact string this produces so any future
+ * drift from make_fake_artifact's real behaviour is caught.
+ */
+
+import type { Artifact } from "../obj/types.js";
+import type { Constants } from "../constants.js";
+import type { ObjRegistry } from "../obj/bind.js";
+import { ODESC, objectDesc } from "../obj/desc.js";
+import { objectPrep } from "../obj/make.js";
+import { knownDescOf } from "./describe.js";
+import type { GameState } from "./context.js";
+
+/** The dlev/clev/turn stamp history_add_with_flags reads off live state. */
+export interface HistoryStamp {
+  dlev: number;
+  clev: number;
+  turn: number;
+}
+
+/** history_add_with_flags's stamp (player-history.c L115-121). */
+export function historyStamp(state: GameState): HistoryStamp {
+  return {
+    dlev: state.chunk.depth,
+    clev: state.actor.player.lev,
+    turn: Math.trunc(state.actor.totalEnergy / 100),
+  };
+}
+
+/**
+ * get_artifact_name (player-history.c L197-215): the spoiled description
+ * ("the Phial of Galadriel") history_find_artifact / history_lose_artifact
+ * use for their "Found "/"Missed " text. RNG-free (see module doc).
+ */
+export function artifactHistoryName(
+  state: GameState,
+  reg: ObjRegistry,
+  constants: Constants,
+  art: Artifact,
+): string {
+  const kind = reg.lookupKind(art.tval, art.sval);
+  if (!kind) return art.name;
+  const obj = objectPrep(state.rng, reg, constants, kind, 0, "maximise");
+  obj.artifact = art;
+  return objectDesc(
+    obj,
+    ODESC.PREFIX | ODESC.BASE | ODESC.SPOIL,
+    null,
+    state.runeEnv,
+    knownDescOf(state),
+  );
+}

package/src/game/ignore-cmd.ts

@@ -0,0 +1,68 @@
+/**
+ * ignore_drop (obj-ignore.c L651): "drop all {ignore}able gear" - fired by
+ * notice_stuff's PN_IGNORE handling whenever a menu edit or the 'K'
+ * unignoring toggle flags the notice (player-calcs.c L2542).
+ *
+ * This module holds only the SCAN half (which gear objects are eligible and
+ * whether each is currently worn): a pure read with no game mutation, so it
+ * belongs beside the other game/ state readers rather than in obj/ignore.ts
+ * (which stays free of GameState/Gear so it has no upward dependency on the
+ * game layer). The shell (web/main.ts's applyIgnoreDrop) does the actual
+ * work upstream interleaves here: confirming + inscribing "!d" on a declined
+ * equipped item, and queuing the real CMD_DROP-equivalent "drop" command for
+ * the rest.
+ *
+ * GEAR ORDER: upstream walks p->gear (one combined linked list of pack AND
+ * equipped objects in insertion order) backwards via gear_last_item/obj->prev.
+ * This port's Gear (game/gear.ts) deliberately has no such combined
+ * insertion-order list - equipment lives in fixed player.equipment[] slots
+ * and the pack is its own ordered array (see game/gear.ts's module doc). The
+ * faithful-enough substitute here is: equipment slots in slot order, then the
+ * pack in its own order, the whole thing reversed - so every ignorable item
+ * is still visited exactly once and pack items (usually the freshest
+ * ignores) are offered first, without claiming to reproduce upstream's exact
+ * add-order sequence.
+ */
+
+import type { GameState } from "./context.js";
+import { checkForInscrip } from "./pickup.js";
+
+/** One gear object ignore_drop is willing to drop. */
+export interface IgnoreDropTarget {
+  /** The gear handle (state.gear.store key). */
+  handle: number;
+  /** Whether the object is currently worn (object_is_equipped). */
+  equipped: boolean;
+  /** The full stack count to drop (obj->number). */
+  number: number;
+}
+
+/**
+ * The scan half of ignore_drop: every gear object that is currently eligible
+ * for ignoring (state.isIgnored, i.e. ignore_item_ok) and not inscribed
+ * "!d"/"!*", in the backwards gear order described above.
+ */
+export function ignoreDropTargets(state: GameState): IgnoreDropTarget[] {
+  const player = state.actor.player;
+  const equipped = new Set<number>();
+  const handles: number[] = [];
+  for (let i = 0; i < player.body.count; i++) {
+    const handle = player.equipment[i] ?? 0;
+    if (handle !== 0) {
+      handles.push(handle);
+      equipped.add(handle);
+    }
+  }
+  for (const handle of state.gear.pack) handles.push(handle);
+  handles.reverse();
+
+  const out: IgnoreDropTarget[] = [];
+  for (const handle of handles) {
+    const obj = state.gear.store.get(handle);
+    if (!obj) continue;
+    if (!(state.isIgnored?.(obj) ?? false)) continue;
+    if (checkForInscrip(obj, "!d") || checkForInscrip(obj, "!*")) continue;
+    out.push({ handle, equipped: equipped.has(handle), number: obj.number });
+  }
+  return out;
+}

package/src/game/inscription-confirm.ts

@@ -0,0 +1,115 @@
+/**
+ * The `!` / `^` inscription safety net - Angband's oldest and most-used way of
+ * protecting yourself from your own fingers. Inscribe `!q` on a Potion of Death
+ * and quaffing it asks first; `^t` on your body armour and every Take off asks;
+ * `!*` or `^*` covers every command at once.
+ *
+ * Two upstream functions, both of which the port was missing entirely:
+ *
+ * - `key_confirm_command` (ui-input.c:1995-2020) scans the WORN EQUIPMENT for
+ *   `^*` and `^<key>` and asks "Are you sure? " once per occurrence found, before
+ *   the command key is turned into a command at all (ui-game.c:565; also
+ *   ui-context.c:155, :349, :353, :585 for the context menus).
+ * - `get_item_allow` (ui-object.c:634-679) scans the SELECTED OBJECT for
+ *   `!<key>` - plus `!*` unless the command is harmless - and asks
+ *   verify_object's "Really <verb> <the object>? " once per occurrence, from the
+ *   item menu as a row is chosen (ui-object.c:958) and from the context menu's
+ *   object actions (ui-context.c:855).
+ *
+ * The census found only "Are you sure? " here, because get_item_allow's prompt
+ * is assembled by strnfmt and its literal fragments ("Really ", " %s? ") are
+ * shorter than the anchor floor. The behaviour behind the one string it did find
+ * is the whole feature.
+ *
+ * Both are pure counts and strings: core decides how many confirmations are owed
+ * and what to say, and the shell awaits them, the same division walkTerrainPrompt
+ * uses (game/player-turn.ts) because the core command path cannot block on UI.
+ */
+
+import type { Player } from "../player/player.js";
+import type { GameObject } from "../obj/object.js";
+import type { Gear } from "./gear.js";
+import type { CommandCode } from "../cmd.js";
+import { cmdVerb } from "../cmd.js";
+import { checkForInscrip } from "./pickup.js";
+
+/** get_check's prompt in key_confirm_command (ui-input.c:2014), verbatim. */
+export const KEY_CONFIRM_PROMPT = "Are you sure? ";
+
+/** cmd_verb's fallback when a command has no verb (ui-object.c:664-665). */
+export const ITEM_ALLOW_FALLBACK_VERB = "do that with";
+
+/**
+ * UN_KTRL_CAP (ui-event.h:135): a control code becomes its CAPITAL letter, not
+ * the lower-case one UN_KTRL would give. The comment there explains why - the
+ * roguelike ignore command is Ctrl-D, and UN_KTRL would turn that into 'd', the
+ * drop command in both keysets, so `!d` would fire on an ignore.
+ */
+export function unKtrlCap(key: string): string {
+  const code = key.charCodeAt(0);
+  return code < 0x20 ? String.fromCharCode(code + 64) : key;
+}
+
+/**
+ * key_confirm_command (ui-input.c:1995-2020): how many times "Are you sure? "
+ * must be answered before command key `key` may run. Zero almost always.
+ *
+ * Upstream asks per equipment slot and aborts on the first refusal, so a total
+ * is equivalent - every prompt must be accepted for the command to proceed.
+ *
+ * The `key === "*"` case counts DOUBLE, and that is upstream's arithmetic, not a
+ * slip here: verify_inscrip starts life as the string "^*" and only its second
+ * byte is overwritten, so for '*' both terms of the sum count the same
+ * inscription. Kept because core keeps upstream's warts.
+ *
+ * `key` is used RAW - no unKtrlCap. get_item_allow shifts a control code to its
+ * capital and this function pointedly does not, so a roguelike Ctrl-chord looks
+ * for a `^` plus a control byte, which no inscription can hold, and asks nothing.
+ * That asymmetry is upstream's; do not tidy it.
+ */
+export function keyConfirmCount(player: Player, gear: Gear, key: string): number {
+  let n = 0;
+  for (let i = 0; i < player.body.count; i++) {
+    const handle = player.equipment[i] ?? 0;
+    const obj = handle ? gear.store.get(handle) : undefined;
+    if (!obj) continue;
+    n += checkForInscrip(obj, "^*") + checkForInscrip(obj, `^${key}`);
+  }
+  return n;
+}
+
+/** What get_item_allow owes: a prompt and how many times to ask it. */
+export interface ItemAllowPrompt {
+  /** verify_object's finished question (obj-util.c:1085), trailing space and all. */
+  readonly prompt: string;
+  /** How many matching inscriptions were found; each one asks again. */
+  readonly count: number;
+}
+
+/**
+ * get_item_allow (ui-object.c:634-679): the confirmations `obj` demands before
+ * command key `key` may act on it, or null when it demands none.
+ *
+ * `isHarmless` is upstream's IS_HARMLESS flag - a harmless command (inspecting,
+ * for instance) ignores a blanket `!*` but still honours its own `!<key>`.
+ *
+ * `describe` is object_desc(ODESC_PREFIX | ODESC_FULL) (obj-util.c:1082); the
+ * shell passes its own namer so the format string stays here, next to the C
+ * line it copies.
+ */
+export function itemAllowPrompt(
+  obj: GameObject,
+  key: string,
+  cmd: CommandCode | null,
+  isHarmless: boolean,
+  describe: (obj: GameObject) => string,
+): ItemAllowPrompt | null {
+  const ch = unKtrlCap(key);
+  let count = checkForInscrip(obj, `!${ch}`);
+  if (!isHarmless) count += checkForInscrip(obj, "!*");
+  if (!count) return null;
+  const verb = (cmd ? cmdVerb(cmd) : null) ?? ITEM_ALLOW_FALLBACK_VERB;
+  /* strnfmt "Really %s" (ui-object.c:667) then verify_object's "%s %s? "
+   * (obj-util.c:1085) - one prompt built in two steps upstream. */
+  return { prompt: `Really ${verb} ${describe(obj)}? `, count };
+}