@rpgm-tools/neo-angband-core 0.10.0

package/src/game/project-monster.ts

@@ -0,0 +1,407 @@
+/**
+ * The project_m driver, ported from reference/src/project-mon.c (Angband 4.2.6):
+ * project_m (L1328) and its appliers project_m_player_attack (L1102),
+ * project_m_monster_attack (L1034) and project_m_apply_side_effects (L1177).
+ *
+ * This is the game-layer half of the monster projection: it operates on the
+ * live GameState (monster-by-grid lookup, damage, removal), wiring together the
+ * pure effect-computation core (mon/project-mon.ts runMonsterHandler), the
+ * shared damage primitive (mon/take-hit.ts monTakeHit), and the projection
+ * behaviour data (world/projection.ts obvious / wake). It implements the
+ * onMonster seam of project() (world/project.ts).
+ *
+ * mon/ must not depend on game/, so the driver lives here (it mutates
+ * GameState). The genuinely downstream consequences are injected as hooks, so
+ * this ships and is tested before their subsystems land:
+ * - onKill / onMonsterDeath (player_kill_monster / monster_death: experience,
+ *   drops, quests - blocked on floor objects, lore, experience, quests). The
+ *   minimal removal (delete_monster_idx) is done here; the hook does the rest.
+ * - polymorph (poly_race + place_new_monster: needs monster generation).
+ * - teleport (effect_simple EF_TELEPORT: an effect handler, #18).
+ * - thrustAway (thrust_away: the cave-mutating knockback).
+ * - becomeAware / revertShape / message / messagePain / lore learning: the
+ *   knowledge, shapechange and message-list systems.
+ */
+
+import { MON_MSG, MON_TMD, PROJ } from "../generated/index.js";
+import type { Loc } from "../loc.js";
+import type { Monster } from "../mon/monster.js";
+import {
+  monsterIsCamouflaged,
+  monsterIsDestroyed,
+  monsterIsInView,
+  monsterIsUnique,
+  monsterIsVisible,
+} from "../mon/predicate.js";
+import { newMonProjectContext, runMonsterHandler } from "../mon/project-mon.js";
+import type { MonProjectContext } from "../mon/project-mon.js";
+import { monsterWake, monTakeHit } from "../mon/take-hit.js";
+import { MON_TMD_FLG_NOTIFY, monIncTimed } from "../mon/timed.js";
+import type { MonTimedMessageSink } from "../mon/timed.js";
+import { PROJECT } from "../world/project.js";
+import type { MonsterHitResult } from "../world/project.js";
+import type { ProjectionInfo } from "../world/projection.js";
+import { arenaInterceptDeath, deleteMonster } from "./context.js";
+import type { GameState } from "./context.js";
+
+/** The player-facing / downstream consequences the driver defers to the caller. */
+export interface ProjectMonsterHooks {
+  /**
+   * add_monster_message(mon, msg_code, delay): queue a message about the monster
+   * (by MON_MSG index). `delay` is upstream's third argument (what_delay,
+   * mon-msg.c:238), not a comma flag. When `damage` is given the caller must use
+   * add_monster_message_show_damage (mon-msg.c:288) and append " (N)".
+   */
+  message?: (
+    mon: Monster,
+    msg: number,
+    delay?: boolean,
+    damage?: number,
+  ) => void;
+  /**
+   * message_pain: a graded "it is hurt" message from the damage amount. With
+   * `showDamage` the caller must use message_pain_show_damage (mon-msg.c:132).
+   */
+  messagePain?: (mon: Monster, dam: number, showDamage?: boolean) => void;
+  /**
+   * OPT(player, show_damage) (list-options.h): project_m_player_attack combines
+   * it with origin.what == SRC_PLAYER into its `display_dam`
+   * (project-mon.c:1111-1112), which selects the *_show_damage message calls.
+   */
+  showDamage?: boolean;
+  /** Timed-effect messages emitted while applying side-effect timers. */
+  timedMessage?: MonTimedMessageSink;
+  /** player_kill_monster: experience, drops, quests (removal is done here). */
+  onKill?: (mon: Monster) => void;
+  /** monster_death for a monster-vs-monster kill (drops; removal done here). */
+  onMonsterDeath?: (mon: Monster) => void;
+  /** become_aware: reveal a camouflaged monster. */
+  becomeAware?: (mon: Monster) => void;
+  /** monster_revert_shape: a shapechanged monster reverts on death. */
+  revertShape?: (mon: Monster) => void;
+  /** rf_on(lore): learn a race flag when seen. */
+  learnRaceFlag?: (mon: Monster, flag: number) => void;
+  /** rsf_on(lore): learn a spell flag when seen. */
+  learnSpellFlag?: (mon: Monster, flag: number) => void;
+  /** multiply_monster (PROJ_MON_CLONE). */
+  multiplyMonster?: (mon: Monster) => boolean;
+  /**
+   * poly_race + place_new_monster: replace the monster with a polymorphed one.
+   * Returns the new monster, or null if the polymorph failed / is unmodelled.
+   */
+  polymorph?: (mon: Monster, power: number, directPoly: boolean) => Monster | null;
+  /** effect_simple EF_TELEPORT: teleport the monster up to `distance` grids. */
+  teleport?: (mon: Monster, distance: number) => void;
+  /** thrust_away(centre, target, gridsAway): knock a monster back (PROJ_FORCE). */
+  thrustAway?: (centre: Loc, target: Loc, gridsAway: number) => void;
+  /** update_mon + square_light_spot + PR_MONSTER: refresh a surviving monster. */
+  onUpdate?: (mon: Monster) => void;
+  /** clear the player's TMD_COVERTRACKS once player damage lands. */
+  coverTracksBroken?: () => void;
+}
+
+/** The projection source, resolved for the driver. */
+export interface ProjectMonsterSource {
+  /** origin.what == SRC_PLAYER (routes to project_m_player_attack). */
+  isPlayer: boolean;
+  /** origin.which.monster for SRC_MONSTER (0 otherwise). */
+  monster: number;
+  /** origin_get_loc(origin): thrust-away centre. */
+  grid: Loc;
+  /** player_has(PF_CHARM): boosts effects vs animals. */
+  charm: boolean;
+}
+
+/** Everything the per-grid driver needs, built once per project() call. */
+export interface ProjectMonsterCtx {
+  state: GameState;
+  projections: readonly ProjectionInfo[];
+  origin: ProjectMonsterSource;
+  hooks: ProjectMonsterHooks;
+}
+
+const NO_HIT: MonsterHitResult = { didHit: false, wasObvious: false };
+
+/**
+ * project_m for one grid: affect the monster (if any) in `grid` with projection
+ * `typ` for `dam` damage at distance `dist`. Returns project_m's out-parameters
+ * (did_hit / was_obvious, plus the monster's post-hit grid). Suitable as the
+ * onMonster hook of project().
+ */
+export function projectMonster(
+  pctx: ProjectMonsterCtx,
+  dist: number,
+  grid: Loc,
+  dam: number,
+  typ: number,
+  flg: number,
+): MonsterHitResult {
+  const { state, hooks, origin } = pctx;
+
+  /* Walls protect monsters. */
+  if (!state.chunk.isPassable(grid)) return NO_HIT;
+
+  const mIdx = state.chunk.mon(grid);
+  /* No monster here. */
+  if (mIdx <= 0) return NO_HIT;
+
+  /* Never affect the projecting monster. */
+  if (origin.monster !== 0 && origin.monster === mIdx) return NO_HIT;
+
+  const mon = state.monsters[mIdx];
+  if (!mon) return NO_HIT;
+
+  /* See visible monsters (camouflaged ones only when in view). */
+  let seen = monsterIsCamouflaged(mon)
+    ? monsterIsInView(mon)
+    : monsterIsVisible(mon);
+
+  /* Breathers may not blast members of the same race. */
+  if (origin.monster !== 0 && flg & PROJECT.SAFE) {
+    const caster = state.monsters[origin.monster];
+    if (!caster) return NO_HIT;
+    if (caster.race === mon.race) return NO_HIT;
+  }
+
+  const ctx = newMonProjectContext(state.rng, mon, typ, dam, {
+    originIsMonster: origin.monster !== 0,
+    r: dist,
+    grid,
+    charm: origin.charm,
+    seen,
+    obvious: (flg & PROJECT.AWARE) !== 0,
+    hooks: {
+      ...(hooks.learnRaceFlag ? { learnRaceFlag: hooks.learnRaceFlag } : {}),
+      ...(hooks.learnSpellFlag ? { learnSpellFlag: hooks.learnSpellFlag } : {}),
+      ...(hooks.multiplyMonster
+        ? { multiplyMonster: hooks.multiplyMonster }
+        : {}),
+      ...(hooks.timedMessage ? { onMessage: hooks.timedMessage } : {}),
+    },
+  });
+
+  /* Some monsters get "destroyed" rather than slain. */
+  if (monsterIsDestroyed(mon)) ctx.dieMsg = MON_MSG.DESTROYED;
+
+  /* Reveal a camouflaged monster that stopped an effect. */
+  if (flg & PROJECT.STOP && monsterIsCamouflaged(mon) && monsterIsInView(mon)) {
+    hooks.becomeAware?.(mon);
+    if (monsterIsVisible(mon)) {
+      seen = true;
+      ctx.seen = true;
+    }
+  }
+
+  /* Force obviousness for certain projection types if seen. */
+  const info = pctx.projections[typ];
+  if (info && info.obvious && ctx.seen) ctx.obvious = true;
+
+  /* Run the type handler (accumulates damage / timers / poly / teleport). */
+  runMonsterHandler(ctx);
+
+  /* PROJ_FORCE thrust happens in the handler upstream, before wake / damage. */
+  if (ctx.thrustGridsAway > 0) {
+    hooks.thrustAway?.(origin.grid, grid, ctx.thrustGridsAway);
+  }
+
+  /* Wake the monster if the projection type forces it. */
+  if (info && info.wake) monsterWake(state.rng, mon, false, 100);
+
+  /* Absolutely no effect. */
+  if (ctx.skipped) return NO_HIT;
+
+  /* Apply damage, based on who did the damage. */
+  const monDied = origin.monster !== 0
+    ? monsterAttack(pctx, ctx, mIdx, seen)
+    : playerAttack(pctx, ctx, mIdx, seen);
+
+  if (!monDied) applySideEffects(pctx, ctx, typ, flg, seen);
+
+  /* The side-effect appliers can change ctx.mon (polymorph) or remove it. */
+  const finalMon = ctx.mon;
+  if (finalMon && !monDied) hooks.onUpdate?.(finalMon);
+
+  return {
+    didHit: true,
+    wasObvious: ctx.obvious,
+    grid: finalMon ? finalMon.grid : grid,
+  };
+}
+
+/**
+ * project_m_player_attack: damage from the player (or a trap), routed through
+ * mon_take_hit so death, fear and waking match every other player attack.
+ */
+function playerAttack(
+  pctx: ProjectMonsterCtx,
+  ctx: MonProjectContext,
+  mIdx: number,
+  seen: boolean,
+): boolean {
+  const { state, hooks } = pctx;
+  const mon = ctx.mon;
+  const dam = ctx.dam;
+
+  /* display_dam (project-mon.c:1111-1112): only the PLAYER's own damage gets
+   * the " (N)" suffix, and only with OPT(player, show_damage) on - a trap also
+   * routes here (origin.what == SRC_TRAP) and must stay bare. */
+  const displayDam = pctx.origin.isPlayer && (hooks.showDamage ?? false);
+
+  /* Lethal blow: show the death message before mon_take_hit (which is passed
+   * an empty note, so it prints none, keeping message order correct). */
+  if (dam > mon.hp) {
+    hooks.revertShape?.(mon);
+    const dieMsg = seen ? ctx.dieMsg : MON_MSG.MORIA_DEATH;
+    /* add_monster_message_show_damage vs add_monster_message
+     * (project-mon.c:1127-1132). */
+    if (displayDam) hooks.message?.(mon, dieMsg, false, dam);
+    else hooks.message?.(mon, dieMsg);
+  }
+
+  let died = false;
+  let fear = false;
+  if (dam) {
+    const res = monTakeHit(state.rng, mon, dam, "", {
+      onKill: (m) => {
+        hooks.onKill?.(m);
+        deleteMonster(state, mIdx);
+      },
+      ...(hooks.becomeAware ? { becomeAware: hooks.becomeAware } : {}),
+      ...(hooks.coverTracksBroken
+        ? { coverTracksBroken: hooks.coverTracksBroken }
+        : {}),
+      /* Single combat: the kill waits for the arena exit. */
+      ...(state.arenaLevel
+        ? { onArenaDeath: (m: Monster) => void arenaInterceptDeath(state, m) }
+        : {}),
+    });
+    died = res.died;
+    fear = res.fear;
+  }
+
+  if (!died) {
+    /* project-mon.c:1145-1159: the display_dam branch swaps both the specific
+     * hurt message and the fallback pain message for their damage-showing
+     * twins. The FLEE_IN_TERROR line never shows damage. */
+    if (seen && ctx.hurtMsg !== MON_MSG.NONE) {
+      if (displayDam) hooks.message?.(mon, ctx.hurtMsg, false, dam);
+      else hooks.message?.(mon, ctx.hurtMsg);
+    } else if (dam > 0) {
+      hooks.messagePain?.(mon, dam, displayDam);
+    }
+    if (seen && fear) hooks.message?.(mon, MON_MSG.FLEE_IN_TERROR, true);
+  }
+
+  return died;
+}
+
+/**
+ * project_m_monster_attack: damage from another monster. Like mon_take_hit but
+ * without the player-oriented handling; uniques are reduced to but not killed.
+ */
+function monsterAttack(
+  pctx: ProjectMonsterCtx,
+  ctx: MonProjectContext,
+  mIdx: number,
+  seen: boolean,
+): boolean {
+  const { state, hooks } = pctx;
+  const mon = ctx.mon;
+  let dam = ctx.dam;
+
+  /* "Unique" or arena monsters can only be killed by the player. */
+  if ((monsterIsUnique(mon) || state.arenaLevel) && dam > mon.hp) dam = mon.hp;
+
+  /* Wake the monster up, don't notice the player. */
+  monsterWake(state.rng, mon, false, 0);
+
+  mon.hp -= dam;
+
+  if (mon.hp < 0) {
+    hooks.revertShape?.(mon);
+    const dieMsg = seen ? ctx.dieMsg : MON_MSG.MORIA_DEATH;
+    hooks.message?.(mon, dieMsg);
+    hooks.onMonsterDeath?.(mon);
+    deleteMonster(state, mIdx);
+    return true;
+  }
+
+  if (!monsterIsCamouflaged(mon)) {
+    if (ctx.hurtMsg !== MON_MSG.NONE && seen) {
+      hooks.message?.(mon, ctx.hurtMsg);
+    } else if (dam > 0) {
+      hooks.messagePain?.(mon, dam);
+    }
+  }
+
+  return false;
+}
+
+/**
+ * project_m_apply_side_effects: polymorph, teleport, or apply the accumulated
+ * timed effects. Polymorph and teleport are checked first since they may
+ * invalidate applying status effects to a changed monster.
+ */
+function applySideEffects(
+  pctx: ProjectMonsterCtx,
+  ctx: MonProjectContext,
+  typ: number,
+  _flg: number,
+  seen: boolean,
+): void {
+  const { state, hooks } = pctx;
+  const mon = ctx.mon;
+
+  if (ctx.doPoly) {
+    /* Uniques cannot be polymorphed, nor can anything on an arena level
+     * (project-mon.c L1197: monster_is_unique(mon) || player->arena_level). PR3. */
+    if (monsterIsUnique(mon) || state.arenaLevel) {
+      if (seen) hooks.message?.(mon, MON_MSG.UNAFFECTED);
+      return;
+    }
+
+    if (seen) ctx.obvious = true;
+
+    /* Saving throw: damage-based for direct poly, random for chaos. */
+    const savelvl =
+      typ === PROJ.MON_POLY
+        ? state.rng.randint1(Math.max(1, ctx.doPoly - 10)) + 10
+        : state.rng.randint1(90);
+    if (mon.race.level > savelvl) {
+      if (seen) {
+        hooks.message?.(
+          mon,
+          typ === PROJ.MON_POLY ? MON_MSG.MAINTAIN_SHAPE : MON_MSG.UNAFFECTED,
+        );
+      }
+      return;
+    }
+
+    const newMon =
+      hooks.polymorph?.(mon, ctx.doPoly, typ === PROJ.MON_POLY) ?? null;
+    if (newMon && newMon !== mon) {
+      if (seen) hooks.message?.(mon, MON_MSG.CHANGE);
+      ctx.mon = newMon;
+    } else if (seen) {
+      hooks.message?.(mon, MON_MSG.MAINTAIN_SHAPE);
+    }
+  } else if (ctx.teleportDistance > 0) {
+    hooks.teleport?.(mon, ctx.teleportDistance);
+    /* Wake the monster up, don't notice the player. */
+    monsterWake(state.rng, mon, false, 0);
+  } else {
+    for (let i = 0; i < MON_TMD.MAX; i++) {
+      if (ctx.monTimed[i]! > 0) {
+        monIncTimed(
+          state.rng,
+          mon,
+          i,
+          ctx.monTimed[i]!,
+          ctx.flag | MON_TMD_FLG_NOTIFY,
+          hooks.timedMessage,
+        );
+        if (seen) ctx.obvious = true;
+      }
+    }
+  }
+}

package/src/game/project-obj.ts

@@ -0,0 +1,298 @@
+/**
+ * Projection effects on objects, ported from reference/src/project-obj.c
+ * (Angband 4.2.6): the project_o driver over the floor pile at a grid, the
+ * per-projection object handlers (elemental destruction driven by the
+ * EL_INFO_HATES / EL_INFO_IGNORE bits), and inven_damage (the pack-side
+ * casualty roll elemental hits on the player make).
+ *
+ * KILL_TRAP's chest unlock (is_locked_chest / unlock_chest), the mimic reveal
+ * on object destruction (obj->mimicking_m_idx -> become_aware via
+ * state.becomeAware) and the protected_obj parameter (the object that created
+ * the projection, so it does not destroy itself) are ported here.
+ *
+ * Knowledge / ignore integration (gap 6.12, C project-obj.c L86-90, L146,
+ * L537, L546-569):
+ * - inven_damage's obj->known->to_h / to_d / to_a writes (L86-90, L103-104) are
+ *   subsumed by the on-demand known shadow: objectKnownShadow reads the live
+ *   obj->to_* gated by p->obj_k, so decrementing them here is reflected in every
+ *   later describe without a separate twin write (there is no persistent twin to
+ *   update, and no known twin to object_delete on destruction).
+ * - inven_damage now labels the casualty with gear_to_label (L143) and project_o
+ *   gates its "unaffected" / destruction / "Click!" messages on
+ *   ignore_item_ok (state.isIgnored, L363-364, L546-569). square_isseen still
+ *   stands in for the obj->known visibility half, matching the rest of this
+ *   driver (the persistent floor twin is game/known.ts' reduced glyph memory).
+ */
+
+import type { Loc } from "../loc.js";
+import { ELEM, PROJ } from "../generated/index.js";
+import { EL_INFO_HATES, EL_INFO_IGNORE } from "../obj/types.js";
+import type { GameObject } from "../obj/object.js";
+import { tvalIsAmmo, tvalIsArmor, tvalIsRod, tvalIsWeapon } from "../obj/object.js";
+import { isLockedChest, unlockChest } from "../obj/chest.js";
+import { ODESC } from "../obj/desc.js";
+import { squareIsSeen } from "../world/view.js";
+import type { GameState } from "./context.js";
+import { describeObject } from "./describe.js";
+import { floorExcise, floorPile } from "./floor.js";
+import { gearObjectForUse, gearToLabel } from "./gear.js";
+
+/**
+ * gear_to_label (obj-gear.c:443) lives in game/gear.ts, beside the Gear it reads.
+ * Re-exported here because inven_damage's own callers import it from this module;
+ * equipment is exempt from inven_damage, so the two-argument form is all it needs.
+ */
+export { gearToLabel };
+
+/** The world seams project_o/project_f need beyond the GameState. */
+export interface ProjectWorldEnv {
+  msg?(text: string): void;
+  /**
+   * protected_obj (project-obj.c L537): the object that created the
+   * projection, which must not destroy itself. Absent when the projection has
+   * no object source (the common case; no live caller projects from an object
+   * yet).
+   */
+  protectedObj?: GameObject;
+}
+
+/** VERB_AGREEMENT over an object stack. */
+function verbAgree(n: number, singular: string, plural: string): string {
+  return n > 1 ? plural : singular;
+}
+
+/** One handler outcome (project_object_handler_context_t's out fields). */
+interface ObjHandlerResult {
+  doKill: boolean;
+  ignore: boolean;
+  noteKill: string | null;
+}
+
+/** project_object_elemental: destruction gated by the HATES/IGNORE bits. */
+function elemental(
+  obj: GameObject,
+  out: ObjHandlerResult,
+  element: number,
+  singular: string,
+  plural: string,
+): void {
+  const info = obj.elInfo[element];
+  if (info && info.flags & EL_INFO_HATES) {
+    out.doKill = true;
+    out.noteKill = verbAgree(obj.number, singular, plural);
+    out.ignore = (info.flags & EL_INFO_IGNORE) !== 0;
+  }
+}
+
+/** The object handler for one projection type (null = no object effect). */
+function runObjectHandler(typ: number, obj: GameObject): ObjHandlerResult {
+  const out: ObjHandlerResult = { doKill: false, ignore: false, noteKill: null };
+  switch (typ) {
+    case PROJ.ACID:
+      elemental(obj, out, ELEM.ACID, "melts", "melt");
+      break;
+    case PROJ.ELEC:
+      elemental(obj, out, ELEM.ELEC, "is destroyed", "are destroyed");
+      break;
+    case PROJ.FIRE:
+      elemental(obj, out, ELEM.FIRE, "burns up", "burn up");
+      break;
+    case PROJ.COLD:
+      elemental(obj, out, ELEM.COLD, "shatters", "shatter");
+      break;
+    case PROJ.SOUND:
+      elemental(obj, out, ELEM.SOUND, "shatters", "shatter");
+      break;
+    case PROJ.SHARD:
+      elemental(obj, out, ELEM.SHARD, "shatters", "shatter");
+      break;
+    case PROJ.ICE:
+      elemental(obj, out, ELEM.ICE, "shatters", "shatter");
+      break;
+    case PROJ.FORCE:
+      elemental(obj, out, ELEM.FORCE, "shatters", "shatter");
+      break;
+    case PROJ.PLASMA:
+      elemental(obj, out, ELEM.FIRE, "burns up", "burn up");
+      elemental(obj, out, ELEM.ELEC, "is destroyed", "are destroyed");
+      break;
+    case PROJ.METEOR:
+      elemental(obj, out, ELEM.FIRE, "burns up", "burn up");
+      elemental(obj, out, ELEM.COLD, "shatters", "shatter");
+      break;
+    case PROJ.MANA:
+      /* Mana -- destroys everything. */
+      out.doKill = true;
+      out.noteKill = verbAgree(obj.number, "is destroyed", "are destroyed");
+      break;
+    /* KILL_TRAP's chest unlock is handled in projectObject (it mutates the
+     * object and messages instead of destroying it). Every other projection
+     * has no object effect, exactly as the upstream stubs. */
+    default:
+      break;
+  }
+  return out;
+}
+
+/**
+ * project_o: affect every object in the pile at `grid` (PROJECT_ITEM).
+ * Returns whether anything the player can see happened.
+ */
+export function projectObject(
+  state: GameState,
+  _r: number,
+  grid: Loc,
+  _dam: number,
+  typ: number,
+  env: ProjectWorldEnv = {},
+): boolean {
+  let obvious = false;
+
+  /* Scan a snapshot: destruction mutates the pile. */
+  for (const obj of [...floorPile(state, grid)]) {
+    /* KILL_TRAP unlocks a locked chest instead of destroying it. */
+    if (typ === PROJ.KILL_TRAP) {
+      if (isLockedChest(obj)) {
+        unlockChest(obj);
+        /* project_object_handler_KILL_TRAP L363-364: obj->known &&
+         * !ignore_item_ok(player, obj). The chest's known->pval reveal (L365)
+         * rides the on-demand shadow; squareIsSeen stands in for obj->known. */
+        if (
+          squareIsSeen(state.chunk, grid) &&
+          !(state.isIgnored?.(obj) ?? false)
+        ) {
+          env.msg?.("Click!");
+          obvious = true;
+        }
+      }
+      continue;
+    }
+
+    const { doKill: rawKill, ignore, noteKill } = runObjectHandler(typ, obj);
+    /* protected_obj never destroys itself. */
+    const doKill = rawKill && obj !== env.protectedObj;
+    if (!doKill) continue;
+
+    /* Upstream gates the observed effect on obj->known && !ignore_item_ok(player,
+     * obj) && square_isseen (L546-547); squareIsSeen stands in for obj->known. */
+    const notIgnored = !(state.isIgnored?.(obj) ?? false);
+    const observed = squareIsSeen(state.chunk, grid) && notIgnored;
+    if (observed) obvious = true;
+
+    if (obj.artifact || ignore) {
+      /* Artifacts and ignoring objects resist (L554-560). */
+      if (observed) {
+        env.msg?.(
+          `The ${describeObject(state, obj, ODESC.BASE)} ${verbAgree(obj.number, "is", "are")} unaffected!`,
+        );
+      }
+    } else if (obj.mimickingMIdx) {
+      /* Reveal a mimic instead of destroying its fake item (L561-565). */
+      if (obvious) {
+        const mon = state.monsters[obj.mimickingMIdx];
+        if (mon) state.becomeAware?.(mon);
+      }
+    } else {
+      /* Describe the destruction if it is observed (L566-571). */
+      if (observed && noteKill) {
+        env.msg?.(`The ${describeObject(state, obj, ODESC.BASE)} ${noteKill}!`);
+      }
+      floorExcise(state, grid, obj);
+    }
+  }
+
+  return obvious;
+}
+
+/**
+ * inven_damage (project-obj.c L42): give every vulnerable pack item a shot
+ * at destruction on an elemental hit. `cperc` is in hundredths of a percent
+ * (a 1-in-10000 roll per item). Weapons and armor are damaged (to_h/to_d or
+ * to_a decremented) instead of destroyed; rods quarter the chance.
+ * Returns the number of items destroyed.
+ */
+export function invenDamage(
+  state: GameState,
+  typ: number,
+  cperc: number,
+  env: ProjectWorldEnv = {},
+): number {
+  if (cperc <= 0) return 0;
+  const player = state.actor.player;
+  const gear = state.gear;
+  let killed = 0;
+
+  /* Scan a snapshot of the pack (equipment is exempt). */
+  for (const handle of [...gear.pack]) {
+    const obj = gear.store.get(handle);
+    if (!obj) continue;
+    if (obj.artifact) continue; /* for now, skip artifacts */
+
+    const info = obj.elInfo[typ];
+    if (!info || !(info.flags & EL_INFO_HATES) || info.flags & EL_INFO_IGNORE) {
+      continue;
+    }
+
+    let chance = cperc;
+    let damage = false;
+
+    if (tvalIsWeapon(obj.tval) && !tvalIsAmmo(obj.tval)) {
+      if (state.rng.randint0(10000) < cperc) {
+        /* obj->to_h-- / obj->to_d-- (L85, L88). The known-twin writes at L86-90
+         * (gated on p->obj_k->to_h / to_d) are subsumed by the on-demand shadow,
+         * which reads the live obj->to_* under the same p->obj_k gate. */
+        obj.toH--;
+        obj.toD--;
+        damage = true;
+      } else {
+        continue;
+      }
+    } else if (tvalIsArmor(obj.tval)) {
+      if (state.rng.randint0(10000) < cperc) {
+        /* obj->to_a-- (L102); the L103-104 known->to_a write is likewise
+         * subsumed by the on-demand shadow. */
+        obj.toA--;
+        damage = true;
+      } else {
+        continue;
+      }
+    } else if (tvalIsRod(obj.tval)) {
+      chance = Math.trunc(chance / 4);
+    }
+
+    /* Count the casualties (a damaged stack counts whole). */
+    let amt = 0;
+    if (damage) {
+      amt = obj.number;
+    } else {
+      for (let j = 0; j < obj.number; j++) {
+        if (state.rng.randint0(10000) < chance) amt++;
+      }
+    }
+    if (!amt) continue;
+
+    const prefix =
+      obj.number > 1
+        ? amt === obj.number
+          ? "All of y"
+          : amt > 1
+            ? "Some of y"
+            : "One of y"
+        : "Y";
+    /* "%sour %s (%c) %s %s!" (L139-145): the (%c) is gear_to_label. */
+    const label = gearToLabel(gear, handle);
+    env.msg?.(
+      `${prefix}our ${describeObject(state, obj, ODESC.BASE)} (${label}) ${amt > 1 ? "were" : "was"} ${
+        damage ? "damaged" : "destroyed"
+      }!`,
+    );
+
+    if (damage) continue;
+
+    /* Destroy amt items (the detached split is discarded). */
+    gearObjectForUse(gear, player, handle, amt);
+    killed += amt;
+  }
+
+  return killed;
+}