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

package/src/obj/randart-file.ts

@@ -0,0 +1,130 @@
+/**
+ * randart.txt (obj-randart.c:3061-3167, PORT_TODO 5.5) - the optional data
+ * file do_randart writes alongside randart.log when its `create_file` argument
+ * is true.
+ *
+ * WHAT IT IS FOR. randart.txt is a real artifact.txt: a player who rolls a set
+ * they like can read exactly what they got, and the file is in the grammar the
+ * parser already reads, so it can be diffed against the standard set or handed
+ * to a mod. That is why it is a separate file from randart.log rather than
+ * another section of it.
+ *
+ * WHAT DIFFERS FROM THE C, and why:
+ *
+ * - Upstream reuses the `log_file` global as the handle, having just closed
+ *   randart.log with it. Nothing is shared but the variable, so the port keeps
+ *   the two files properly apart and this module never touches the log sink.
+ * - The C writes line by line through file_putf. HostIo.write is a whole-file
+ *   call, so this returns the document as a string and do_randart writes once.
+ * - `graphics:` needs the kind's display char and attr. Upstream converts a
+ *   wide char with text_wctomb and an attr index with attr_to_text; the port
+ *   already stores both as strings on ObjectKind, so the conversion has no
+ *   counterpart and the values go out directly.
+ */
+import { writeElements, writeFlags, writeMods } from "../datafile.js";
+import { OBJECT_FLAG_ENTRIES } from "../generated/index.js";
+import type { ObjRegistry } from "./bind.js";
+import { objectShortName, tvalFindName } from "./bind.js";
+import { OF_SIZE } from "./types.js";
+import type { Artifact } from "./types.js";
+
+/** randart.txt, in ANGBAND_DIR_USER. */
+export const RANDART_TXT = "randart.txt";
+
+/**
+ * The obj_flags[] table write_randart_entry builds inline: "NONE" at index 0,
+ * then list-object-flags.h in order. Index 0 is the sentinel OF_NONE, which is
+ * never set, so its name is only ever a placeholder that keeps the rest aligned.
+ */
+const OBJ_FLAG_NAMES: readonly string[] = [
+  "NONE",
+  ...OBJECT_FLAG_ENTRIES.map((e) => e.name),
+];
+
+/**
+ * write_randart_entry (obj-randart.c:3061-3167): one artifact.txt record.
+ *
+ * Returns "" for an artifact with no name - upstream's "Ignore non-existent
+ * artifacts" guard, which is how the unused slots in a_info are skipped.
+ */
+export function writeRandartEntry(reg: ObjRegistry, art: Artifact): string {
+  if (!art.name) return "";
+  const kind = reg.lookupKind(art.tval, art.sval);
+
+  let out = "";
+  out += `# ${art.text}\n`;
+  out += `name:${art.name}\n`;
+  out += `base-object:${tvalFindName(art.tval)}:${objectShortName(kind ? kind.name : "")}\n`;
+
+  /* Graphics only for kinds past the ordinary ones - i.e. the artifact has a
+   * base item invented for it, so nothing else defines its glyph. */
+  if (kind && kind.kidx >= reg.ordinaryKindCount) {
+    out += `graphics:${kind.dChar}:${kind.dAttr}\n`;
+  }
+
+  out += `level:${String(art.level)}\n`;
+  out += `weight:${String(art.weight)}\n`;
+  out += `cost:${String(art.cost)}\n`;
+  out += `alloc:${String(art.allocProb)}:${String(art.allocMin)} to ${String(art.allocMax)}\n`;
+  out += `attack:${String(art.dd)}d${String(art.ds)}:${String(art.toH)}:${String(art.toD)}\n`;
+  out += `armor:${String(art.ac)}:${String(art.toA)}\n`;
+
+  out += writeFlags("flags:", art.flags, OF_SIZE, OBJ_FLAG_NAMES);
+  out += writeMods(art.modifiers);
+  out += writeElements(art.elInfo);
+
+  if (art.slays) {
+    for (let j = 1; j < reg.slays.length; j++) {
+      if (art.slays[j]) out += `slay:${reg.slays[j]!.code}\n`;
+    }
+  }
+  if (art.brands) {
+    for (let j = 1; j < reg.brands.length; j++) {
+      if (art.brands[j]) out += `brand:${reg.brands[j]!.code}\n`;
+    }
+  }
+  if (art.curses) {
+    for (let j = 1; j < reg.curses.length; j++) {
+      const power = art.curses[j] ?? 0;
+      if (power !== 0) out += `curse:${reg.curses[j]!.name}:${String(power)}\n`;
+    }
+  }
+
+  /* The artifact's own activation wins; otherwise the base item's, if it has
+   * one. An artifact with neither writes no act:/time: pair at all. */
+  const act = art.activation ?? kind?.activation ?? null;
+  const time = art.activation ? art.time : kind?.time;
+  if (act && time) {
+    out += `act:${act.name}\n`;
+    out += `time:${String(time.base)}+${String(time.dice)}d${String(time.sides)}\n`;
+  }
+
+  /* Upstream writes the description twice - once as a leading comment and once
+   * as the record's own desc: line. Both are kept. */
+  out += `desc:${art.text}\n`;
+  out += "\n";
+  return out;
+}
+
+/**
+ * do_randart's `create_file` block (obj-randart.c:3195-3215): the seed header
+ * followed by every artifact's entry, from index 1.
+ *
+ * The seed is written as C's `%08lx` - lower-case hex, zero-padded to eight
+ * digits - so the file names the seed that produced it and a player can
+ * reproduce the set.
+ */
+export function writeRandartFile(
+  reg: ObjRegistry,
+  arts: readonly (Artifact | null)[],
+  randartSeed: number,
+): string {
+  let out = `# Artifact file for random artifacts with seed ${(randartSeed >>> 0)
+    .toString(16)
+    .padStart(8, "0")}\n\n\n`;
+  for (let i = 1; i < arts.length; i++) {
+    const art = arts[i];
+    if (art) out += writeRandartEntry(reg, art);
+  }
+  return out;
+}

package/src/obj/randart-log.ts

@@ -0,0 +1,78 @@
+/**
+ * `randart.log`: the artifact-generation log, ported from the two file-scope
+ * statics that carry it in the C.
+ *
+ * WHAT THIS IS. `do_randart` opens ANGBAND_DIR_USER/randart.log for writing
+ * before it touches an artifact and closes it after (obj-randart.c
+ * L3165-L3193), and every step of the design loop narrates itself into it -
+ * 174 `file_putf(log_file, ...)` sites in obj-randart.c and 59 `log_obj(...)`
+ * sites in obj-power.c, which is where a randart's POWER is worked out. It is
+ * the only account of why a generated artifact came out the way it did, and the
+ * maintainer's disposition on 2026-08-04 was **pursue parity**, so it is a port
+ * with no asterisk rather than a spoiler dump to drop.
+ *
+ * A MODULE-LEVEL SINK, DELIBERATELY. Upstream has exactly this shape: two
+ * statics (`log_file` in obj-randart.c, `object_log` in obj-power.c) that are
+ * NULL for the whole game except inside do_randart, and `log_obj` opens with
+ * `if (!object_log) return;`. Threading a log parameter through all 233 sites
+ * would touch every signature in three modules to model a variable that is
+ * global in the original. The port collapses the two statics into one because
+ * they only ever point at the same file: object_power's `log_file` argument is
+ * always do_randart's, and the one other caller that passes a different file is
+ * `object_value_real`'s pricing log, which is behind `#ifdef PRICE_DEBUG` and
+ * ships off (see randartLogPriceDebugNote).
+ *
+ * THE POWER LOG IS NOT DEAD WHEN THE SINK IS NULL - it is *skipped*, cheaply.
+ * `objectPower` runs on every item the game prices, so the guard has to be a
+ * null check and the message must not be built when there is no sink. That is
+ * why the emitters take a thunk at the sites where formatting is not free.
+ */
+
+/** A sink for one already-formatted log line (upstream: file_putf). */
+export type RandartLog = (text: string) => void;
+
+let sink: RandartLog | null = null;
+
+/**
+ * Install the log sink, or null to close it. do_randart's file_open/file_close
+ * pair (obj-randart.c L3166, L3190) is spelt as setRandartLog(f) /
+ * setRandartLog(null) so an aborted generation cannot leave it open.
+ */
+export function setRandartLog(log: RandartLog | null): void {
+  sink = log;
+}
+
+/** Whether a log is open, i.e. upstream's `if (!object_log) return;`. */
+export function randartLogOpen(): boolean {
+  return sink !== null;
+}
+
+/**
+ * `file_putf(log_file, ...)` / `log_obj(...)`: append one already-formatted
+ * chunk. Upstream's format strings carry their own "\n" (several deliberately
+ * do NOT - see damage_dice_power, which ends "for damage dice, " so the next
+ * line continues it), so callers pass the text exactly as the C composes it and
+ * this adds nothing.
+ */
+export function randartLog(text: string): void {
+  if (sink) sink(text);
+}
+
+/**
+ * The same, for a line whose formatting is not free. Upstream pays that cost
+ * unconditionally because file_vputf is inside log_obj; the port must not,
+ * because objectPower is on the item-pricing path for every object in the game.
+ */
+export function randartLogf(build: () => string): void {
+  if (sink) sink(build());
+}
+
+/**
+ * `object_value_real`'s `pricing.log` (obj-power.c L1119-L1204) is NOT this
+ * log and is NOT ported. It is guarded by `#ifdef PRICE_DEBUG`, which no
+ * shipped configuration defines, so its seven file_putf sites are dead in every
+ * build a player can obtain. Recorded here rather than left to be rediscovered
+ * as a gap by the next census, which counts format strings and cannot see a
+ * preprocessor condition.
+ */
+export const PRICE_DEBUG_LOG_NOT_PORTED = true;

package/src/obj/randart-registry.ts

@@ -0,0 +1,247 @@
+/**
+ * The RANDOM ARTIFACT registry: what an ability does, what an item class starts
+ * with, which bucket it counts toward, and whether an activation is redundant.
+ *
+ * WHY THIS IS A REGISTRY. `artifact.json` has always accepted a new record, so a
+ * mod could always ship a fixed artifact. What it could not do was reach the
+ * RANDOM artifact generator, which is a different thing entirely: four closed
+ * `switch` statements decided every property a randart can have, and each failed
+ * silently rather than loudly.
+ *
+ *   - `addAbilityAux` (randart-build.ts, keyed on the `ART_IDX` ability, 87
+ *     cases) - the largest dispatch in the port. A mod-coined ability index took
+ *     the default arm, which is `break`: the design loop spent power on it and
+ *     the artifact got NOTHING.
+ *   - `artifactPrep` (randart-build.ts, keyed on the base item's tval, 15) - the
+ *     starting to-hit / to-dam / AC an item class is given. An unlisted tval got
+ *     zero of each, so a mod's new item class produced randarts that started
+ *     blank and could never be told apart from a bug.
+ *   - the item-class census (randart-data.ts, keyed on tval, 14) - which
+ *     `data.*Total` bucket a standard artifact counts toward. That census feeds
+ *     the frequency table the design loop SPENDS, so a mod's item class landing
+ *     in `otherTotal` skews what every randart in the game becomes.
+ *   - the redundancy test (randart-build.ts, keyed on the `EFPROP` kind, 9) -
+ *     whether an activation only duplicates something the artifact already has.
+ *     An unknown kind takes upstream's conservative default (keep it), which is
+ *     right for core and useless to a mod that coined a new property kind.
+ *
+ * FOUR TABLES, THREE KEYS, kept separate because upstream's keys are: the
+ * ability index, the tval, and the EFPROP kind name three different things and
+ * collapsing them would force a mod to register the same behaviour twice.
+ *
+ * WHAT A HANDLER GETS, AND WHY IT IS NOT A PILE OF CALLBACKS. Every primitive
+ * core's own arms use - `addFlag`, `addMod`, `addResist`, `addBrand`, `addSlay`,
+ * `addToHit`, `addToDam`, `addToAC`, `addLowResist`, `addHighResist`,
+ * `addImmunity`, `addStat`, `addSustain`, `addDamageDice`, `addWeightMod`,
+ * `addActivation` - is exported and reachable through `ctx.core`. So the context
+ * carries STATE (the registry, the artifact, the base kind, the target power,
+ * the set data, the rng) and nothing else. A mod's handler is written exactly
+ * the way core's arms are written.
+ *
+ * That reachability was NOT free, and it is the trap this seam nearly shipped
+ * with. The helpers were exported from `randart-build.ts` but the module was
+ * never re-exported from core's index, so none of them were in `ctx.core` - a
+ * mod could register a handler and had no way to write its body. `index.ts` now
+ * exports `randart-build.js` and `randart-data.js` for exactly that reason. A
+ * seam whose primitives a mod cannot reach is a seam a mod cannot use.
+ *
+ * ORDER AND RNG. Core's handlers are the case bodies lifted unchanged, so the
+ * draw sequence is identical - which is what `randart-vectors.json` exists to
+ * prove, 834 vectors recorded before this file existed, the per-arm families
+ * carrying an RNG probe because a changed draw count is invisible in the
+ * artifact and diverges every artifact after it. A MOD's handler draws from the
+ * same `rng`, so it changes the stream from that ability onward. That is
+ * inherent in adding behaviour to generation and is why a modded game is not
+ * seed-compatible with an unmodded one.
+ *
+ * WHY MODULE-LEVEL. The same 2026-08-09 ruling that justified
+ * `EffectInfoRegistry`: disabling a mod always takes effect on the next RELOAD,
+ * so a module-level table cannot violate the mod default policy. A fresh page is
+ * a fresh module instance and the host installs each plugin at most once per
+ * realm, so a disabled mod's registrations are gone on the next boot because the
+ * table they lived in is. `resetRandartRegistry()` is the same restoration
+ * without a fresh realm; it has no production caller by design.
+ */
+
+import type { Rng } from "../rng.js";
+import type { ObjRegistry } from "./bind.js";
+import type { EffectObjectProperty } from "./randart-build.js";
+import type { ArtifactSetData } from "./randart-data.js";
+import type { Artifact, ObjectKind } from "./types.js";
+
+/* ------------------------------------------------------------------ *
+ * Table 1: what an ability does, keyed on the ART_IDX index.
+ * ------------------------------------------------------------------ */
+
+/** The state one `add_ability_aux` arm is given (obj-randart.c L2150). */
+export interface RandartAbilityContext {
+  /** The object registry, for the flag / brand / slay / element tables. */
+  readonly reg: ObjRegistry;
+  /** The artifact being built. Handlers mutate this. */
+  readonly art: Artifact;
+  /** The base item kind, or null when the tval/sval pair names none. */
+  readonly kind: ObjectKind | null;
+  /** The power the design loop is aiming at (gates AGGRAVATE, sizes ACTIV). */
+  readonly targetPower: number;
+  /** The measured profile of the standard set: increments, powers, frequencies. */
+  readonly data: ArtifactSetData;
+  /** The generation stream. Drawing from it moves every later artifact. */
+  readonly rng: Rng;
+}
+
+/**
+ * What one ability does to an artifact. Write it the way core's arms are
+ * written: call the exported `addFlag` / `addMod` / `addResist` / ... helpers,
+ * which handle the "already has it" case and the randart.log line.
+ */
+export type RandartAbilityHandler = (ctx: RandartAbilityContext) => void;
+
+/* ------------------------------------------------------------------ *
+ * Table 2: an item class's starting stats, keyed on tval.
+ * ------------------------------------------------------------------ */
+
+/** The state one `artifact_prep` item-class arm is given. */
+export interface RandartPrepContext {
+  readonly reg: ObjRegistry;
+  /** The artifact, already given the base kind's own values. */
+  readonly art: Artifact;
+  /** The base item kind this artifact was built from. */
+  readonly kind: ObjectKind;
+  readonly data: ArtifactSetData;
+  readonly rng: Rng;
+}
+
+/**
+ * The basic stats an item class starts with. Upstream gives weapons to-hit and
+ * to-dam, armour to-AC, and everything else nothing at all - an unregistered
+ * tval takes that last arm, which is upstream's own default rather than a hole.
+ */
+export type RandartPrepHandler = (ctx: RandartPrepContext) => void;
+
+/* ------------------------------------------------------------------ *
+ * Table 3: the item-class census, keyed on tval.
+ * ------------------------------------------------------------------ */
+
+/**
+ * Which `data.*Total` bucket a standard artifact counts toward. This feeds the
+ * frequency table the design loop spends, so it is not bookkeeping: a class in
+ * the wrong bucket changes what every randart in the game becomes.
+ *
+ * `TV.NULL` is registered as an explicit no-op rather than left to the default,
+ * because upstream distinguishes "an empty artifact slot" from "an item class I
+ * have no bucket for" - the first counts toward nothing, the second toward
+ * `otherTotal`.
+ */
+export type RandartCensusHandler = (data: ArtifactSetData) => void;
+
+/* ------------------------------------------------------------------ *
+ * Table 4: activation redundancy, keyed on the EFPROP kind.
+ * ------------------------------------------------------------------ */
+
+/** The state one redundancy arm is given (obj-randart.c L2420). */
+export interface RandartRedundancyContext {
+  readonly reg: ObjRegistry;
+  /** The artifact whose activation is on trial. */
+  readonly art: Artifact;
+  /** The summarized property this arm is judging. */
+  readonly prop: EffectObjectProperty;
+}
+
+/**
+ * Whether the activation is STILL redundant after considering this property.
+ * Return false the moment the activation does something the artifact does not
+ * already do - upstream stops at the first `false` and keeps the activation.
+ * An unregistered kind takes upstream's conservative default (not redundant),
+ * which is the safe direction: a kept activation is a weaker artifact than
+ * intended, a dropped one is a missing power.
+ */
+export type RandartRedundancyHandler = (
+  ctx: RandartRedundancyContext,
+) => boolean;
+
+/* ------------------------------------------------------------------ *
+ * The tables.
+ * ------------------------------------------------------------------ */
+
+/**
+ * One keyed table. Written once and used four times, because the four differ
+ * only in their key and handler types.
+ */
+export class RandartTable<K, H> {
+  private readonly table = new Map<K, H>();
+
+  /** Install (or replace) the handler for one key. */
+  set(key: K, handler: H): void {
+    this.table.set(key, handler);
+  }
+
+  /**
+   * The handler installed for a key right now, or null. This is what a mod
+   * calls to WRAP core - keep the returned handler, install its own, and call
+   * through. Wrapping matters more here than almost anywhere else: an ability
+   * that draws a different NUMBER of random values changes every artifact
+   * generated after it, so a handler that reimplements core's from scratch and
+   * gets the draw count wrong is a whole-set divergence, not a local one.
+   */
+  handlerFor(key: K): H | null {
+    return this.table.get(key) ?? null;
+  }
+
+  /** Whether anything handles this key. */
+  has(key: K): boolean {
+    return this.table.has(key);
+  }
+
+  /** Every key handled, in registration order (core's first). */
+  keys(): readonly K[] {
+    return [...this.table.keys()];
+  }
+}
+
+/** Random artifact construction, in four tables under three keys. */
+export class RandartRegistry {
+  /** What an ability does, keyed on the ART_IDX index. */
+  readonly abilities = new RandartTable<number, RandartAbilityHandler>();
+  /** An item class's starting stats, keyed on tval. */
+  readonly prep = new RandartTable<number, RandartPrepHandler>();
+  /** The item-class census bucket, keyed on tval. */
+  readonly census = new RandartTable<number, RandartCensusHandler>();
+  /** Activation redundancy, keyed on the EFPROP kind. */
+  readonly redundancy = new RandartTable<number, RandartRedundancyHandler>();
+}
+
+/* ------------------------------------------------------------------ *
+ * The live registry.
+ * ------------------------------------------------------------------ */
+
+/**
+ * Core's own seeders. The modules that OWN a table register their arms here at
+ * import time, and each is also the only module that READS its table - so "the
+ * module is loaded" and "core's arms are installed" cannot come apart. A seeder
+ * somebody has to remember to call is a seeder that gets forgotten on one path,
+ * and the failure mode here is silent: every randart comes out blank.
+ */
+const seeders: Array<(reg: RandartRegistry) => void> = [];
+
+let live = new RandartRegistry();
+
+/** Install a set of core arms, now and on every reset. A MOD never calls this. */
+export function seedRandart(seed: (reg: RandartRegistry) => void): void {
+  seeders.push(seed);
+  seed(live);
+}
+
+/** The live registry. Module-level; see this file's header for why that is safe. */
+export function randartRegistry(): RandartRegistry {
+  return live;
+}
+
+/**
+ * Back to core's arms alone, dropping every mod registration - the same state a
+ * reload produces, without needing a fresh realm. No production caller by
+ * design; see this file's header.
+ */
+export function resetRandartRegistry(): void {
+  live = new RandartRegistry();
+  for (const seed of seeders) seed(live);
+}

package/src/obj/randart-vectors.fixtures.ts

@@ -0,0 +1,61 @@
+/**
+ * The registry and constants a randart vector is recorded against, built from
+ * the real shipped content pack.
+ *
+ * SEPARATE FILE, and it reads the disk: keeping node:fs out of
+ * `randart-vectors.ts` means that module stays importable from anywhere. ONE
+ * copy, shared by `randart-vectors.test.ts` and by
+ * `scripts/gen-randart-vectors.mjs`, so the test and the generator cannot
+ * disagree about what they are measuring.
+ *
+ * The projections are bound for a reason that is not decoration: `add_brand`
+ * (obj-randart.c:1951) compares the brand it picked against `projections[i].name`
+ * to grant the matching resist, so a registry without them cannot run
+ * `do_randart` at all.
+ */
+
+import { readFileSync } from "node:fs";
+import { bindConstants } from "../constants.js";
+import type { Constants } from "../constants.js";
+import { bindProjections } from "../world/projection.js";
+import type { ProjectionRecordJson } from "../world/projection.js";
+import { ObjRegistry } from "./bind.js";
+import type { ObjPackJson } from "./types.js";
+import type { RandartVectorFixtures } from "./randart-vectors.js";
+
+function loadJson<T>(name: string): T {
+  return JSON.parse(
+    readFileSync(new URL(`../../../content/pack/${name}.json`, import.meta.url), "utf8"),
+  ) as T;
+}
+
+export function randartVectorFixtures(): RandartVectorFixtures {
+  /* Parsed ONCE; a fresh ObjRegistry is built per call from the same records,
+   * because the whole-set family wants a registry no earlier seed has run
+   * against. */
+  const pack = {
+    objectBase: loadJson("object_base"),
+    object: loadJson("object"),
+    egoItem: loadJson("ego_item"),
+    artifact: loadJson("artifact"),
+    curse: loadJson("curse"),
+    brand: loadJson("brand"),
+    slay: loadJson("slay"),
+    activation: loadJson("activation"),
+    objectProperty: loadJson("object_property"),
+    flavor: loadJson("flavor"),
+  } as ObjPackJson;
+  const projectionRecords = loadJson<{ records: ProjectionRecordJson[] }>(
+    "projection",
+  ).records;
+  const constants = bindConstants(loadJson("constants"));
+
+  return {
+    registry(): ObjRegistry {
+      const reg = new ObjRegistry(pack);
+      reg.projections = bindProjections(projectionRecords);
+      return reg;
+    },
+    constants: (): Constants => constants,
+  };
+}