@rpgm-tools/neo-angband-core 0.10.0

package/src/mon/spell.ts

@@ -0,0 +1,418 @@
+/**
+ * Monster-spell substrate, ported from reference/src/mon-spell.c (Angband
+ * 4.2.6): the spell-type classification (the mon_spell_types table built from
+ * list-mon-spells.h), the spell-type predicates and masks, the spell-hit
+ * chance, and the breath-damage calculation. These are the pure computations
+ * over the bound spell / race data that both the spell executor (do_mon_spell,
+ * game/ layer) and the spell-selection AI (choose_attack_spell / remove_bad_
+ * spells, mon-attack.c) sit on; they do not touch the GameState, so they live
+ * here in mon/ below game/.
+ *
+ * The RST_ classification is generated as a string expression per spell
+ * (generated/mon-spells.ts keeps `type` as written, e.g. "RST_BREATH |
+ * RST_INNATE"); MON_SPELL_TYPES evaluates each once into a bitmask indexed by
+ * RSF value (index 0 is RSF_NONE, matching the enum), so the lookups mirror
+ * upstream's mon_spell_types[index] exactly.
+ *
+ * monSpellNonhpDamage (nonhp_dam, mon-spell.c L571) is the non-breath half of
+ * mon_spell_dam: the deterministic MAXIMISE sum of a spell's damaging effect
+ * dice, with each effect's SPELL_POWER expression (the only base value
+ * monster-spell damage dice reference) rebound to the calling race - upstream
+ * sets its global `ref_race` for the same duration. This is the seam the
+ * lore/recall layer (mon/lore-describe.ts) needed to wire mon_spell_lore_damage
+ * for real; breath damage keeps using breathDam below unchanged.
+ */
+
+import { Dice } from "../dice.js";
+import { Expression } from "../expression.js";
+import { FlagSet } from "../bitflag.js";
+import { ELEM, MON_SPELL_ENTRIES, MON_TMD, OF, PF, RSF } from "../generated/index.js";
+import type { RandomValue, Rng } from "../rng.js";
+import { ELEM_MAX } from "../obj/types.js";
+import type { TimedFailLike } from "../obj/object.js";
+import { RSF_SIZE } from "./types.js";
+import type { MonsterRace, MonsterSpell, MonsterSpellEffect } from "./types.js";
+import type { Monster } from "./monster.js";
+import { monsterEffectLevel } from "./timed.js";
+import { monsterIsSmart, monsterIsStupid } from "./predicate.js";
+
+/**
+ * RST_ spell-type bitflags (mon-spell.h). RST_DAMAGE is the composite of the
+ * four damaging categories.
+ */
+export const RST = {
+  NONE: 0x0000,
+  BOLT: 0x0001,
+  BALL: 0x0002,
+  BREATH: 0x0004,
+  DIRECT: 0x0008,
+  ANNOY: 0x0010,
+  HASTE: 0x0020,
+  HEAL: 0x0040,
+  HEAL_OTHER: 0x0080,
+  TACTIC: 0x0100,
+  ESCAPE: 0x0200,
+  SUMMON: 0x0400,
+  INNATE: 0x0800,
+  ARCHERY: 0x1000,
+} as const;
+
+/** #define RST_DAMAGE (RST_BOLT | RST_BALL | RST_BREATH | RST_DIRECT). */
+export const RST_DAMAGE = RST.BOLT | RST.BALL | RST.BREATH | RST.DIRECT;
+
+/** CONF_HIT_REDUCTION (mon-timed.h): accuracy loss per level of confusion. */
+export const CONF_HIT_REDUCTION = 20;
+
+/** Evaluate a generated RST_ type expression ("RST_A | RST_B" or 0). */
+function evalTypeExpr(expr: string | number): number {
+  if (typeof expr === "number") return expr;
+  let mask = 0;
+  for (const tok of expr.split("|")) {
+    const name = tok.trim().replace(/^RST_/, "");
+    const value = (RST as Record<string, number>)[name];
+    if (value === undefined) throw new Error(`unknown RST token: ${tok}`);
+    mask |= value;
+  }
+  return mask;
+}
+
+/**
+ * The per-spell type bitmask, indexed by RSF value (mon_spell_types[]). Built
+ * once from the generated entries; index 0 (RSF_NONE) and the trailing MAX
+ * entry are 0.
+ */
+export const MON_SPELL_TYPES: readonly number[] = MON_SPELL_ENTRIES.map((e) =>
+  evalTypeExpr(e.type),
+);
+
+/** mon_spell_is_valid: a real RSF_ spell index. */
+export function monSpellIsValid(index: number): boolean {
+  return index > RSF.NONE && index < RSF.MAX;
+}
+
+/** monster_spell_is_breath. */
+export function monSpellIsBreath(index: number): boolean {
+  return (MON_SPELL_TYPES[index]! & RST.BREATH) !== 0;
+}
+
+/** mon_spell_has_damage. */
+export function monSpellHasDamage(index: number): boolean {
+  return (MON_SPELL_TYPES[index]! & RST_DAMAGE) !== 0;
+}
+
+/** mon_spell_is_innate. */
+export function monSpellIsInnate(index: number): boolean {
+  return (MON_SPELL_TYPES[index]! & RST.INNATE) !== 0;
+}
+
+/** test_spells: whether any spell of a wanted type is set in the flagset. */
+export function testSpells(f: FlagSet, types: number): boolean {
+  for (let index = RSF.NONE + 1; index < RSF.MAX; index++) {
+    if (f.has(index) && (MON_SPELL_TYPES[index]! & types) !== 0) return true;
+  }
+  return false;
+}
+
+/** ignore_spells: clear every spell of the given type(s) from the flagset. */
+export function ignoreSpells(f: FlagSet, types: number): void {
+  for (let index = RSF.NONE + 1; index < RSF.MAX; index++) {
+    if (f.has(index) && (MON_SPELL_TYPES[index]! & types) !== 0) f.off(index);
+  }
+}
+
+/** create_mon_spell_mask: a fresh flagset of every spell of the given type(s). */
+export function createMonSpellMask(...types: number[]): FlagSet {
+  const f = new FlagSet(RSF_SIZE);
+  const wanted = types.reduce((a, b) => a | b, 0);
+  for (let index = RSF.NONE + 1; index < RSF.MAX; index++) {
+    if ((MON_SPELL_TYPES[index]! & wanted) !== 0) f.on(index);
+  }
+  return f;
+}
+
+/**
+ * chance_of_spell_hit_base: MAX(race->level, 1) * 3 + spell->hit. See also the
+ * melee analogue chance_of_monster_hit_base.
+ */
+export function chanceOfSpellHitBase(
+  race: MonsterRace,
+  spell: MonsterSpell,
+): number {
+  return Math.max(race.level, 1) * 3 + spell.hit;
+}
+
+/** chance_of_spell_hit: the base to-hit reduced for each level of confusion. */
+export function chanceOfSpellHit(mon: Monster, spell: MonsterSpell): number {
+  let toHit = chanceOfSpellHitBase(mon.race, spell);
+  const conf = monsterEffectLevel(mon, MON_TMD.CONF);
+  for (let i = 0; i < conf; i++) {
+    toHit = Math.trunc((toHit * (100 - CONF_HIT_REDUCTION)) / 100);
+  }
+  return toHit;
+}
+
+/** The projection fields breath_dam reads (a structural view of ProjectionInfo). */
+export interface BreathProjection {
+  /** element->divisor: hp is divided by this. */
+  divisor: number;
+  /** element->damage_cap: the maximum breath damage. */
+  damageCap: number;
+}
+
+/**
+ * breath_dam: a monster breath does hp / divisor damage, capped at the
+ * element's damage cap.
+ */
+export function breathDam(proj: BreathProjection, hp: number): number {
+  let dam = Math.trunc(hp / proj.divisor);
+  if (dam > proj.damageCap) dam = proj.damageCap;
+  return dam;
+}
+
+/** TMD_FAIL_ codes (player-timed.h), for the unset_spells fail-table scan. */
+const TMD_FAIL_FLAG_OBJECT = 1;
+const TMD_FAIL_FLAG_RESIST = 2;
+const TMD_FAIL_FLAG_VULN = 3;
+const TMD_FAIL_FLAG_PLAYER = 4;
+
+/**
+ * unset_spells (mon-spell.c L470): turn off spells with a side effect or
+ * projection type resisted by what the monster knows about the player, subject
+ * to intelligence and chance. `flags` / `pflags` / `el` are the monster's
+ * ai-memorized view of the player (known_pstate copies); `timedFail` resolves a
+ * TMD_ name to its fail-condition table (the bound player-timed data).
+ *
+ * RNG order preserved exactly, including the C short-circuit quirks:
+ * - every elemental (BOLT/BALL/BREATH) spell present draws one randint0(100),
+ *   even when the learn chance is 0;
+ * - a non-smart monster draws one_in_(3) per EFFECT LINE of every non-elemental
+ *   spell (the `(smart || !one_in_(3)) && index == EF_TIMED_INC` gate is
+ *   evaluated left-to-right for every effect), and one_in_(2) likewise for the
+ *   drain-mana gate.
+ * Upstream indexes el[] by the raw projection subtype; for the handful of
+ * non-element breath subtypes (TIME / INERTIA / GRAVITY / PLASMA / MANA /
+ * WATER) that read past the element table in C, the port treats the resist
+ * level as 0 (an unreproducible out-of-bounds read; the draw still happens).
+ */
+export function unsetSpells(
+  rng: Rng,
+  spells: FlagSet,
+  flags: FlagSet,
+  pflags: FlagSet,
+  el: Int16Array,
+  mon: Monster,
+  spellTable: ReadonlyMap<number, MonsterSpell>,
+  timedFail: (tmdName: string) => readonly TimedFailLike[] | null,
+): void {
+  const smart = monsterIsSmart(mon);
+
+  for (let index = RSF.NONE + 1; index < RSF.MAX; index++) {
+    const spell = spellTable.get(index);
+    if (!spell) continue;
+    if (!spells.has(index)) continue;
+
+    const types = MON_SPELL_TYPES[index]!;
+
+    if (types & (RST.BOLT | RST.BALL | RST.BREATH)) {
+      /* First we test the elemental spells. */
+      const typeName = spell.effects[0]?.type ?? "";
+      const element = (ELEM as Record<string, number>)[typeName];
+      const resLevel =
+        element !== undefined && element < ELEM_MAX ? (el[element] ?? 0) : 0;
+      const learnChance = resLevel * (smart ? 50 : 25);
+      if (rng.randint0(100) < learnChance) {
+        spells.off(index);
+      }
+    } else {
+      /* Now others with resisted effects. */
+      let stopped = false;
+      for (const effect of spell.effects) {
+        /* Timed effects: the intelligence/chance gate draws for every
+         * effect line of a non-smart monster (C short-circuit order). */
+        const timedGate = smart || !rng.oneIn(3);
+        if (timedGate && effect.eff === "TIMED_INC") {
+          let resisted = false;
+          for (const f of timedFail(effect.type ?? "") ?? []) {
+            if (resisted) break;
+            switch (f.code) {
+              case TMD_FAIL_FLAG_OBJECT: {
+                const of = (OF as Record<string, number>)[f.flag];
+                if (of !== undefined && flags.has(of)) resisted = true;
+                break;
+              }
+              case TMD_FAIL_FLAG_RESIST: {
+                const e = (ELEM as Record<string, number>)[f.flag];
+                if (e !== undefined && (el[e] ?? 0) > 0) resisted = true;
+                break;
+              }
+              case TMD_FAIL_FLAG_VULN: {
+                const e = (ELEM as Record<string, number>)[f.flag];
+                if (e !== undefined && (el[e] ?? 0) < 0) resisted = true;
+                break;
+              }
+              case TMD_FAIL_FLAG_PLAYER: {
+                const pf = (PF as Record<string, number>)[f.flag];
+                if (pf !== undefined && pflags.has(pf)) resisted = true;
+                break;
+              }
+              /* TMD_FAIL_FLAG_TIMED_EFFECT: the monster does not track the
+               * player's timed effects; do nothing. */
+              default:
+                break;
+            }
+          }
+          if (resisted) {
+            stopped = true;
+            break;
+          }
+        }
+
+        /* Mana drain (the chance gate draws per effect for non-smart). */
+        const manaGate = smart || rng.oneIn(2);
+        if (
+          manaGate &&
+          effect.eff === "DRAIN_MANA" &&
+          pflags.has(PF.NO_MANA)
+        ) {
+          stopped = true;
+          break;
+        }
+      }
+      if (stopped) spells.off(index);
+    }
+  }
+}
+
+/** The player-side seams update_smart_learn drives (mon-util.c L788). */
+export interface SmartLearnEnv {
+  /** OPT(p, birth_ai_learn). */
+  aiLearn: boolean;
+  /** equip_learn_flag(p, flag). */
+  equipLearnFlag: (of: number) => void;
+  /** equip_learn_element(p, element). */
+  equipLearnElement: (elem: number) => void;
+  /** player_of_has(p, flag). */
+  playerOfHas: (of: number) => boolean;
+  /** pf_has(p->state.pflags, pflag). */
+  playerPfHas: (pf: number) => boolean;
+  /** p->state.el_info[element].res_level. */
+  playerResLevel: (elem: number) => number;
+}
+
+/**
+ * update_smart_learn (mon-util.c L788): the monster learns an "observed"
+ * resistance or other player property (or its absence). The player always
+ * learns the corresponding rune (equip_learn_*); the monster's known_pstate is
+ * only updated under birth_ai_learn, for non-stupid monsters, with the
+ * one_in_(2) non-smart and one_in_(100) failure draws in upstream order.
+ * Robust to `element` being an arbitrary PROJ_ index, as upstream.
+ */
+export function updateSmartLearn(
+  rng: Rng,
+  mon: Monster,
+  env: SmartLearnEnv,
+  flag: number,
+  pflag: number,
+  element: number,
+): void {
+  const elementOk = element >= 0 && element < ELEM_MAX;
+
+  /* Sanity check. */
+  if (!flag && !elementOk) return;
+
+  /* Anything a monster might learn, the player should learn. */
+  if (flag) env.equipLearnFlag(flag);
+  if (elementOk) env.equipLearnElement(element);
+
+  /* Not allowed to learn. */
+  if (!env.aiLearn) return;
+
+  /* Too stupid to learn anything. */
+  if (monsterIsStupid(mon)) return;
+
+  /* Not intelligent, only learn sometimes. */
+  if (!monsterIsSmart(mon) && rng.oneIn(2)) return;
+
+  /* Analyze the knowledge; fail very rarely. */
+  if (rng.oneIn(100)) return;
+
+  /* Learn the flag. */
+  if (flag) {
+    if (env.playerOfHas(flag)) mon.knownPstate.flags.on(flag);
+    else mon.knownPstate.flags.off(flag);
+  }
+
+  /* Learn the pflag (upstream writes it with of_on/of_off; same bit ops). */
+  if (pflag) {
+    if (env.playerPfHas(pflag)) mon.knownPstate.pflags.on(pflag);
+    else mon.knownPstate.pflags.off(pflag);
+  }
+
+  /* Learn the element. */
+  if (elementOk) {
+    mon.knownPstate.elInfo[element] = env.playerResLevel(element);
+  }
+}
+
+/**
+ * randcalc(v, 0, MAXIMISE): base + dice*sides + mBonus. Level and RNG never
+ * enter the MAXIMISE branch (rng.ts damcalc / mBonusCalc), so this mirrors
+ * that arithmetic directly rather than threading an Rng through a display
+ * path (the same choice obj/object-info.ts makes for its own rvMax).
+ */
+function maximiseRandomValue(rv: RandomValue): number {
+  return rv.base + rv.dice * rv.sides + rv.mBonus;
+}
+
+/**
+ * FLAGGED ADDITION (#lore-damage): nonhp_dam (mon-spell.c L571), restricted to
+ * the MAXIMISE aspect mon_spell_lore_damage needs - deterministic, no RNG.
+ *
+ * Sums the MAXIMISE damage of every effect line except EF_TIMED_INC ("Timed
+ * effects increases don't count as damage in lore", upstream comment).
+ * EF_LASH is special-cased exactly as upstream: full damage from the race's
+ * first blow plus half from each of the rest (integer division per term,
+ * summed - not the total divided by two).
+ *
+ * Each non-LASH effect's dice is parsed fresh from its raw string and any
+ * SPELL_POWER expression rebound to `race` (the only base value monster-spell
+ * damage dice reference - see reference/lib/gamedata/monster_spell.txt),
+ * mirroring upstream's do_mon_spell / mon-cast.ts buildSpellEffectChain
+ * pattern of rebuilding the bound dice per caster rather than mutating the
+ * shared MonsterSpell record (which every race with that spell shares).
+ */
+export function monSpellNonhpDamage(
+  effects: readonly MonsterSpellEffect[],
+  race: MonsterRace,
+): number {
+  let dam = 0;
+
+  for (const effect of effects) {
+    if (effect.eff === "LASH") {
+      for (let i = 0; i < race.blows.length; i++) {
+        const blowDice = race.blows[i]!.dice;
+        if (!blowDice) continue;
+        const full = maximiseRandomValue(blowDice.randomValue());
+        dam += i === 0 ? full : Math.trunc(full / 2);
+      }
+      continue;
+    }
+
+    if (!effect.dice || effect.eff === "TIMED_INC" || effect.diceRaw === null) {
+      continue;
+    }
+
+    const dice = new Dice();
+    if (!dice.parseString(effect.diceRaw)) continue;
+    for (const x of effect.exprs) {
+      if (x.base.toUpperCase() !== "SPELL_POWER") continue;
+      const expr = new Expression();
+      expr.setBaseValue(() => race.spellPower);
+      expr.addOperationsString(x.expr);
+      dice.bindExpression(x.name, expr);
+    }
+    dam += maximiseRandomValue(dice.randomValue());
+  }
+
+  return dam;
+}

package/src/mon/steal.ts

@@ -0,0 +1,246 @@
+/**
+ * Stealing objects from a monster, ported from reference/src/mon-util.c
+ * (Angband 4.2.6): get_random_monster_object (L1405) and steal_monster_item
+ * (L1430). This is the RNG core of the rogue / PF_STEAL "steal" command
+ * (do_cmd_steal, cmd-cave.c L1016) and, upstream, of the EAT_ITEM melee blow
+ * when the attacker's target is another monster (mon-blows.c L876).
+ *
+ * The heavy RNG order is the correctness crux, so it lives here worldless (like
+ * combat/mon-melee.ts): stealMonsterItem draws every roll in strict upstream
+ * order and mutates the monster's held pile directly, delegating the
+ * player-facing world work (gold gain, pack carry, drop_near, ignore checks,
+ * the hit-and-run teleport, EF_WAKE aggro) to the injected StealEnv. The game
+ * binding (game/steal.ts) supplies that env over the live GameState.
+ *
+ * RNG draw order (mon-util.c L1430-1539), verified against the C:
+ *   1. get_random_monster_object(mon): a reservoir pick over mon->held_obj -
+ *      one_in_(i) for each non-quest-artifact held object, i counting from 1.
+ *   2. (no object) one_in_(3), then monster_wake(mon, false, 100) on success
+ *      (which draws randint0(100) for awareness).
+ *   3. monster_reaction = guard/2 + randint1(MAX(guard, 1)); the item-weight
+ *      term adds no RNG.
+ *   4. success (reaction < skill): pile_excise, then either gold gain, or a
+ *      drop_near (its own breakage / grid RNG) when the item is ignored or the
+ *      pack is full, or a plain inven_carry; then mon_dec_timed(SLEEP) (which
+ *      may draw for its save), then the hit-and-run teleport when TMD_ATT_RUN.
+ *   5. decent fail (reaction/2 < skill): monster_wake(mon, true, 50).
+ *   6. bungle (else): monster_wake(mon, true, 100), then EF_WAKE aggro.
+ *
+ * DEFERRED (noted, no RNG impact): the object knowledge bookkeeping upstream
+ * threads here - object_grab / object_see / delist_object / object_delete - is
+ * the knowledge subsystem (#24), carried by the env's carry/gainGold seams; and
+ * react_to_slay blocking the monster-thief path (midx >= 0) is deferred exactly
+ * as the EAT_ITEM blow already defers it (game/mon-side.ts / mon-cmd.ts). The
+ * mon-vs-mon EAT_ITEM path wires stealMonsterItem from game/mon-cmd.ts.
+ */
+
+import { KF } from "../generated/index.js";
+import type { Rng } from "../rng.js";
+import type { GameObject } from "../obj/object.js";
+import type { Monster } from "./monster.js";
+import { getLore } from "./lore.js";
+import type { LoreStore } from "./lore.js";
+import { monsterIsUnique } from "./predicate.js";
+import { monsterWake } from "./take-hit.js";
+import { MON_TMD } from "../generated/index.js";
+import { monDecTimed, MON_TMD_FLG_NOTIFY } from "./timed.js";
+
+/**
+ * get_random_monster_object (mon-util.c L1405): pick one object from the
+ * monster's held pile with uniform probability, skipping quest artifacts. The
+ * reservoir draw (one_in_(i), i from 1) matches upstream exactly, so the choice
+ * is the same for a given RNG stream.
+ */
+export function getRandomMonsterObject(
+  rng: Rng,
+  mon: Monster,
+): GameObject | null {
+  let pick: GameObject | null = null;
+  let i = 1;
+  for (const obj of mon.heldObj) {
+    /* Check it isn't a quest artifact. */
+    if (obj.artifact && obj.kind.kindFlags.has(KF.QUEST_ART)) continue;
+    if (rng.oneIn(i)) pick = obj;
+    i++;
+  }
+  return pick;
+}
+
+/**
+ * The world-facing operations steal_monster_item delegates, so the RNG core
+ * stays worldless. The game binding (game/steal.ts) supplies these over the
+ * live GameState; the RNG-drawing seams (dropStolen, wakeAll, hitAndRun) run at
+ * the exact point upstream draws them.
+ */
+export interface StealEnv {
+  /** msg(): route messages to the game's sink. */
+  msg(text: string): void;
+  /** monster_desc(mon, MDESC_TARG) (mon-util.c L1438): the victim's name. */
+  monName(mon: Monster): string;
+  /**
+   * monster_desc(mon, MDESC_STANDARD) (mon-util.c L1524): the re-described,
+   * capitalised name for the bungle "cries out in anger" line. Defaults to
+   * monName when absent.
+   */
+  monNameStandard?(mon: Monster): string;
+  /** player->state.skills[SKILL_STEALTH]. */
+  readonly stealthSkill: number;
+  /** adj_dex_th[player->state.stat_ind[STAT_DEX]]. */
+  readonly dexToHit: number;
+  /** player->state.speed. */
+  readonly playerSpeed: number;
+  /** player->timed[TMD_BLIND] || [TMD_CONFUSED] || [TMD_IMAGE]. */
+  readonly statusPenalty: boolean;
+  /** player->timed[TMD_ATT_RUN] (the hit-and-run stance is active). */
+  readonly attRun: boolean;
+  /** object_weight_one(obj), curses folded in. */
+  objectWeight(obj: GameObject): number;
+  /** tval_is_money(obj). */
+  isMoney(obj: GameObject): boolean;
+  /** object_desc(obj, PREFIX|FULL): the display name for messages. */
+  objectName(obj: GameObject): string;
+  /** ignore_item_ok(player, obj). */
+  isIgnored(obj: GameObject): boolean;
+  /** inven_carry_okay(obj): the pack can accept it. */
+  canCarry(obj: GameObject): boolean;
+  /** player->au += obj->pval; PR_GOLD redraw; delist / object_delete. */
+  gainGold(obj: GameObject): void;
+  /** object_grab + inven_carry(player, obj, true, true). */
+  carry(obj: GameObject): void;
+  /**
+   * drop_near(cave, &obj, 0, player->grid, true, true) then "You drop X." -
+   * the name is captured before the drop (upstream order); draws drop_near RNG.
+   */
+  dropStolen(obj: GameObject): void;
+  /** effect_simple(EF_WAKE, source_monster(mon)): aggro monsters in LOS. */
+  wakeAll?(mon: Monster): void;
+  /**
+   * The TMD_ATT_RUN hit-and-run: "You vanish into the shadows!", EF_TELEPORT
+   * "20", then clear TMD_ATT_RUN. Draws the teleport RNG.
+   */
+  hitAndRun?(): void;
+  /** monster_desc for the thief (midx >= 0 path); the race name (#25). */
+  thiefName?(midx: number): string;
+  /** monster_carry(cave, thief, obj) (midx >= 0 path). */
+  thiefCarry?(midx: number, obj: GameObject): void;
+}
+
+/** pile_excise(&mon->held_obj, obj): drop the object from the held pile. */
+function pileExcise(mon: Monster, obj: GameObject): void {
+  const at = mon.heldObj.indexOf(obj);
+  if (at >= 0) mon.heldObj.splice(at, 1);
+}
+
+/**
+ * steal_monster_item (mon-util.c L1430): the thief with index `midx` steals a
+ * random item from `mon`. `midx < 0` is the player (do_cmd_steal); `midx >= 0`
+ * is a monster thief (the EAT_ITEM blow against another monster). Every RNG
+ * draw is issued in strict upstream order; see the module header.
+ */
+export function stealMonsterItem(
+  rng: Rng,
+  lore: LoreStore,
+  mon: Monster,
+  midx: number,
+  env: StealEnv,
+): void {
+  /* Choose the victim item (drawn first, before anything else). */
+  const obj = getRandomMonsterObject(rng, mon);
+  const mName = env.monName(mon);
+
+  if (midx < 0) {
+    /* Base monster protection and player stealing skill. */
+    const unique = monsterIsUnique(mon);
+    let guard =
+      Math.trunc((mon.race.level * (unique ? 4 : 3)) / 4) +
+      mon.mspeed -
+      env.playerSpeed;
+    let stealSkill = env.stealthSkill + env.dexToHit;
+
+    /* No object. */
+    if (!obj) {
+      env.msg(`You can find nothing to steal from ${mName}.`);
+      if (rng.oneIn(3)) {
+        /* Monster notices. */
+        monsterWake(rng, mon, false, 100);
+      }
+      return;
+    }
+
+    /* Penalize some status conditions. */
+    if (env.statusPenalty) {
+      stealSkill = Math.trunc(stealSkill / 4);
+    }
+    if (mon.mTimed[MON_TMD.SLEEP]) {
+      guard = Math.trunc(guard / 2);
+    }
+
+    /* Monster base reaction, plus allowance for item weight. */
+    let monsterReaction =
+      Math.trunc(guard / 2) + rng.randint1(Math.max(guard, 1));
+    monsterReaction += Math.trunc(
+      (obj.number * env.objectWeight(obj)) / 20,
+    );
+
+    /* Try and steal. */
+    if (monsterReaction < stealSkill) {
+      const wake = 35 - env.stealthSkill;
+
+      /* Success! */
+      obj.heldMIdx = 0;
+      pileExcise(mon, obj);
+      if (env.isMoney(obj)) {
+        env.msg(`You steal ${obj.pval} gold pieces worth of treasure.`);
+        env.gainGold(obj);
+      } else {
+        /* Drop immediately if ignored, or if inventory already full to
+         * prevent pack overflow. */
+        if (env.isIgnored(obj) || !env.canCarry(obj)) {
+          env.dropStolen(obj);
+        } else {
+          env.carry(obj);
+        }
+      }
+
+      /* Track thefts. */
+      getLore(lore, mon.race).thefts++;
+
+      /* Monster wakes a little. */
+      monDecTimed(rng, mon, MON_TMD.SLEEP, wake, MON_TMD_FLG_NOTIFY);
+    } else if (Math.trunc(monsterReaction / 2) < stealSkill) {
+      /* Decent attempt, at least. */
+      const oName = env.isMoney(obj) ? "treasure" : env.objectName(obj);
+      env.msg(`You fail to steal ${oName} from ${mName}.`);
+      /* Monster wakes, may notice. */
+      monsterWake(rng, mon, true, 50);
+    } else {
+      /* Bungled it. */
+      monsterWake(rng, mon, true, 100);
+      env.msg(
+        `${(env.monNameStandard ?? env.monName)(mon)} cries out in anger!`,
+      );
+      env.wakeAll?.(mon);
+    }
+
+    /* Player hit and run. */
+    if (env.attRun) {
+      env.hitAndRun?.();
+    }
+  } else {
+    /* Monster thief (midx >= 0): mon-vs-mon EAT_ITEM (mon-cmd.ts). react_to_slay
+     * blocking the theft is DEFERRED (no RNG), as the player EAT_ITEM path. */
+    const tName = env.thiefName?.(midx) ?? "It";
+
+    if (!obj /* || react_to_slay(obj, thief) -- DEFERRED */) {
+      /* Fail to steal. */
+      env.msg(`${tName} tries to steal something from ${mName}, but fails.`);
+    } else {
+      env.msg(`${tName} steals something from ${mName}!`);
+
+      /* Steal and carry. */
+      obj.heldMIdx = 0;
+      pileExcise(mon, obj);
+      env.thiefCarry?.(midx, obj);
+    }
+  }
+}