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

package/src/mon/bind.ts

@@ -60,6 +60,7 @@ import type {
 } from "./types.js";
 import { RF, RSF } from "../generated/index.js";
 import { messageLookupByName } from "../sound/engine.js";
+import { attachExt } from "../mod/extension.js";
 
 /* re-export for consumers that reach the domain through bind */
 export { MFLAG_SIZE, RF_SIZE, RSF_SIZE };
@@ -473,13 +474,16 @@ function bindBases(
     }
     const flags = new FlagSet(RF_SIZE);
     raceFlagsOn(flags, rec.flags);
-    map.set(rec.name, {
-      name: rec.name,
-      text: joinLines(rec.desc),
-      flags,
-      glyph: rec.glyph,
-      pain,
-    });
+    map.set(
+      rec.name,
+      attachExt<MonsterBase>("monster_base", rec, {
+        name: rec.name,
+        text: joinLines(rec.desc),
+        flags,
+        glyph: rec.glyph,
+        pain,
+      }),
+    );
   }
   return map;
 }
@@ -646,7 +650,9 @@ export class MonsterRegistry {
     this.racesByName = new Map();
     for (const rec of pack.monsters) {
       const race = this.bindRace(rec, maxSight, innate, breathOrInnate);
-      this.races.push(race);
+      /* Keys core does not read ride along instead of being dropped - the same
+       * seam as ObjectKind.ext, for the same reason. */
+      this.races.push(attachExt("monster", rec, race));
       this.racesByName.set(race.name.toLowerCase(), race);
     }
 

package/src/mon/knowledge-groups.ts

@@ -27,10 +27,6 @@ export interface MonsterCategory {
   readonly incBases: readonly string[];
   /** mcat-include-flag flag indices (RF_*). */
   readonly incFlags: readonly number[];
-  /** mcat-include-other:fully-known */
-  readonly includeFullyKnown: boolean;
-  /** mcat-include-other:not-fully-known */
-  readonly includeNotFullyKnown: boolean;
 }
 
 /** A compiled pack/ui_knowledge.json record. */
@@ -39,8 +35,6 @@ export interface UiKnowledgeRecordJson {
   "mcat-include-base"?: string[];
   /** Each entry is a " | "-separated flag list (may hold several flags). */
   "mcat-include-flag"?: string[];
-  /** "fully-known" / "not-fully-known". */
-  "mcat-include-other"?: string[];
 }
 
 /** The reserved catch-all category name (finish_ui_knowledge_parser L3439). */
@@ -60,13 +54,10 @@ export function bindMonsterCategories(
         if (idx !== undefined) incFlags.push(idx);
       }
     }
-    const other = (r["mcat-include-other"] ?? []).map(String);
     return {
       name: r["monster-category"],
       incBases: (r["mcat-include-base"] ?? []).map(String),
       incFlags,
-      includeFullyKnown: other.includes("fully-known"),
-      includeNotFullyKnown: other.includes("not-fully-known"),
     };
   });
 }
@@ -104,17 +95,26 @@ function compareInGroup(
   return strcmp(a.name, b.name);
 }
 
-/** Does a race match a category by flag or by the fully-/not-fully-known other? */
+/**
+ * Does a race match a category by flag? (ui-knowledge.c parse_mcat_include_flag.)
+ *
+ * There is no `mcat-include-other` arm here any more. That directive, and the
+ * fully-known / not-fully-known categories it drives, are POST-4.2.6 upstream
+ * work; #143 moved reference/ back to the 4.2.6 tag, whose ui-knowledge.c
+ * registers only mcat-include-base and mcat-include-flag, and whose
+ * ui_knowledge.txt uses neither of the "other" values. Core reproduces a
+ * released Angband, so an upstream feature newer than the baseline is an
+ * extension and belongs in a mod (#146).
+ */
 function matchesFlagOrOther(
   category: MonsterCategory,
   race: MonsterRace,
   allKnown: boolean,
 ): boolean {
+  void allKnown;
   for (const flag of category.incFlags) {
     if (race.flags.has(flag)) return true;
   }
-  if (category.includeFullyKnown && allKnown) return true;
-  if (category.includeNotFullyKnown && !allKnown) return true;
   return false;
 }
 

package/src/mon/lore-describe.ts

@@ -18,8 +18,8 @@
  * spell&blow danger colors that upstream reads off the global player) is not
  * available in this module, so it is injected through the LoreDeps object.
  * Colors default to the datum's base lore color when no danger evaluator is
- * supplied; the two hit-chance callbacks are the remaining integration seams
- * for the combat layer (still default to 0 unwired). The spell damage
+ * supplied; the two hit-chance callbacks are integration seams supplied by the
+ * combat layer in the live game. The spell damage
  * callback (`spellLoreDamage`) is a full override only - its default
  * computes the real mon_spell_lore_damage from the bound spell + race data
  * (see monSpellLoreDamage below), needing just `breathProjection` from the
@@ -43,6 +43,7 @@ import {
   colorTextToAttr,
 } from "../color.js";
 import { EF, MON_RACE_FLAG_ENTRIES, OF, PROJ, RF } from "../generated/index.js";
+import { ATTR_TILE_BIT } from "../visuals/map-text.js";
 import { createMonFlagMask, monsterFlagsKnown } from "./lore.js";
 import type { MonsterLore } from "./lore.js";
 import { EXTRACT_ENERGY } from "./monster.js";
@@ -114,6 +115,21 @@ export interface LoreDeps {
   playerSpeed: number;
   /** OPT(player, effective_speed): multiplier form vs. adjective form. */
   effectiveSpeed: boolean;
+  /**
+   * OPT(player, purple_uniques): recolour a unique's title glyph violet
+   * (ui-mon-lore.c L56-60). Required rather than optional, and named exactly as
+   * `visuals/map-text.ts` names it, because the map layer already honours this
+   * option — a lore title that quietly ignored it would disagree with the glyph
+   * the player is looking at on the same screen.
+   */
+  purpleUniques: boolean;
+  /**
+   * monster_x_attr[race->ridx] / monster_x_char[race->ridx] (ui-mon-lore.c
+   * L47/L51): the pref-file / picker override pair for a race. Optional, and
+   * absent means "no override table" - a spoiler file and a worldless test have
+   * none, and upstream's arrays would hold the default pair there anyway.
+   */
+  monsterGlyph?: (race: MonsterRace) => { attr: number; char: string } | undefined;
   /** monster_spell_by_index: the bound spell list, keyed by RSF_ index. */
   spells: ReadonlyMap<number, MonsterSpell>;
   /**
@@ -129,13 +145,15 @@ export interface LoreDeps {
   /**
    * The player's percent chance to hit this race in melee
    * (random_chance_scaled of hit_chance(chance_of_melee_hit_base, ac)).
-   * DEFERRED: defaults to 0 when the combat layer does not supply it.
+   * Defaults to 0 only for a caller that omits it. The core spoiler dump has
+   * booted player combat state, but deliberately omits this inert callback.
    */
   meleeHitPercent?: (race: MonsterRace) => number;
   /**
    * The monster's percent chance to land the given blow on the player
    * (random_chance_scaled of hit_chance(chance_of_monster_hit_base, ac+to_a)).
-   * DEFERRED: defaults to 0 when the combat layer does not supply it.
+   * Defaults to 0 only for a caller that omits it and has no player defence to
+   * supply. The core spoiler dump supplies this callback from its booted state.
    */
   monsterHitPercent?: (race: MonsterRace, effect: BlowEffect) => number;
   /**
@@ -151,9 +169,8 @@ export interface LoreDeps {
    * The breath element's damage divisor/cap (element->divisor /
    * element->damage_cap, projection.txt), keyed by PROJ_ value - the one
    * piece of breath damage that lives outside mon/ (world/projection.ts).
-   * Only consulted for breath-type spells' default damage. DEFERRED: damage
-   * shows as 0 when the caller does not supply it, like the other
-   * world-derived callbacks above.
+   * Only consulted for breath-type spells' default damage. A worldless caller
+   * without projection data renders that component as 0.
    */
   breathProjection?: (subtype: number) => BreathProjection | undefined;
 }
@@ -1342,54 +1359,104 @@ function isFullyKnown(race: MonsterRace, lore: MonsterLore): boolean {
 }
 
 /**
- * lore_title (ui-mon-lore.c L38), reduced to what the headless model can
- * express: "The " for non-uniques, the name, and the primary glyph.
+ * lore_title (ui-mon-lore.c L38): "The " for non-uniques, the name, and the
+ * primary glyph — with OPT(purple_uniques) recolouring a unique's glyph violet
+ * (L56-60). Upstream also recolours the OPTIONAL attr there, but only when it is
+ * not a tile index (`!(optional_attr & 0x80)`).
  *
- * DEFERRED: the optional secondary glyph (monster_x_char / monster_x_attr,
- * ui-mon-lore.c L47/L51), OPT(purple_uniques) recoloring (L56), and tile
- * width/height gating (L69) are all presentation state not modelled here.
+ * The secondary glyph is ported too, through the optional `monsterGlyph` dep.
+ * It used to be filed here as shell-owned along with `purple_uniques` and the
+ * tile-size gate, and all three of those groupings were wrong in different
+ * ways: `purple_uniques` is a live option the map layer already honours;
+ * `monster_x_attr` / `monster_x_char` are a real table in the port
+ * (`visuals/glyph-table.ts`, `GlyphTable.monsterGlyph`); and the
+ * `tile_width == 1 && tile_height == 1` gate (L69) is unconditionally TRUE
+ * here — the port has no multi-cell tiles, a ratified divergence recorded at
+ * `packages/web/src/mapview.ts:70` — so the gate is omitted rather than
+ * deferred. Absent `monsterGlyph` (spoiler files, worldless tests) the pair
+ * equals the race's own and nothing extra is emitted, exactly as upstream's
+ * unmodified array would give.
  */
-function loreTitle(b: LoreTextBuilder, race: MonsterRace): void {
-  if (!race.flags.has(RF.UNIQUE)) b.append("The ");
+function loreTitle(b: LoreTextBuilder, race: MonsterRace, deps: LoreDeps): void {
+  const unique = race.flags.has(RF.UNIQUE);
+  const optional = deps.monsterGlyph?.(race);
+  let standardAttr = race.dAttr;
+  let optionalAttr = optional?.attr ?? race.dAttr;
+  const optionalChar = optional?.char ?? race.dChar;
+
+  if (!unique) {
+    b.append("The ");
+  } else if (deps.purpleUniques) {
+    standardAttr = COLOUR_VIOLET;
+    /* L58-59: a tile code in the slot is left alone. */
+    if (!(optionalAttr & ATTR_TILE_BIT)) optionalAttr = COLOUR_VIOLET;
+  }
+
   b.append(race.name);
   b.append(" ('");
-  b.append(race.dChar, race.dAttr);
+  b.append(race.dChar, standardAttr);
   b.append("')");
+
+  if (optionalAttr !== standardAttr || optionalChar !== race.dChar) {
+    b.append(" ('");
+    b.append(optionalChar, optionalAttr);
+    b.append("')");
+  }
 }
 
 /**
- * lore_description (ui-mon-lore.c L89), non-spoiler path: assemble the full
- * recall for what the player knows. Returns the finished flat run list.
+ * lore_description (ui-mon-lore.c L89): assemble the full recall. Returns the
+ * finished flat run list.
  *
  * The order of sections is transcribed from ui-mon-lore.c L110-150:
  *   title, kills, flavor, movement, toughness, exp, drop, abilities,
  *   awareness, friends, spells, attack, fully-known note, questor note.
+ *
+ * `spoilers` is upstream's fourth argument (L90) and means "full information,
+ * without the subjective parts". It suppresses FOUR sections, not just the
+ * title: the title (L108-112), the kill counts (L114-116), the toughness block
+ * (L124-125) and the experience reward (L128-129). Every one of those is a
+ * statement about a player, and a spoiler file has no player.
+ *
+ * Upstream also calls cheat_monster_lore inside here when the flag is set
+ * (L101-102). The port leaves that to the caller: game/spoil.ts already does it
+ * on the lore copy it owns, and doing it twice is the same work for the same
+ * answer.
  */
 export function loreDescription(
   race: MonsterRace,
   lore: MonsterLore,
   deps: LoreDeps,
+  /**
+   * ui-mon-lore.c's `spoilers` (L90). Defaults false, the player view. There
+   * are exactly two callers and they want different values, so this is a live
+   * branch rather than an option nobody sets.
+   */
+  spoilers = false,
 ): LoreText {
   const b = new LoreTextBuilder();
   const knownFlags = monsterFlagsKnown(race, lore);
 
-  /* Title (only in the non-spoiler player view). */
-  loreTitle(b, race);
-  b.append("\n");
+  /* Title (L108-112). Upstream's own comment: appending it here simplifies the
+     callers, "and it also causes a crash when generating spoilers". */
+  if (!spoilers) {
+    loreTitle(b, race, deps);
+    b.append("\n");
+  }
 
-  /* Kills of monster vs. player(s). */
-  loreAppendKills(b, race, lore, knownFlags);
+  /* Kills of monster vs. player(s) (L114-116). */
+  if (!spoilers) loreAppendKills(b, race, lore, knownFlags);
 
   loreAppendFlavor(b, race);
 
   /* Type, location, speed. */
   loreAppendMovement(b, race, lore, knownFlags, deps);
 
-  /* Life and armor, and player's hit chance. */
-  loreAppendToughness(b, race, lore, knownFlags, deps);
+  /* Life and armor, and player's hit chance (L124-125). */
+  if (!spoilers) loreAppendToughness(b, race, lore, knownFlags, deps);
 
-  /* Experience reward. */
-  loreAppendExp(b, race, lore, knownFlags, deps);
+  /* Experience reward (L128-129). */
+  if (!spoilers) loreAppendExp(b, race, lore, knownFlags, deps);
 
   loreAppendDrop(b, race, lore, knownFlags);
 

package/src/mon/lore-file.ts

@@ -0,0 +1,365 @@
+/**
+ * lore.txt: monster memory as a file in ANGBAND_DIR_USER, both halves.
+ *
+ * WHAT WAS MISSING, AND WHY IT IS NOT JUST A FILE
+ *
+ * Upstream splits monster memory between two stores, and the split is
+ * load-bearing rather than incidental:
+ *
+ *   - the SAVEFILE carries `pkills` and `thefts` - "in this life" counters;
+ *   - `lore.txt` in the USER directory carries everything else, and the user
+ *     directory belongs to the PLAYER, not to a character. `lore_save` is
+ *     called from `save_game_checked` (ui-game.c:1089) and the file is read back
+ *     by `lore_parser` at startup (mon-init.c:2672), before any savefile is
+ *     touched.
+ *
+ * So upstream's monster knowledge SURVIVES DEATH. `tkills` is commented "Count
+ * monsters killed in all lives" and mon-lore.c says so out loud: "your ancestors
+ * have exterminated at least %d of the creatures." The port kept the whole lore
+ * record in the JSON save, which is tidy and is why nothing ever noticed - but it
+ * means tkills can only ever count this character's kills, and the ancestor
+ * sentence in lore-describe.ts could never be true of an ancestor. A behavioural
+ * gap wearing a file's clothes: reading the port, there was no missing function to
+ * find, because the knowledge was being persisted - just to the wrong place.
+ *
+ * THE SPLIT, KEPT EXACTLY. This module is the file. The save keeps carrying the
+ * full record (no SAVE_VERSION change: a bump reads as corruption to an existing
+ * character), and the front end overlays lore.txt on top of a loaded game for the
+ * seven counters plus the flags and blows that the file carries - which is
+ * precisely the set `write_lore_entries` writes. pkills and thefts are never in
+ * the file and so are never overlaid, exactly as upstream has them.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT EMIT: `drop:`, `drop-base:`, `friends:`,
+ * `friends-base:` and `mimic:`. Upstream writes those from `lore->drops` and
+ * friends, and NOTHING in the C populates those lists except the lore PARSER -
+ * they are a pure echo of a previously-read file. A player who has never had a
+ * lore.txt gets none of those lines from upstream either, and the port models the
+ * same knowledge on the race gated on `dropKnown` and the known flags (see
+ * lore.ts). The reader below accepts and ignores them, so an upstream lore.txt
+ * still loads.
+ */
+
+import { writeFlags } from "../datafile.js";
+/**
+ * writeFlags used to be DEFINED here and is on the pinned ctx.core surface
+ * (mod-core-surface.test.ts), so a plugin may be importing it from this
+ * module. Moving the definition to ../datafile.js must not move the export.
+ */
+export { writeFlags };
+import { FlagSet, flagSetall } from "../bitflag.js";
+import { RF, RSF } from "../generated/index.js";
+import { RF_SIZE, RSF_SIZE } from "./types.js";
+import type { MonsterRace } from "./types.js";
+import { loreUpdate, newMonsterLore } from "./lore.js";
+import type { LoreStore, MonsterLore } from "./lore.js";
+
+/**
+ * A flag-number -> name table, INVERTED FROM THE ENUM rather than read off the
+ * generated entry list.
+ *
+ * The two entry lists disagree about index 0: MON_SPELL_ENTRIES keeps upstream's
+ * RSF_NONE at [0], and MON_RACE_FLAG_ENTRIES drops RF_NONE, so `ENTRIES[flag]`
+ * is right for one and off by one for the other. Inverting the enum - which is
+ * generated from the same header as the flags themselves - cannot be off by one
+ * in either direction, and the test pins both against the reference headers.
+ */
+function nameTable(en: Readonly<Record<string, number>>): readonly (string | undefined)[] {
+  const out: (string | undefined)[] = [];
+  for (const [name, value] of Object.entries(en)) out[value] = name;
+  return out;
+}
+
+/** r_info_flags (mon-init.c), by flag number. Index 0 is upstream's RF_NONE. */
+export const RF_FLAG_NAMES = nameTable(RF);
+/** r_info_spell_flags (mon-init.c:55-61), by flag number. */
+export const RSF_FLAG_NAMES = nameTable(RSF);
+
+const RF_NAMES = RF_FLAG_NAMES;
+const RSF_NAMES = RSF_FLAG_NAMES;
+
+
+/**
+ * write_lore_entries (mon-lore.c:1743-1893): one block per race the player has
+ * seen or fully knows, in race index order.
+ *
+ * `rsf_inter(lore->spell_flags, race->spell_flags)` at L1802 MUTATES the lore
+ * record as a side effect of writing the file - a wart, but a wart that changes
+ * what the next save contains, so it is reproduced (core keeps the C's warts;
+ * fixes go in the bug-fixes mod).
+ */
+export function writeLoreEntries(
+  races: readonly MonsterRace[],
+  store: LoreStore,
+): string {
+  let out = "";
+
+  for (const race of races) {
+    /* "Ignore non-existent or unseen monsters" (L1755-1757). */
+    if (!race.name) continue;
+    const lore = store.get(race.ridx);
+    if (!lore) continue;
+    if (!lore.sights && !lore.allKnown) continue;
+
+    out += `name:${race.name}\n`;
+
+    /* "Output base if we're remembering everything" (L1760-1762). */
+    if (lore.allKnown) out += `base:${race.base.name}\n`;
+
+    out += `counts:${lore.sights}:${lore.deaths}:${lore.tkills}:${lore.wake}:${lore.ignore}:${lore.castInnate}:${lore.castSpell}\n`;
+
+    /* Blows, up to mon_blows_max (L1768-1795). */
+    for (let n = 0; n < race.blows.length; n++) {
+      if (!lore.blowKnown[n] && !lore.allKnown) continue;
+      const blow = race.blows[n];
+      if (!blow?.method) continue;
+      const rv = blow.dice?.randomValue() ?? { base: 0, dice: 0, sides: 0, mBonus: 0 };
+      out += `blow:${blow.method.name}`;
+      out += `:${blow.effect.name}`;
+      out += `:${rv.base}+${rv.dice}d${rv.sides}M${rv.mBonus}`;
+      out += `:${lore.blowTimesSeen[n] ?? 0}`;
+      out += `:${n}`;
+      out += "\n";
+    }
+
+    out += writeFlags("flags:", lore.flags, RF_SIZE, RF_NAMES);
+
+    /* rsf_inter, in place, then the spell line (L1802-1805). */
+    lore.spellFlags.inter(race.spellFlags);
+    out += writeFlags("spells:", lore.spellFlags, RSF_SIZE, RSF_NAMES);
+
+    out += "\n";
+  }
+
+  return out;
+}
+
+/** The fields lore.txt carries, for one race. Everything else stays as it was. */
+interface LoreFileEntry {
+  readonly sights: number;
+  readonly deaths: number;
+  readonly tkills: number;
+  readonly wake: number;
+  readonly ignore: number;
+  readonly castInnate: number;
+  readonly castSpell: number;
+  readonly allKnown: boolean;
+  /** index -> times_seen, only for blows the file recorded as seen. */
+  readonly blowTimesSeen: ReadonlyMap<number, number>;
+  readonly flags: FlagSet;
+  readonly spellFlags: FlagSet;
+}
+
+/** What one parse produced, plus the lines it could not use. */
+export interface LoreFileParse {
+  /** Race name (as written in the file) -> the record it carried. */
+  readonly entries: ReadonlyMap<string, LoreFileEntry>;
+  /**
+   * Directives that were recognised but carry nothing this port models - the
+   * drop / friends / mimic echo - counted rather than dropped silently, so a
+   * caller can say "this file held more than we read" instead of guessing.
+   */
+  readonly ignored: number;
+  /** Lines that are not a directive at all. Named, because a broken file is a bug. */
+  readonly bad: readonly string[];
+}
+
+/** grab_flag by name, tolerant exactly as the C's `(void) grab_flag` is. */
+function grabFlags(text: string, set: FlagSet, names: readonly (string | undefined)[]): void {
+  for (const token of text.split(/[\s|]+/u)) {
+    if (token === "") continue;
+    const flag = names.indexOf(token);
+    if (flag > 0) set.on(flag);
+  }
+}
+
+/**
+ * lore_parser (mon-init.c:2544-2580), as a pure function over the file text.
+ *
+ * Upstream resolves `name:` to a race immediately and drops the block when the
+ * monster does not exist ("to allow for non-existent monsters"). This keeps the
+ * NAME and lets the caller resolve, because in this port a name can be absent for
+ * a second reason upstream does not have: a mod that supplied the monster is no
+ * longer installed. Losing that block silently would quietly forget a player's
+ * memory of it, where keeping it means re-enabling the mod restores the lore.
+ */
+export function parseLoreFile(text: string): LoreFileParse {
+  const entries = new Map<string, LoreFileEntry>();
+  const bad: string[] = [];
+  let ignored = 0;
+
+  let name: string | null = null;
+  let cur: {
+    sights: number;
+    deaths: number;
+    tkills: number;
+    wake: number;
+    ignore: number;
+    castInnate: number;
+    castSpell: number;
+    allKnown: boolean;
+    blowTimesSeen: Map<number, number>;
+    flags: FlagSet;
+    spellFlags: FlagSet;
+  } | null = null;
+
+  const flush = (): void => {
+    if (name !== null && cur !== null) entries.set(name, cur);
+    name = null;
+    cur = null;
+  };
+
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+
+    const colon = line.indexOf(":");
+    const directive = colon < 0 ? line : line.slice(0, colon);
+    const rest = colon < 0 ? "" : line.slice(colon + 1);
+
+    switch (directive) {
+      case "name": {
+        flush();
+        name = rest;
+        cur = {
+          sights: 0,
+          deaths: 0,
+          tkills: 0,
+          wake: 0,
+          ignore: 0,
+          castInnate: 0,
+          castSpell: 0,
+          allKnown: false,
+          blowTimesSeen: new Map<number, number>(),
+          flags: new FlagSet(RF_SIZE),
+          spellFlags: new FlagSet(RSF_SIZE),
+        };
+        break;
+      }
+      case "base": {
+        /* parse_lore_base: the base is only validated; what it MEANS is
+         * "know everything" plus every racial flag set (mon-init.c:2294-2296). */
+        if (cur) {
+          cur.allKnown = true;
+          flagSetall(cur.flags.bits);
+        }
+        break;
+      }
+      case "counts": {
+        if (!cur) break;
+        const n = rest.split(":").map((v) => Number.parseInt(v, 10));
+        if (n.length < 7 || n.some((v) => Number.isNaN(v))) {
+          bad.push(line);
+          break;
+        }
+        [cur.sights, cur.deaths, cur.tkills, cur.wake, cur.ignore, cur.castInnate, cur.castSpell] =
+          n as [number, number, number, number, number, number, number];
+        break;
+      }
+      case "blow": {
+        if (!cur) break;
+        /* method:effect:damage:seen:index, every field after the method
+         * optional. "Interpret: if (seen)" - a blow seen zero times is not
+         * recorded at all (mon-init.c:2345-2351). */
+        const f = rest.split(":");
+        const seen = Number.parseInt(f[3] ?? "", 10);
+        const index = Number.parseInt(f[4] ?? "", 10);
+        if (!Number.isNaN(seen) && seen > 0 && !Number.isNaN(index) && index >= 0) {
+          cur.blowTimesSeen.set(index, seen);
+        }
+        break;
+      }
+      case "flags": {
+        if (cur) grabFlags(rest, cur.flags, RF_NAMES);
+        break;
+      }
+      case "spells": {
+        if (cur) grabFlags(rest, cur.spellFlags, RSF_NAMES);
+        break;
+      }
+      case "drop":
+      case "drop-base":
+      case "friends":
+      case "friends-base":
+      case "mimic": {
+        ignored++;
+        break;
+      }
+      default:
+        bad.push(line);
+    }
+  }
+  flush();
+
+  return { entries, ignored, bad };
+}
+
+/** What an overlay changed, so a caller can log it instead of assuming. */
+export interface LoreOverlayResult {
+  /** Races whose record the file supplied. */
+  readonly applied: number;
+  /** Entries naming a race this pack does not have (an uninstalled mod). */
+  readonly unknownRaces: readonly string[];
+  readonly ignored: number;
+  readonly bad: readonly string[];
+}
+
+/**
+ * Put lore.txt's record over a loaded game's store, which is upstream's order:
+ * the file is read at startup and the savefile then supplies only pkills and
+ * thefts.
+ *
+ * Overwrites rather than merges, deliberately. The file is written on every save
+ * from this same store, so it is never older than the save; inventing a
+ * max()-per-counter merge would produce numbers neither store ever held.
+ * pkills, thefts, dropGold and dropItem are not in the file and are left alone.
+ */
+export function applyLoreFile(
+  races: readonly MonsterRace[],
+  store: LoreStore,
+  parsed: LoreFileParse,
+): LoreOverlayResult {
+  const byName = new Map<string, MonsterRace>();
+  for (const race of races) if (race.name) byName.set(race.name, race);
+
+  const unknownRaces: string[] = [];
+  let applied = 0;
+
+  for (const [name, entry] of parsed.entries) {
+    const race = byName.get(name);
+    if (!race) {
+      unknownRaces.push(name);
+      continue;
+    }
+    let lore: MonsterLore | undefined = store.get(race.ridx);
+    if (!lore) {
+      lore = newMonsterLore(race);
+      store.set(race.ridx, lore);
+    }
+
+    lore.sights = entry.sights;
+    lore.deaths = entry.deaths;
+    lore.tkills = entry.tkills;
+    lore.wake = entry.wake;
+    lore.ignore = entry.ignore;
+    lore.castInnate = entry.castInnate;
+    lore.castSpell = entry.castSpell;
+    lore.allKnown = entry.allKnown;
+    lore.flags = entry.flags;
+    lore.spellFlags = entry.spellFlags;
+
+    /* Blows the file did not mention were seen zero times, which is what
+     * upstream's zeroed l_list means before the parser fills it in. */
+    lore.blowTimesSeen = race.blows.map((_, i) => entry.blowTimesSeen.get(i) ?? 0);
+    lore.blowKnown = race.blows.map((_, i) => (entry.blowTimesSeen.get(i) ?? 0) > 0);
+
+    /* lore_update is what derives armourKnown / dropKnown / the RFT_OBV union
+     * from the counters, and the parser leaves those unset. */
+    loreUpdate(race, lore);
+    applied++;
+  }
+
+  return { applied, unknownRaces, ignored: parsed.ignored, bad: parsed.bad };
+}
+
+/** The name lore_save is called with (ui-game.c:1090). */
+export const LORE_FILE = "lore.txt";

package/src/mon/lore.ts

@@ -13,9 +13,15 @@
  * gated on dropKnown / the known flags, so they are not modelled.
  *
  * The store lives on GameState.lore (a Map keyed by race.ridx), created
- * lazily by getLore; the save serializes it whole. Upstream splits
- * persistence between the savefile (pkills / thefts) and the user lore
- * file (everything else); the JSON save carries the full record.
+ * lazily by getLore.
+ *
+ * PERSISTENCE IS SPLIT, as upstream's is. The savefile owns pkills and thefts
+ * ("in this life"); lore.txt in the user directory owns everything else and
+ * outlives the character, which is what makes tkills "monsters killed in all
+ * lives" and lore-describe's "your ancestors have exterminated at least %d"
+ * able to be about an ancestor. lore-file.ts is both halves of that file; the
+ * JSON save still carries the whole record (narrowing it would be a
+ * SAVE_VERSION change) and the file is laid over it on load.
  */
 
 import { FlagSet } from "../bitflag.js";