@rpgm-tools/neo-angband-core 0.19.0 → 0.20.0

package/src/game/context.ts

@@ -805,6 +805,37 @@ export interface GameState {
    * from a mod's register(), is dispatched to on the next projection.
    */
   projectionHandlers?: import("./projection-handlers.js").ProjectionHandlerRegistry;
+  /**
+   * The verb "Really <verb> <the object>? " uses, keyed by command code
+   * (cmd.ts). wireGame seeds one per game with core's, and a mod names the verb
+   * for its OWN command through ModRegistryHost.commands.setVerb
+   * ("registry:command") - COMMAND_INFO is keyed by the closed CommandCode
+   * union, so a mod's code could never have had one.
+   *
+   * Per game, for the same reason as blowEffects: one character's mod verb must
+   * not leak into the next character's game. A UI STRING and nothing else; the
+   * command's behaviour still lives in the ActionRegistry.
+   */
+  commandVerbs?: import("../cmd.js").CommandVerbTable;
+  /**
+   * The second character screen's two ui-entry tables - the nine value
+   * COMBINERS and the six renderer BACKENDS - seeded per game and reached by a
+   * mod through ModRegistryHost.uiEntry ("registry:ui-entry").
+   *
+   * `characterGrid` and `equipCmpSummary` read this field at the moment they
+   * compute a row, and resolve BY NAME against it, so a combiner or backend
+   * installed later - from a mod's register() - is dispatched to the next time
+   * either screen opens. Nothing stores the resolved handler, and nothing
+   * stores a slot: the 1-based combiner index and 0..5 backend index this
+   * replaced were coordinates into core's own tables, which a registered
+   * handler has none of.
+   *
+   * Optional only because the headless harnesses build a GameState without one;
+   * ui-entry then resolves against core's nine and six, which is stock
+   * behaviour, and a mod can never reach that fallback because the facade
+   * refuses to register when the host wired no registry.
+   */
+  uiEntry?: import("./ui-entry-registry.js").UiEntryRegistry;
   /**
    * Named boolean "mod rule" flags: the player's per-patch choices, resolved by
    * the HOST from each enabled mod's manifest `rules` against their saved Fixes

package/src/game/display.ts

@@ -73,11 +73,36 @@ export interface DisplayRun {
   color: number;
 }
 
+/**
+ * The numbers behind a display field, for a consumer that is not going to draw
+ * the text.
+ *
+ * Upstream has no such thing: prt_hp formats "HP   20/  20" and the number is
+ * gone. The port's runs preserved that exactly, which is right for the faithful
+ * terminal and useless to anything else - a replacement HUD that wants to draw
+ * hit points as a proportional bar had to parse a rendering, and parsing a
+ * rendering is how a mod ends up broken by a pref file (MOD_REACH gap 21).
+ *
+ * ONE CONVENTION, and it is the whole point of the type: `current` and `max`
+ * together mean THIS IS A PROPORTION and `current / max` is meaningful. A field
+ * that has two numbers which are not a ratio must not use those two names -
+ * a stat's 18/118 encoding is not 15% of anything, so it publishes `use`, `cur`
+ * and `max` and a bar-drawing consumer correctly finds no proportion to draw.
+ * Every other key is a plain named quantity, documented where it is produced.
+ *
+ * Absent means "no number here", never zero: a monster health bar reads
+ * `[----------]` when the monster is unseen, and the honest answer for its
+ * current hit points is that this display does not know them.
+ */
+export type DisplayValues = Readonly<Record<string, number>>;
+
 /** One computed sidebar field: its handler key and its ordered runs. */
 export interface SidebarField {
   /** The side_handlers[] prt_* name minus the "prt_" prefix. */
   key: string;
   runs: DisplayRun[];
+  /** The numbers this field's text was formatted from, where it has any. */
+  values?: DisplayValues;
 }
 
 /** One computed status-line indicator: its handler key and its runs. */
@@ -85,6 +110,8 @@ export interface StatusIndicator {
   /** The status_handlers[] prt_* name minus the "prt_" prefix. */
   key: string;
   runs: DisplayRun[];
+  /** The numbers this indicator's text was formatted from, where it has any. */
+  values?: DisplayValues;
 }
 
 /**
@@ -441,6 +468,23 @@ function statRuns(player: Player, stat: number, deps: ResolvedDeps): DisplayRun[
   ];
 }
 
+/**
+ * The three numbers behind one stat row.
+ *
+ * NOT `current`/`max`: `use` is the internal 18/xx encoding, where 118 means
+ * 18/100 and is one point above 117. A bar drawn from `use / max` would report
+ * an 18/100 character as 15% of a maxed one. The names say what each number is
+ * and leave the arithmetic to whoever knows what the encoding means (`cnvStat`
+ * is exported for exactly that).
+ */
+function statValues(player: Player, stat: number, deps: ResolvedDeps): DisplayValues {
+  return {
+    use: deps.statUse[stat] ?? 0,
+    cur: player.statCur[stat] ?? 0,
+    max: player.statMax[stat] ?? 0,
+  };
+}
+
 /** prt_level (ui-display.c L207). */
 function levelRuns(player: Player): DisplayRun[] {
   const value = rjust(player.lev, 6);
@@ -459,11 +503,7 @@ function levelRuns(player: Player): DisplayRun[] {
  */
 function expRuns(player: Player): DisplayRun[] {
   const levMax = player.lev === PY_MAX_LEVEL;
-  let xp = player.exp;
-  if (!levMax) {
-    const base = player_exp[player.lev - 1] ?? 0;
-    xp = Math.trunc((base * player.expFactor) / 100) - player.exp;
-  }
+  const xp = levMax ? player.exp : expAdvance(player);
   const value = rjust(xp, 8);
   const atMax = player.exp >= player.maxExp;
   const label = levMax ? (atMax ? "EXP" : "Exp") : atMax ? "NXT" : "Nxt";
@@ -473,6 +513,20 @@ function expRuns(player: Player): DisplayRun[] {
   ];
 }
 
+/**
+ * The experience prt_exp counts DOWN to the next level (L232-243), or 0 at
+ * PY_MAX_LEVEL where the field shows the total instead.
+ *
+ * Shared by the text and the numbers so the two cannot part: this used to be
+ * inline in expRuns, and a second copy computing it for `values` would be a
+ * transcription of the same formula sitting one screen away from the original.
+ */
+function expAdvance(player: Player): number {
+  if (player.lev === PY_MAX_LEVEL) return 0;
+  const base = player_exp[player.lev - 1] ?? 0;
+  return Math.trunc((base * player.expFactor) / 100) - player.exp;
+}
+
 /** prt_gold (ui-display.c L256). */
 function goldRuns(player: Player): DisplayRun[] {
   return [
@@ -523,10 +577,19 @@ function hpRuns(player: Player, deps: ResolvedDeps): DisplayRun[] {
   ];
 }
 
+/**
+ * Whether this character HAS mana - prt_sp's own gate (L333-336), shared so the
+ * blank field and the absent numbers can never disagree. A warrior has no spell
+ * points, which is not the same fact as having zero of them.
+ */
+function hasMana(player: Player): boolean {
+  const magic = player.cls.magic;
+  return Boolean(magic.totalSpells) && player.lev >= magic.spellFirst;
+}
+
 /** prt_sp (ui-display.c L332): empty unless the class has mana at this level. */
 function spRuns(player: Player, deps: ResolvedDeps): DisplayRun[] {
-  const magic = player.cls.magic;
-  if (!magic.totalSpells || player.lev < magic.spellFirst) {
+  if (!hasMana(player)) {
     /* An experience-drain clear (L344) leaves the field blank either way. */
     return [];
   }
@@ -538,6 +601,23 @@ function spRuns(player: Player, deps: ResolvedDeps): DisplayRun[] {
   ];
 }
 
+/**
+ * The tracked monster's hit points, but ONLY when the bar is showing them.
+ *
+ * prt_health_aux draws `[----------]` for a monster that is unseen, dead or
+ * being hallucinated (L433-441), and the honest answer for its current hit
+ * points in that state is that this display does not know them. Returning
+ * `{ current: 0, max: 1 }` there would draw an empty bar that reads as "nearly
+ * dead" - a wrong number is worse than an absent one.
+ */
+function healthValues(player: Player, deps: ResolvedDeps): DisplayValues | undefined {
+  const mon = deps.healthWho;
+  if (!mon) return undefined;
+  const image = (player.timed[TMD.IMAGE] ?? 0) > 0;
+  if (!monsterIsVisible(mon) || image || mon.hp < 0) return undefined;
+  return { current: mon.hp, max: mon.maxhp };
+}
+
 /** prt_health / prt_health_aux (ui-display.c L425). */
 function healthRuns(player: Player, deps: ResolvedDeps): DisplayRun[] {
   const mon = deps.healthWho;
@@ -674,25 +754,55 @@ export function sidebarModel(
   const d = resolveDeps(state, deps);
   const player = state.actor.player;
   const shape = playerIsShapechanged(player);
+  const combat = state.actor.knownCombat;
+  const health = healthValues(player, d);
+  const mana = hasMana(player);
+  /* `current`/`max` ONLY where the ratio means something (see DisplayValues):
+     hp, sp and the monster health bar are proportions and nothing else here is.
+     A stat's 18/118 encoding and a drained character's level are two numbers
+     apiece that a bar would misdraw, so they publish their own names. */
   return [
     { key: "race", runs: field(shape ? "" : player.race.name) },
     { key: "title", runs: field(fmtTitle(player, d)) },
     { key: "class", runs: field(shape ? "" : player.cls.name) },
-    { key: "level", runs: levelRuns(player) },
-    { key: "exp", runs: expRuns(player) },
-    { key: "gold", runs: goldRuns(player) },
+    { key: "level", runs: levelRuns(player), values: { level: player.lev, maxLevel: player.maxLev } },
+    {
+      key: "exp",
+      runs: expRuns(player),
+      values: { exp: player.exp, maxExp: player.maxExp, advance: expAdvance(player) },
+    },
+    { key: "gold", runs: goldRuns(player), values: { au: player.au } },
     { key: "equippy", runs: equippyRuns(state, d) },
-    { key: "str", runs: statRuns(player, STAT.STR, d) },
-    { key: "int", runs: statRuns(player, STAT.INT, d) },
-    { key: "wis", runs: statRuns(player, STAT.WIS, d) },
-    { key: "dex", runs: statRuns(player, STAT.DEX, d) },
-    { key: "con", runs: statRuns(player, STAT.CON, d) },
-    { key: "ac", runs: acRuns(state) },
-    { key: "hp", runs: hpRuns(player, d) },
-    { key: "sp", runs: spRuns(player, d) },
-    { key: "health", runs: healthRuns(player, d) },
-    { key: "speed", runs: speedRuns(state, d) },
-    { key: "depth", runs: depthRuns(state) },
+    { key: "str", runs: statRuns(player, STAT.STR, d), values: statValues(player, STAT.STR, d) },
+    { key: "int", runs: statRuns(player, STAT.INT, d), values: statValues(player, STAT.INT, d) },
+    { key: "wis", runs: statRuns(player, STAT.WIS, d), values: statValues(player, STAT.WIS, d) },
+    { key: "dex", runs: statRuns(player, STAT.DEX, d), values: statValues(player, STAT.DEX, d) },
+    { key: "con", runs: statRuns(player, STAT.CON, d), values: statValues(player, STAT.CON, d) },
+    {
+      key: "ac",
+      runs: acRuns(state),
+      values: { ac: combat.ac + combat.toA, armour: combat.ac, bonus: combat.toA },
+    },
+    { key: "hp", runs: hpRuns(player, d), values: { current: player.chp, max: player.mhp } },
+    {
+      key: "sp",
+      runs: spRuns(player, d),
+      ...(mana ? { values: { current: player.csp, max: player.msp } } : {}),
+    },
+    { key: "health", runs: healthRuns(player, d), ...(health ? { values: health } : {}) },
+    {
+      key: "speed",
+      runs: speedRuns(state, d),
+      /* Published at normal speed too, where the FIELD is blank: 110 is a known
+         number, not a missing one, and a replacement that wants to show "+0" is
+         entitled to. Core's own text stays upstream's. */
+      values: { speed: state.actor.speed, relative: state.actor.speed - 110 },
+    },
+    {
+      key: "depth",
+      runs: depthRuns(state),
+      values: { depth: state.chunk.depth, feet: state.chunk.depth * 50 },
+    },
   ];
 }
 
@@ -985,7 +1095,19 @@ export function statusLineModel(
   const d = resolveDeps(state, deps);
   const player = state.actor.player;
   return [
-    { key: "level_feeling", runs: levelFeelingRuns(state, d) },
+    {
+      key: "level_feeling",
+      runs: levelFeelingRuns(state, d),
+      /* "LF:3-4" is two digits that are each an INDEX into a colour table, and
+         both are printed inverted (11 - objFeeling). A consumer that wants its
+         own wording for a feeling needs the indices, not the arithmetic. */
+      values: {
+        object: Math.trunc(state.chunk.feeling / 10),
+        monster: state.chunk.feeling % 10,
+        squares: state.chunk.feelingSquares,
+        need: d.feelingNeed,
+      },
+    },
     { key: "light", runs: lightRuns(state) },
     { key: "moves", runs: movesRuns(d) },
     { key: "unignore", runs: unignoreRuns(d) },

package/src/game/dump-level.ts

@@ -3,7 +3,7 @@
  *
  * The post-mortem level dump: one HTML page holding an ASCII map of a chunk, one
  * character per grid, in upstream's own precedence order. Two commands use it -
- * the wizard's "dump level map" (cmd-wizard.c:1112) and wiz-stats' disconnect
+ * the wizard's "dump level map" (cmd-wizard.c:1162) and wiz-stats' disconnect
  * report (disconnect.html) - and the `dist` argument is what the latter needs:
  * where the distance array is negative, the grid is written as '*' instead of
  * its own glyph, which is how an unreachable region shows up on the page.

package/src/game/effect-attack.ts

@@ -24,7 +24,7 @@
  * attack projections are rare and resolve to a bare source.
  */
 
-import { EF, MSG, PROJ, TMD } from "../generated/index.js";
+import { EF, PROJ, TMD } from "../generated/index.js";
 import type { Loc } from "../loc.js";
 import { monsterIsPowerful } from "../mon/predicate.js";
 import { MDESC_DIED_FROM, monsterDesc } from "../mon/desc.js";
@@ -239,7 +239,6 @@ const handleBREATH: EffectHandler = (ctx) => {
     const proj = env.cast.projections[ctx.subtype];
     if (proj) {
       ctx.env.messages?.msg(`You breathe ${proj.desc}.`, proj.msgt ?? undefined);
-      if (proj.msgt) env.state.sound?.((MSG as Record<string, number>)[proj.msgt] ?? 0);
     }
   }
 

package/src/game/effect-general.ts

@@ -26,7 +26,7 @@
  * squareIsDecoyed / monsterIsDecoyed).
  */
 
-import { EF, MON_TMD, MSG, OF, PROJ, TMD } from "../generated/index.js";
+import { EF, MON_TMD, OF, PROJ, TMD } from "../generated/index.js";
 import { DDGRID, distance, loc, locSum } from "../loc.js";
 import { PROJECT } from "../world/project.js";
 import { GLYPH_DECOY } from "../effects/effect.js";
@@ -152,8 +152,10 @@ interface GameEffectEnvLike {
 
 /**
  * msg() over the effect context's optional message sink. `msgt` is a MSG_*
- * name and supplies msgt's message half; the sound half is state.sound at the
- * call site (this helper has no state).
+ * name, and passing one makes this the whole of msgt(): the sink plays the
+ * type's sound as well (#239). It used to supply only the message half, with
+ * every caller expected to add a `state.sound` of its own - which is why the
+ * ones that did not were silent.
  */
 function say(ctx: EffectHandlerContext, text: string, msgt?: string): void {
   ctx.env.messages?.msg(text, msgt);
@@ -762,9 +764,9 @@ const handleRECALL: EffectHandler = (ctx) => {
 };
 
 /**
- * EF_DEEP_DESCENT: a delayed drop of several levels (effect-handler-
- * general.c L1166), counted down by process_world. The target increment is
- * (4 / stair_skip) + 1 from the deepest reached depth.
+ * EF_DEEP_DESCENT: a delayed drop of several levels
+ * (effect-handler-general.c L1162-1181), counted down by process_world. The
+ * target increment is (4 / stair_skip) + 1 from the deepest reached depth.
  */
 const handleDEEP_DESCENT: EffectHandler = (ctx) => {
   const env = gameEnv(ctx);
@@ -780,10 +782,10 @@ const handleDEEP_DESCENT: EffectHandler = (ctx) => {
 
   /* Both arms are msgt(MSG_TPLEVEL, ...) (effect-handler-general.c:1171,
    * :1178) - the message carries the type, and msgt's other half is the
-   * sound. Neither half existed here (PORT_TODO 3.26). */
+   * sound. Neither half existed here (PORT_TODO 3.26); the second half is the
+   * typed sink's job now (#239). */
   if (targetDepth > state.chunk.depth) {
     say(ctx, "The air around you starts to swirl...", "TPLEVEL");
-    state.sound?.(MSG.TPLEVEL);
     p.deepDescent = 3 + state.rng.randint1(4);
   } else {
     say(
@@ -791,7 +793,6 @@ const handleDEEP_DESCENT: EffectHandler = (ctx) => {
       "You sense a malevolent presence blocking passage to the levels below.",
       "TPLEVEL",
     );
-    state.sound?.(MSG.TPLEVEL);
   }
   ctx.ident = true;
   return true;
@@ -1157,9 +1158,9 @@ const GENERAL_HANDLERS: ReadonlyMap<number, EffectHandler> = new Map<
   [EF.DRAIN_LIGHT, handleDRAIN_LIGHT],
   /* effect_handler_DRAIN_MANA (effect-handler-general.c:956) */
   [EF.DRAIN_MANA, handleDRAIN_MANA],
-  /* effect_handler_SCRAMBLE_STATS (effect-handler-general.c:3634) */
+  /* effect_handler_SCRAMBLE_STATS (effect-handler-general.c:3630) */
   [EF.SCRAMBLE_STATS, handleSCRAMBLE_STATS],
-  /* effect_handler_UNSCRAMBLE_STATS (effect-handler-general.c:3646) */
+  /* effect_handler_UNSCRAMBLE_STATS (effect-handler-general.c:3642) */
   [EF.UNSCRAMBLE_STATS, handleUNSCRAMBLE_STATS],
   /* effect_handler_TIMED_INC (effect-handler-general.c:576) */
   [EF.TIMED_INC, handleTIMED_INC],