@rpgm-tools/neo-angband-core 0.10.0

package/dist/mod/hooks.js

@@ -0,0 +1,161 @@
+/**
+ * The behaviour seam: the closed set of points where a mod may change what the
+ * ENGINE does, as opposed to what content it runs on.
+ *
+ * WHY THIS EXISTS
+ *
+ * Content mods are already fully expressible - a pack contributes records and
+ * composeContentPacks merges them, and core never learns a mod was involved.
+ * Behaviour is different. A fix like "don't log a duplicate unique kill" is not a
+ * record; it is a decision taken inside a function, and no amount of data can
+ * reach inside that function from outside. So the first cut of the bundled
+ * bug-fixes / QoL mods did the only thing that was available: the FIX LIVED IN
+ * CORE behind `if (modRuleEnabled(state, "bugfix.x"))`.
+ *
+ * That was wrong, and neostryder named exactly why (2026-07-29): "the whole point of
+ * making them mods was to exclude them from the core game." A flag-gated fix is
+ * not excluded from core. It ships in core, it is tested in core, and core
+ * carries the string "bugfix.uniqueKillHistory" - so core knows the mod's name.
+ * Deleting the mod folder would not delete one line of it.
+ *
+ * WHAT THIS CHANGES, AND WHAT IT HONESTLY DOES NOT
+ *
+ * After this, core contains no mod's fix and no mod's name: no `bugfix.*` or
+ * `qol.*` literal, no staircase repair, no message rewriter. Each fix body lives
+ * in its mod's own folder and arrives as that mod's code.
+ *
+ * What core still contains - and cannot stop containing - is the SEAM ITSELF:
+ * one named, documented extension point per behaviour a mod may override. That
+ * is not a residue of the bundled mods; it is the price of behaviour modding at
+ * all, and it is the same bargain SKSE, Forge and every other real modding
+ * system strikes. The difference from a flag read is the difference that matters:
+ * a seam is generic and available to ANY mod, and it holds no opinion about what
+ * should plug into it, whereas `if (modRuleEnabled(state, "bugfix.stairsReachable"))`
+ * is core implementing one specific mod.
+ *
+ * SHAPE
+ *
+ * A plain interface of optional functions rather than a string-keyed registry,
+ * for three reasons:
+ *
+ *  - It is typed end to end. A registry keyed by strings pushes every payload
+ *    through `unknown` and moves the errors to runtime.
+ *  - "A disabled mod's patches DO NOT EXIST" becomes literally true, not merely
+ *    false-y: with no mod loaded the field is ABSENT, the optional call is not
+ *    made, and the faithful path is the only path that was ever compiled into
+ *    the branch. No flag map is consulted because there is no flag map.
+ *  - It costs nothing. `state.modHooks?.historyAdd?.(...)` on an absent object is
+ *    one undefined check, not a map lookup per call.
+ *
+ * COMPOSITION IS THE HOST'S JOB
+ *
+ * Two enabled mods may both want the same hook. Core deliberately holds ONE
+ * ModHooks and knows nothing about mod identity, ordering or enablement - the
+ * host (web/cli) collects each enabled mod's contributions in load order and
+ * folds them into a single object (see composeModHooks). This is the same
+ * layering as content: core consumes a composed result and never the pack list.
+ *
+ * DETERMINISM
+ *
+ * Two of these run inside the generation and object pipelines, where an extra
+ * RNG draw does not merely change a value, it desynchronises every draw after
+ * it - so a seed would stop meaning the same level. Those hooks are documented
+ * RNG-FREE and are given no rng to draw from. That is a contract a mod can still
+ * break by reaching for a global; the test suite pins it by running generation
+ * with a hook installed and asserting the level is bit-identical.
+ */
+/**
+ * Fold several mods' contributions into the single ModHooks core holds.
+ *
+ * Order is LOAD order, and what "later wins" means differs per hook because the
+ * hooks differ in kind - which is precisely why this is one written-down function
+ * and not a generic merge:
+ *
+ *  - VETO hooks (levelGenerated, artifactCommit, historyAdd) are conjunctive:
+ *    every contributor must agree, and the first refusal decides. This is the
+ *    only safe fold - a mod that vetoes a duplicate artifact must not be
+ *    overruled by a later mod that merely has no opinion.
+ *  - TRANSFORM hooks (messageText) compose in order, each seeing the previous
+ *    one's output.
+ *  - FIRST-HANDLER hooks (walkBlockedByDiggable) stop at the first non-null, so
+ *    an earlier mod's handling wins and a later one cannot double-spend energy.
+ *  - ANY hooks (saveNoiseScent) are disjunctive: one mod asking for the data is
+ *    enough, because the data is additive and a second mod cannot object.
+ *  - ORDERING hooks (objectListTiebreak) stop at the first non-zero answer, the
+ *    same way a lexicographic comparator chains.
+ *
+ * Returns undefined when nothing contributed, so the caller can leave the field
+ * absent rather than storing an empty object - keeping "no mod loaded" and "a
+ * mod loaded that touches nothing" indistinguishable from core's side.
+ */
+export function composeModHooks(contributions) {
+    const list = contributions.filter((c) => Object.keys(c).length > 0);
+    if (list.length === 0)
+        return undefined;
+    const out = {};
+    const walk = list.map((c) => c.walkBlockedByDiggable).filter(isFn);
+    if (walk.length > 0) {
+        out.walkBlockedByDiggable = (state, grid, deps) => {
+            for (const fn of walk) {
+                const energy = fn(state, grid, deps);
+                if (energy !== null)
+                    return energy;
+            }
+            return null;
+        };
+    }
+    const tiebreak = list.map((c) => c.objectListTiebreak).filter(isFn);
+    if (tiebreak.length > 0) {
+        out.objectListTiebreak = (a, b) => {
+            for (const fn of tiebreak) {
+                const r = fn(a, b);
+                if (r !== 0)
+                    return r;
+            }
+            return 0;
+        };
+    }
+    const level = list.map((c) => c.levelGenerated).filter(isFn);
+    if (level.length > 0) {
+        out.levelGenerated = (gen, quest) => {
+            /* Every contributor runs even after one has repaired the level, because a
+             * second mod's invariant is not satisfied by the first mod's repair. The
+             * first REFUSAL short-circuits, since the level is being thrown away. */
+            for (const fn of level)
+                if (!fn(gen, quest))
+                    return false;
+            return true;
+        };
+    }
+    const artifact = list.map((c) => c.artifactCommit).filter(isFn);
+    if (artifact.length > 0) {
+        out.artifactCommit = (aidx, alreadyCreated) => {
+            for (const fn of artifact)
+                if (!fn(aidx, alreadyCreated))
+                    return false;
+            return true;
+        };
+    }
+    const history = list.map((c) => c.historyAdd).filter(isFn);
+    if (history.length > 0) {
+        out.historyAdd = (entry) => {
+            for (const fn of history)
+                if (!fn(entry))
+                    return false;
+            return true;
+        };
+    }
+    const noise = list.map((c) => c.saveNoiseScent).filter(isFn);
+    if (noise.length > 0) {
+        out.saveNoiseScent = () => noise.some((fn) => fn());
+    }
+    const text = list.map((c) => c.messageText).filter(isFn);
+    if (text.length > 0) {
+        out.messageText = (raw) => text.reduce((s, fn) => fn(s), raw);
+    }
+    return out;
+}
+function isFn(v) {
+    return typeof v === "function";
+}
+//# sourceMappingURL=hooks.js.map

package/dist/mod/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/mod/hooks.ts"],"names":[],"mappings":"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"}

package/dist/mod/ids.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Content ids: the load-bearing rule of the mod substrate (MOD_LIFECYCLE.md
+ * section 1, decision 19/1). Saves reference content by a stable namespaced
+ * string id - `core:kobold`, `frost:frost-wyrm` - never by a numeric array
+ * index. Upstream Angband serializes an r_idx / k_idx (an array position);
+ * add or remove one record and every later index shifts, silently corrupting
+ * older saves. Ids never move: adding, removing, or reordering content leaves
+ * every existing id pointing at the same thing.
+ *
+ * An id is `<namespace>:<localid>`. The namespace is the owning pack (`core`
+ * for the base game, pack zero). The localid is derived from the entity's own
+ * stable fields (its name/code, and for object kinds its tval) - so for the
+ * overwhelming majority of content it is identical no matter what else is
+ * loaded; only genuine duplicate names take an order-dependent suffix (see
+ * below). The localid is only required to be unique WITHIN its registry and
+ * namespace: an id's entity TYPE is implied by where it appears in the save (a
+ * kind reference is always a kind id), so a kind and a race may share a
+ * localid without ambiguity.
+ *
+ * This module is the one place ids are minted and resolved. The
+ * ContentIdResolver builds both directions (index <-> id) once from the bound
+ * registries.
+ *
+ * Duplicate names are real. Angband content is not name-unique: some egos
+ * ship twice under one name (e.g. "of Slay Animal" for both melee and
+ * launchers), several traps share a name with different effects ("dart trap"
+ * appears three times), and the "greater" variants ("*Healing*" vs "Healing")
+ * slug to the same token. A raw name therefore cannot be the key. When two
+ * entities in one registry would mint the same localid, the later one (in the
+ * registry's own binding order) gets a numeric suffix - `of-slay-animal`,
+ * `of-slay-animal-2`. This is deterministic and applied identically when
+ * writing and when reading a save, so the round-trip is exact. It is stable
+ * as long as content is APPENDED (mods live in their own namespace; core's
+ * frozen datafiles and cross-version additions append), which is the same
+ * append-only assumption every mod ecosystem relies on - and strictly less
+ * fragile than upstream's bare-index scheme, which breaks on ANY reorder.
+ */
+import type { ObjRegistry } from "../obj/bind.js";
+import type { MonsterRace } from "../mon/types.js";
+import type { PlayerClass, PlayerRace } from "../player/types.js";
+import type { FeatureRegistry } from "../world/feature.js";
+import type { TrapKind } from "../world/trap.js";
+/** The base game's namespace (pack zero). */
+export declare const CORE_NS = "core";
+/** The namespace / localid separator (localids may contain further colons). */
+export declare const ID_SEP = ":";
+/**
+ * Kebab-slug a display name or code into an id-safe token: lowercase, every
+ * run of non-alphanumerics collapsed to a single hyphen, leading/trailing
+ * hyphens trimmed. Deterministic and pure, so the same name always yields the
+ * same token. "Ring of Barahir" -> "ring-of-barahir", "FIRE_3" -> "fire-3".
+ */
+export declare function slug(text: string): string;
+/** Compose a namespaced id from a namespace and a localid. */
+export declare function makeId(namespace: string, localid: string): string;
+/** A core-namespaced id from a localid. */
+export declare function coreId(localid: string): string;
+/**
+ * Split an id into its namespace and localid on the FIRST separator only, so
+ * a localid may itself contain the separator (object kinds use `tval:name`).
+ * Returns null when the string carries no separator.
+ */
+export declare function parseId(id: string): {
+    namespace: string;
+    localid: string;
+} | null;
+/**
+ * An object kind's localid is `<tval>:<name>`, both slugged: the kind name
+ * alone is not unique across tvals (a base "Dagger" and a hypothetical potion
+ * of the same name would collide), but tval+name is the natural key upstream
+ * lookup_kind uses. The sval is deliberately NOT part of the id: svals are
+ * assigned in file order and shift when kinds are inserted, exactly the
+ * fragility ids exist to avoid.
+ */
+export declare function kindLocalId(tval: number, name: string): string;
+/**
+ * The registries the resolver needs; a subset of CoreRegistries. Only
+ * `objects` is required: the monster / feature / trap registries are optional
+ * so a caller that only serializes object references (a focused test) can build
+ * a partial resolver. Production (loadGame/saveGame) always passes the full set.
+ */
+export interface ContentIdRegistries {
+    objects: ObjRegistry;
+    monsters?: {
+        races: readonly MonsterRace[];
+    };
+    features?: FeatureRegistry;
+    traps?: readonly TrapKind[] | null;
+    /**
+     * Player races/classes are optional: the save format does not reference them
+     * by id (a character carries its own race/class record), but the agent
+     * perceive facade exposes namespaced player race/class ids when they are
+     * supplied here, so every entity in the agent contract has a stable id.
+     */
+    playerRaces?: readonly PlayerRace[];
+    playerClasses?: readonly PlayerClass[];
+}
+/**
+ * Builds and holds the index<->id tables for every content type a save
+ * references. Constructed once per bound pack (both when writing and when
+ * reading a save); the two directions are symmetric so a save written on one
+ * registry ordering reloads correctly on any other ordering of the same ids.
+ */
+export declare class ContentIdResolver {
+    private readonly kinds;
+    private readonly egos;
+    private readonly artifacts;
+    private readonly curses;
+    private readonly brands;
+    private readonly slays;
+    private readonly races;
+    private readonly traps;
+    private readonly feats;
+    private readonly playerRaces;
+    private readonly playerClasses;
+    private readonly artifactNames;
+    constructor(reg: ContentIdRegistries, namespace?: string);
+    kindId(kidx: number): string;
+    /** The kind id for an index, or null when unbound (a partial resolver). */
+    kindIdOrNull(kidx: number): string | null;
+    kindIndex(id: string): number | undefined;
+    egoId(eidx: number): string;
+    /** The ego id for an index, or null when unbound (a partial resolver). */
+    egoIdOrNull(eidx: number): string | null;
+    egoIndex(id: string): number | undefined;
+    artifactId(aidx: number): string;
+    artifactIndex(id: string): number | undefined;
+    /** The upstream artifact NAME used by player history save/load. */
+    artifactName(aidx: number): string | null;
+    curseId(index: number): string;
+    curseIndex(id: string): number | undefined;
+    brandId(index: number): string;
+    brandIndex(id: string): number | undefined;
+    slayId(index: number): string;
+    slayIndex(id: string): number | undefined;
+    raceId(ridx: number): string;
+    /** The race id for an index, or null when unbound (a partial resolver). */
+    raceIdOrNull(ridx: number): string | null;
+    raceIndex(id: string): number | undefined;
+    trapId(tidx: number): string;
+    trapIndex(id: string): number | undefined;
+    featId(fidx: number): string;
+    /**
+     * The feature id for an index, or null when the index is not a bound feature
+     * (an unset terrain cell carries a sentinel like -1 that has no id). Used to
+     * build the terrain legend, which skips sentinels: they mean "no feature"
+     * and are pack-independent, so they never need remapping.
+     */
+    featIdOrNull(fidx: number): string | null;
+    featIndex(id: string): number | undefined;
+    playerRaceId(ridx: number): string;
+    /** The player-race id for an index, or null when player races were not supplied. */
+    playerRaceIdOrNull(ridx: number): string | null;
+    playerRaceIndex(id: string): number | undefined;
+    playerClassId(cidx: number): string;
+    /** The player-class id for an index, or null when player classes were not supplied. */
+    playerClassIdOrNull(cidx: number): string | null;
+    playerClassIndex(id: string): number | undefined;
+}
+//# sourceMappingURL=ids.d.ts.map

package/dist/mod/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/mod/ids.ts"],"names":[],"mappings":"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"}

package/dist/mod/ids.js

@@ -0,0 +1,343 @@
+/**
+ * Content ids: the load-bearing rule of the mod substrate (MOD_LIFECYCLE.md
+ * section 1, decision 19/1). Saves reference content by a stable namespaced
+ * string id - `core:kobold`, `frost:frost-wyrm` - never by a numeric array
+ * index. Upstream Angband serializes an r_idx / k_idx (an array position);
+ * add or remove one record and every later index shifts, silently corrupting
+ * older saves. Ids never move: adding, removing, or reordering content leaves
+ * every existing id pointing at the same thing.
+ *
+ * An id is `<namespace>:<localid>`. The namespace is the owning pack (`core`
+ * for the base game, pack zero). The localid is derived from the entity's own
+ * stable fields (its name/code, and for object kinds its tval) - so for the
+ * overwhelming majority of content it is identical no matter what else is
+ * loaded; only genuine duplicate names take an order-dependent suffix (see
+ * below). The localid is only required to be unique WITHIN its registry and
+ * namespace: an id's entity TYPE is implied by where it appears in the save (a
+ * kind reference is always a kind id), so a kind and a race may share a
+ * localid without ambiguity.
+ *
+ * This module is the one place ids are minted and resolved. The
+ * ContentIdResolver builds both directions (index <-> id) once from the bound
+ * registries.
+ *
+ * Duplicate names are real. Angband content is not name-unique: some egos
+ * ship twice under one name (e.g. "of Slay Animal" for both melee and
+ * launchers), several traps share a name with different effects ("dart trap"
+ * appears three times), and the "greater" variants ("*Healing*" vs "Healing")
+ * slug to the same token. A raw name therefore cannot be the key. When two
+ * entities in one registry would mint the same localid, the later one (in the
+ * registry's own binding order) gets a numeric suffix - `of-slay-animal`,
+ * `of-slay-animal-2`. This is deterministic and applied identically when
+ * writing and when reading a save, so the round-trip is exact. It is stable
+ * as long as content is APPENDED (mods live in their own namespace; core's
+ * frozen datafiles and cross-version additions append), which is the same
+ * append-only assumption every mod ecosystem relies on - and strictly less
+ * fragile than upstream's bare-index scheme, which breaks on ANY reorder.
+ */
+import { TVAL_ENTRIES } from "../generated/index.js";
+/** The base game's namespace (pack zero). */
+export const CORE_NS = "core";
+/** The namespace / localid separator (localids may contain further colons). */
+export const ID_SEP = ":";
+/**
+ * Kebab-slug a display name or code into an id-safe token: lowercase, every
+ * run of non-alphanumerics collapsed to a single hyphen, leading/trailing
+ * hyphens trimmed. Deterministic and pure, so the same name always yields the
+ * same token. "Ring of Barahir" -> "ring-of-barahir", "FIRE_3" -> "fire-3".
+ */
+export function slug(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/** Compose a namespaced id from a namespace and a localid. */
+export function makeId(namespace, localid) {
+    return namespace + ID_SEP + localid;
+}
+/** A core-namespaced id from a localid. */
+export function coreId(localid) {
+    return makeId(CORE_NS, localid);
+}
+/**
+ * Split an id into its namespace and localid on the FIRST separator only, so
+ * a localid may itself contain the separator (object kinds use `tval:name`).
+ * Returns null when the string carries no separator.
+ */
+export function parseId(id) {
+    const at = id.indexOf(ID_SEP);
+    if (at < 0)
+        return null;
+    return { namespace: id.slice(0, at), localid: id.slice(at + 1) };
+}
+/* ------------------------------------------------------------------ *
+ * Localid minting (pure functions of a single entity).
+ * ------------------------------------------------------------------ */
+/**
+ * An object kind's localid is `<tval>:<name>`, both slugged: the kind name
+ * alone is not unique across tvals (a base "Dagger" and a hypothetical potion
+ * of the same name would collide), but tval+name is the natural key upstream
+ * lookup_kind uses. The sval is deliberately NOT part of the id: svals are
+ * assigned in file order and shift when kinds are inserted, exactly the
+ * fragility ids exist to avoid.
+ */
+export function kindLocalId(tval, name) {
+    const tv = TVAL_ENTRIES[tval];
+    return slug(tv ? tv.textName : String(tval)) + ID_SEP + slug(name);
+}
+/** One bidirectional index<->id table for a single entity kind. */
+class IdTable {
+    namespace;
+    toId = [];
+    toIndex = new Map();
+    constructor(namespace) {
+        this.namespace = namespace;
+    }
+    /**
+     * Register an index's base localid. If that id is already taken (a genuine
+     * duplicate-name entity), append the first free numeric suffix so every id
+     * is unique. Called in registry-binding order, so the suffix a given entity
+     * receives is deterministic and identical across a save round-trip.
+     */
+    add(index, base) {
+        let id = makeId(this.namespace, base);
+        if (this.toIndex.has(id)) {
+            let n = 2;
+            while (this.toIndex.has(makeId(this.namespace, `${base}-${n}`)))
+                n++;
+            id = makeId(this.namespace, `${base}-${n}`);
+        }
+        this.toIndex.set(id, index);
+        this.toId[index] = id;
+    }
+    /** The id for an index, or null when the index is unbound (e.g. slot 0). */
+    id(index) {
+        return this.toId[index] ?? null;
+    }
+    /** The index for an id, or undefined when no such id is bound. */
+    index(id) {
+        return this.toIndex.get(id);
+    }
+}
+/**
+ * Builds and holds the index<->id tables for every content type a save
+ * references. Constructed once per bound pack (both when writing and when
+ * reading a save); the two directions are symmetric so a save written on one
+ * registry ordering reloads correctly on any other ordering of the same ids.
+ */
+export class ContentIdResolver {
+    kinds;
+    egos;
+    artifacts;
+    curses;
+    brands;
+    slays;
+    races;
+    traps;
+    feats;
+    playerRaces;
+    playerClasses;
+    artifactNames = new Map();
+    constructor(reg, namespace = CORE_NS) {
+        const { objects } = reg;
+        this.kinds = new IdTable(namespace);
+        for (const kind of objects.kinds) {
+            this.kinds.add(kind.kidx, kindLocalId(kind.tval, kind.name));
+        }
+        this.egos = new IdTable(namespace);
+        for (const ego of objects.egos)
+            this.egos.add(ego.eidx, slug(ego.name));
+        /* Artifacts, curses, brands, slays are 1-based with a null at slot 0. */
+        this.artifacts = new IdTable(namespace);
+        for (let i = 1; i < objects.artifacts.length; i++) {
+            const a = objects.artifacts[i];
+            if (a) {
+                this.artifacts.add(i, slug(a.name));
+                this.artifactNames.set(i, a.name);
+            }
+        }
+        this.curses = new IdTable(namespace);
+        for (let i = 1; i < objects.curses.length; i++) {
+            const c = objects.curses[i];
+            if (c)
+                this.curses.add(i, slug(c.name));
+        }
+        this.brands = new IdTable(namespace);
+        for (let i = 1; i < objects.brands.length; i++) {
+            const b = objects.brands[i];
+            if (b)
+                this.brands.add(i, slug(b.code));
+        }
+        this.slays = new IdTable(namespace);
+        for (let i = 1; i < objects.slays.length; i++) {
+            const s = objects.slays[i];
+            if (s)
+                this.slays.add(i, slug(s.code));
+        }
+        this.races = new IdTable(namespace);
+        for (const race of reg.monsters?.races ?? []) {
+            this.races.add(race.ridx, slug(race.name));
+        }
+        this.traps = new IdTable(namespace);
+        for (const trap of reg.traps ?? []) {
+            this.traps.add(trap.tidx, slug(trap.name));
+        }
+        this.feats = new IdTable(namespace);
+        for (const feat of reg.features?.allFeatures() ?? []) {
+            this.feats.add(feat.fidx, slug(feat.code));
+        }
+        this.playerRaces = new IdTable(namespace);
+        for (const race of reg.playerRaces ?? []) {
+            this.playerRaces.add(race.ridx, slug(race.name));
+        }
+        this.playerClasses = new IdTable(namespace);
+        for (const cls of reg.playerClasses ?? []) {
+            this.playerClasses.add(cls.cidx, slug(cls.name));
+        }
+    }
+    /* Object kinds. */
+    kindId(kidx) {
+        const id = this.kinds.id(kidx);
+        if (id === null)
+            throw new Error(`mod/ids: unbound kind index ${kidx}`);
+        return id;
+    }
+    /** The kind id for an index, or null when unbound (a partial resolver). */
+    kindIdOrNull(kidx) {
+        return this.kinds.id(kidx);
+    }
+    kindIndex(id) {
+        return this.kinds.index(id);
+    }
+    /* Egos (nullable reference). */
+    egoId(eidx) {
+        const id = this.egos.id(eidx);
+        if (id === null)
+            throw new Error(`mod/ids: unbound ego index ${eidx}`);
+        return id;
+    }
+    /** The ego id for an index, or null when unbound (a partial resolver). */
+    egoIdOrNull(eidx) {
+        return this.egos.id(eidx);
+    }
+    egoIndex(id) {
+        return this.egos.index(id);
+    }
+    /* Artifacts (nullable reference; 1-based). */
+    artifactId(aidx) {
+        const id = this.artifacts.id(aidx);
+        if (id === null)
+            throw new Error(`mod/ids: unbound artifact index ${aidx}`);
+        return id;
+    }
+    artifactIndex(id) {
+        return this.artifacts.index(id);
+    }
+    /** The upstream artifact NAME used by player history save/load. */
+    artifactName(aidx) {
+        return this.artifactNames.get(aidx) ?? null;
+    }
+    /* Curses (positional on objects; 1-based). */
+    curseId(index) {
+        const id = this.curses.id(index);
+        if (id === null)
+            throw new Error(`mod/ids: unbound curse index ${index}`);
+        return id;
+    }
+    curseIndex(id) {
+        return this.curses.index(id);
+    }
+    /* Brands (positional on objects; 1-based). */
+    brandId(index) {
+        const id = this.brands.id(index);
+        if (id === null)
+            throw new Error(`mod/ids: unbound brand index ${index}`);
+        return id;
+    }
+    brandIndex(id) {
+        return this.brands.index(id);
+    }
+    /* Slays (positional on objects; 1-based). */
+    slayId(index) {
+        const id = this.slays.id(index);
+        if (id === null)
+            throw new Error(`mod/ids: unbound slay index ${index}`);
+        return id;
+    }
+    slayIndex(id) {
+        return this.slays.index(id);
+    }
+    /* Monster races. */
+    raceId(ridx) {
+        const id = this.races.id(ridx);
+        if (id === null)
+            throw new Error(`mod/ids: unbound race index ${ridx}`);
+        return id;
+    }
+    /** The race id for an index, or null when unbound (a partial resolver). */
+    raceIdOrNull(ridx) {
+        return this.races.id(ridx);
+    }
+    raceIndex(id) {
+        return this.races.index(id);
+    }
+    /* Trap kinds. */
+    trapId(tidx) {
+        const id = this.traps.id(tidx);
+        if (id === null)
+            throw new Error(`mod/ids: unbound trap index ${tidx}`);
+        return id;
+    }
+    trapIndex(id) {
+        return this.traps.index(id);
+    }
+    /* Terrain features. */
+    featId(fidx) {
+        const id = this.feats.id(fidx);
+        if (id === null)
+            throw new Error(`mod/ids: unbound feature index ${fidx}`);
+        return id;
+    }
+    /**
+     * The feature id for an index, or null when the index is not a bound feature
+     * (an unset terrain cell carries a sentinel like -1 that has no id). Used to
+     * build the terrain legend, which skips sentinels: they mean "no feature"
+     * and are pack-independent, so they never need remapping.
+     */
+    featIdOrNull(fidx) {
+        return this.feats.id(fidx);
+    }
+    featIndex(id) {
+        return this.feats.index(id);
+    }
+    /* Player races (only bound when playerRaces was supplied). */
+    playerRaceId(ridx) {
+        const id = this.playerRaces.id(ridx);
+        if (id === null)
+            throw new Error(`mod/ids: unbound player race index ${ridx}`);
+        return id;
+    }
+    /** The player-race id for an index, or null when player races were not supplied. */
+    playerRaceIdOrNull(ridx) {
+        return this.playerRaces.id(ridx);
+    }
+    playerRaceIndex(id) {
+        return this.playerRaces.index(id);
+    }
+    /* Player classes (only bound when playerClasses was supplied). */
+    playerClassId(cidx) {
+        const id = this.playerClasses.id(cidx);
+        if (id === null)
+            throw new Error(`mod/ids: unbound player class index ${cidx}`);
+        return id;
+    }
+    /** The player-class id for an index, or null when player classes were not supplied. */
+    playerClassIdOrNull(cidx) {
+        return this.playerClasses.id(cidx);
+    }
+    playerClassIndex(id) {
+        return this.playerClasses.index(id);
+    }
+}
+//# sourceMappingURL=ids.js.map