@rpgm-tools/neo-angband-core 0.10.0

package/src/index.ts

@@ -0,0 +1,250 @@
+/**
+ * @rpgm-tools/neo-angband-core - the headless game engine.
+ *
+ * Phase 0 scaffold. The engine grows here by dependency order:
+ * rng -> dice/expressions -> flags -> world kernel -> entities ->
+ * effects -> game loop. See docs/PORT_PLAN.md at the repository root.
+ *
+ * Parity baseline: Angband 4.2.6 (see reference/ and parity/).
+ */
+
+export * from "./rng.js";
+export * from "./loc.js";
+export * from "./events.js";
+export * from "./cmd.js";
+export * from "./msg.js";
+export * from "./color.js";
+export * from "./bitflag.js";
+export * from "./guard.js";
+export * from "./expression.js";
+export * from "./dice.js";
+export * from "./generated/index.js";
+export * from "./constants.js";
+
+export * from "./version.js";
+export * from "./world/feature.js";
+export * from "./world/chunk.js";
+export * from "./world/view.js";
+export * from "./world/scatter.js";
+export * from "./world/flow.js";
+export * from "./world/project.js";
+export * from "./world/projection.js";
+export * from "./world/trap.js";
+export * from "./effects/effect.js";
+export * from "./effects/effect-info.js";
+export * from "./effects/effect-choice.js";
+export * from "./effects/interpreter.js";
+export * from "./effects/handlers.js";
+export * from "./mon/types.js";
+export * from "./mon/bind.js";
+export * from "./mon/monster.js";
+export * from "./mon/make.js";
+export * from "./mon/summon.js";
+export * from "./mon/predicate.js";
+export * from "./mon/timed.js";
+export * from "./mon/take-hit.js";
+export * from "./mon/spell.js";
+export * from "./mon/desc.js";
+export * from "./mon/knowledge-groups.js";
+export * from "./mon/project-mon.js";
+export * from "./obj/types.js";
+export * from "./obj/bind.js";
+export * from "./obj/object.js";
+export * from "./obj/chest.js";
+export * from "./obj/make.js";
+export * from "./obj/power.js";
+export * from "./obj/value.js";
+export * from "./obj/knowledge.js";
+export * from "./obj/ignore.js";
+export * from "./obj/known-object.js";
+export * from "./obj/artifact-known.js";
+export * from "./obj/artifact-fake.js";
+export * from "./obj/desc.js";
+export * from "./obj/object-info.js";
+export * from "./obj/randname.js";
+export * from "./obj/flavor.js";
+export * from "./obj/randart.js";
+export * from "./player/types.js";
+export * from "./player/options.js";
+export * from "./player/bind.js";
+export * from "./player/player.js";
+export * from "./player/calcs.js";
+export * from "./player/timed.js";
+export * from "./player/take-hit.js";
+export * from "./player/spell.js";
+export * from "./player/birth.js";
+export * from "./player/history.js";
+export * from "./player/abilities.js";
+export * from "./player/shape-lore.js";
+export * from "./save/buffer.js";
+export * from "./save/compress.js";
+export * from "./save/description.js";
+export * from "./save/integrity.js";
+export * from "./gen/util.js";
+export * from "./gen/room.js";
+export * from "./gen/cave.js";
+export * from "./gen/generate.js";
+/* gen-monster's pit machinery: resolvePits is the last piece of a GenDeps a
+ * caller outside core cannot otherwise build, so a mod that wants to run
+ * generateLevel itself (or test a levelGenerated hook against real levels) needs
+ * it. Everything else here is the same generation vocabulary gen/util already
+ * publishes. */
+export * from "./gen/gen-monster.js";
+export * from "./combat/index.js";
+export * from "./store/types.js";
+export * from "./store/bind.js";
+export * from "./store/price.js";
+export * from "./store/store.js";
+export * from "./store/transact.js";
+export * from "./store/store-cmd.js";
+export * from "./session/boot.js";
+export * from "./session/game.js";
+export * from "./session/save.js";
+/* The behaviour seam itself: ModHooks (the closed set of extension points) and
+ * composeModHooks (the host's fold over several mods' contributions). A mod
+ * cannot write a hook without the type, and a host cannot install one without
+ * the fold, so both are part of the published API - see mod/hooks.ts. */
+export * from "./mod/hooks.js";
+export * from "./mod/save-blocks.js";
+export * from "./mod/ids.js";
+export * from "./mod/registry-host.js";
+export * from "./mod/vocabulary.js";
+export * from "./agent/index.js";
+export * from "./game/energy.js";
+export * from "./game/context.js";
+export * from "./game/monster-turn.js";
+export * from "./game/scheduler.js";
+export * from "./game/player-turn.js";
+export * from "./game/project-monster.js";
+export * from "./game/project-player.js";
+export * from "./game/project-cast.js";
+export * from "./game/effect-env.js";
+export * from "./game/effect-game-env.js";
+export * from "./game/effect-attack.js";
+export * from "./game/effect-general.js";
+export * from "./game/effect-monster.js";
+export * from "./game/effect-teleport.js";
+export * from "./game/effect-terrain.js";
+export * from "./game/effect-item.js";
+export * from "./game/effect-melee.js";
+export * from "./game/effect-summon.js";
+export * from "./game/effect-detect.js";
+export * from "./game/known.js";
+export * from "./game/inscription-confirm.js";
+export * from "./game/target.js";
+export * from "./game/target-loop.js";
+export * from "./game/mon-cmd.js";
+export * from "./game/describe.js";
+export * from "./game/history.js";
+export * from "./game/object-inspect.js";
+export * from "./game/mon-message.js";
+export * from "./game/mon-list.js";
+export * from "./game/obj-list.js";
+export * from "./game/display.js";
+export * from "./game/char-sheet.js";
+export * from "./game/lore-color.js";
+export * from "./game/ui-entry.js";
+export * from "./game/equip-cmp.js";
+export * from "./game/mon-shape.js";
+export * from "./mon/lore.js";
+export * from "./mon/lore-describe.js";
+/* The live-cave placement family shares upstream names with its
+ * generation-time twin in gen/util; the live variants export Live-suffixed. */
+export {
+  squareIsOpenLive,
+  squareIsEmptyLive,
+  squareAllowsSummon,
+  placeNewMonsterOne,
+  placeNewMonster as placeNewMonsterLive,
+  pickAndPlaceMonster as pickAndPlaceMonsterLive,
+  summonSpecific,
+  selectShape,
+  wipeMonsterCounts,
+  countMonsterRaces,
+} from "./game/mon-place.js";
+export type {
+  MonPlaceDeps as LiveMonPlaceDeps,
+  SummonDeps,
+} from "./game/mon-place.js";
+export * from "./game/thrust.js";
+export * from "./game/mon-cast.js";
+export * from "./game/mon-ranged.js";
+export * from "./game/mon-group.js";
+export * from "./game/floor.js";
+export * from "./game/dump-level.js";
+export * from "./game/spoil.js";
+export * from "./game/pickup.js";
+export * from "./game/obj-cmd.js";
+export * from "./game/cave-cmd.js";
+export * from "./game/chest.js";
+export * from "./game/trap.js";
+export * from "./game/spell-cmd.js";
+export * from "./game/ranged-cmd.js";
+export * from "./game/loop.js";
+export * from "./game/ignore-cmd.js";
+/* --- Wizard / debug commands (task #29: cmd-wizard.c / wiz-debug.c) ---
+ * The debug/cheat command surface, gated behind the WizardDeps.wizard flag
+ * (upstream ALLOW_DEBUG + NOSCORE_WIZARD); unreachable in faithful play. */
+export * from "./game/wizard.js";
+export * from "./sound/index.js";
+
+/* --- High scores (task #28: score.c / score-util.c / ui-score.c) --- */
+export * from "./score/types.js";
+export * from "./score/score.js";
+export * from "./score/display.js";
+
+/* --- Graphics/tiles + visuals (task #27: grafmode.c / ui-visuals.c) --- */
+export * from "./visuals/index.js";
+
+/* --- The host layer (z-file.c + init.c's ANGBAND_DIR_*) ---
+ * The injectable seam that lets a front end declare what its platform can do
+ * instead of letting the platform's limits quietly redefine the game. Adapters
+ * live with their front ends (web, cli, desktop); MemoryHost is the reference
+ * implementation and what the tests drive. */
+export * from "./host/io.js";
+export * from "./host/memory.js";
+export * from "./host/raw.js";
+export * from "./host/bridge.js";
+export * from "./host/args.js";
+
+// Some small derived constants and geometry helpers are defined
+// independently by more than one domain (identical values/behavior).
+// Re-export a single canonical copy so the barrel is unambiguous rather
+// than dropping the name from two colliding `export *`s.
+// - OF_SIZE/ELEM_MAX: flag-array sizes derived from the generated lists,
+//   defined by both obj/types and player/types.
+// - nextGrid: next_grid(grid, dir), defined by both world/view and
+//   gen/util as grid + DDGRID[dir].
+export { OF_SIZE, ELEM_MAX } from "./obj/types.js";
+export { nextGrid } from "./world/view.js";
+// objDescNameFormat: obj/bind has a reduced &-stripping helper (sval name
+// matching); obj/desc has the full obj_desc_name_format (modstr + pluralise).
+// Expose the full port as canonical; bind's stays internal to its module.
+export { objDescNameFormat } from "./obj/desc.js";
+// CriticalLevel is defined by both constants (parsed data) and combat/hit
+// (with msg typed as the specific HitType). Crit levels are a combat
+// concept; expose combat/hit's as canonical.
+export type { CriticalLevel } from "./combat/hit.js";
+// Combat message types for shells rendering py_attack text (the combat code
+// returns HitType keys only; the text is a UI concern - see combat/melee.ts).
+export type { MeleeAttack, MeleeBlow } from "./combat/melee.js";
+export type { HitType } from "./combat/hit.js";
+// - EXTRACT_ENERGY/turnEnergy: the extract_energy[] table and turn_energy()
+//   live in mon/monster; game/energy re-exports them for convenience, so
+//   pin mon/monster as the single canonical source.
+// - squareIsEmpty: two genuinely different predicates share the name -
+//   gen/util's is a generation-time check (takes a Gen), game/context's is
+//   a live occupancy check (takes a GameState). Keep gen/util's as the
+//   barrel-canonical (it predates game/); game/context's is reached via its
+//   module and will get an aliased export if the game API needs it publicly.
+export { EXTRACT_ENERGY, turnEnergy } from "./mon/monster.js";
+export { squareIsEmpty } from "./gen/util.js";
+// - squareCanPutItem: like squareIsEmpty, a generation-time predicate
+//   (gen/util, takes a Gen) and a live-cave one (game/floor, takes a
+//   GameState) share the name; gen/util's stays barrel-canonical and the
+//   live one is reached via its module.
+export { squareCanPutItem } from "./gen/util.js";
+// - placeTrap: gen/util's generation-time marker vs game/trap's live
+//   place_trap; same convention, gen/util's stays barrel-canonical.
+export { placeTrap } from "./gen/util.js";
+export * from "./game/gear.js";

package/src/loc.ts

@@ -0,0 +1,157 @@
+/**
+ * Grid locations and keypad-direction tables, ported from
+ * reference/src/z-type.h, z-type.c, and the direction tables plus
+ * distance() from reference/src/cave.c and cave-view.c (Angband 4.2.6).
+ *
+ * Locations are plain immutable value objects; y grows downward (screen
+ * order) exactly as upstream. Directions use keypad numbering: 5 is
+ * "no direction", 2/4/6/8 orthogonal, 1/3/7/9 diagonal.
+ */
+
+import type { Rng } from "./rng.js";
+
+export interface Loc {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Construct a location. */
+export function loc(x: number, y: number): Loc {
+  return { x, y };
+}
+
+/** loc_eq: value equality. */
+export function locEq(a: Loc, b: Loc): boolean {
+  return a.x === b.x && a.y === b.y;
+}
+
+/** loc_is_zero. */
+export function locIsZero(a: Loc): boolean {
+  return a.x === 0 && a.y === 0;
+}
+
+/** loc_sum. */
+export function locSum(a: Loc, b: Loc): Loc {
+  return loc(a.x + b.x, a.y + b.y);
+}
+
+/** loc_diff: a - b. */
+export function locDiff(a: Loc, b: Loc): Loc {
+  return loc(a.x - b.x, a.y - b.y);
+}
+
+/** loc_offset. */
+export function locOffset(a: Loc, dx: number, dy: number): Loc {
+  return loc(a.x + dx, a.y + dy);
+}
+
+/** rand_loc: a location spread uniformly around `grid`. */
+export function randLoc(
+  rng: Rng,
+  grid: Loc,
+  xSpread: number,
+  ySpread: number,
+): Loc {
+  return loc(rng.randSpread(grid.x, xSpread), rng.randSpread(grid.y, ySpread));
+}
+
+/**
+ * distance: the upstream integer approximation
+ * (longer axis + half the shorter axis).
+ */
+export function distance(a: Loc, b: Loc): number {
+  const ay = Math.abs(b.y - a.y);
+  const ax = Math.abs(b.x - a.x);
+  return ay > ax ? ay + (ax >> 1) : ax + (ay >> 1);
+}
+
+/**
+ * ddd: the cycle of directions, southward then clockwise, ending with 5.
+ */
+export const DDD: readonly number[] = [2, 8, 6, 4, 3, 1, 9, 7, 5];
+
+/** ddx: keypad direction -> x offset (index 0 unused). */
+export const DDX: readonly number[] = [0, -1, 0, 1, -1, 0, 1, -1, 0, 1];
+
+/** ddy: keypad direction -> y offset (index 0 unused). */
+export const DDY: readonly number[] = [0, 1, 1, 1, 0, 0, 0, -1, -1, -1];
+
+/** ddgrid: keypad direction -> Loc offset (index 0 unused). */
+export const DDGRID: readonly Loc[] = [
+  { x: 0, y: 0 },
+  { x: -1, y: 1 },
+  { x: 0, y: 1 },
+  { x: 1, y: 1 },
+  { x: -1, y: 0 },
+  { x: 0, y: 0 },
+  { x: 1, y: 0 },
+  { x: -1, y: -1 },
+  { x: 0, y: -1 },
+  { x: 1, y: -1 },
+];
+
+/** ddx_ddd: x offsets in ddd order. */
+export const DDX_DDD: readonly number[] = [0, 0, 1, -1, 1, -1, 1, -1, 0];
+
+/** ddy_ddd: y offsets in ddd order. */
+export const DDY_DDD: readonly number[] = [1, -1, 0, 0, 1, 1, -1, -1, 0];
+
+/** ddgrid_ddd: Loc offsets in ddd order. */
+export const DDGRID_DDD: readonly Loc[] = [
+  { x: 0, y: 1 },
+  { x: 0, y: -1 },
+  { x: 1, y: 0 },
+  { x: -1, y: 0 },
+  { x: 1, y: 1 },
+  { x: -1, y: 1 },
+  { x: 1, y: -1 },
+  { x: -1, y: -1 },
+  { x: 0, y: 0 },
+];
+
+/**
+ * clockwise_ddd: can multiply the index by 45 degrees, e.g. index 6 is
+ * 270 degrees (9 o'clock).
+ */
+export const CLOCKWISE_DDD: readonly number[] = [8, 9, 6, 3, 2, 1, 4, 7, 5];
+
+/** clockwise_grid: Loc offsets in clockwise order starting north. */
+export const CLOCKWISE_GRID: readonly Loc[] = [
+  { x: 0, y: -1 },
+  { x: 1, y: -1 },
+  { x: 1, y: 0 },
+  { x: 1, y: 1 },
+  { x: 0, y: 1 },
+  { x: -1, y: 1 },
+  { x: -1, y: 0 },
+  { x: -1, y: -1 },
+  { x: 0, y: 0 },
+];
+
+/**
+ * side_dirs: alternative sideways/backup directions for each keypad
+ * direction, in order of decreasing desirability. Rows 0-9 bias right,
+ * rows 10-19 bias left.
+ */
+export const SIDE_DIRS: readonly (readonly number[])[] = [
+  [0, 0, 0, 0, 0, 0, 0, 0],
+  [1, 4, 2, 7, 3, 8, 6, 9],
+  [2, 1, 3, 4, 6, 7, 9, 8],
+  [3, 2, 6, 1, 9, 4, 8, 7],
+  [4, 7, 1, 8, 2, 9, 3, 6],
+  [5, 5, 5, 5, 5, 5, 5, 5],
+  [6, 3, 9, 2, 8, 1, 7, 4],
+  [7, 8, 4, 9, 1, 6, 2, 3],
+  [8, 9, 7, 6, 4, 3, 1, 2],
+  [9, 6, 8, 3, 7, 2, 4, 1],
+  [0, 0, 0, 0, 0, 0, 0, 0],
+  [1, 2, 4, 3, 7, 6, 8, 9],
+  [2, 3, 1, 6, 4, 9, 7, 8],
+  [3, 6, 2, 9, 1, 8, 4, 7],
+  [4, 1, 7, 2, 8, 3, 9, 6],
+  [5, 5, 5, 5, 5, 5, 5, 5],
+  [6, 9, 3, 8, 2, 7, 1, 4],
+  [7, 4, 8, 1, 9, 2, 6, 3],
+  [8, 7, 9, 4, 6, 1, 3, 2],
+  [9, 8, 6, 7, 3, 4, 2, 1],
+];

package/src/mod/hooks.ts

@@ -0,0 +1,278 @@
+/**
+ * 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.
+ */
+
+import type { GameState } from "../game/context.js";
+
+/**
+ * A mod's behaviour contributions. Every member is optional; an absent member
+ * means "this mod does not touch that point" and core takes its faithful path.
+ *
+ * Each entry documents the ONE core call site it serves, because a hook whose
+ * call site is not written down is a hook nobody can verify is still wired -
+ * exactly the failure the call-site census exists to catch.
+ */
+export interface ModHooks {
+  /**
+   * A walk into a grid the player could tunnel through (cave-cmd.ts,
+   * movementAutoDig's call site).
+   *
+   * Return the energy the move should cost, or null to decline - and declining
+   * MUST be free of observable effect, because faithful core's behaviour here is
+   * to bump into the wall without drawing any RNG. A hook that rolls a dig check
+   * and then returns null has already moved the RNG stream.
+   *
+   * `deps` is the live CaveCmdDeps the session built, passed through because the
+   * work a mod would want to do here (tunnelAux - one real dig attempt with the
+   * upstream roll and payouts) needs dependencies only the session can construct.
+   * Typed as unknown so this seam does not drag the cave-command types into every
+   * consumer of ModHooks; a mod casts it back to CaveCmdDeps, which core exports.
+   *
+   * Serves: the QoL mod's "auto-dig on walk".
+   */
+  walkBlockedByDiggable?: (
+    state: GameState,
+    grid: { y: number; x: number },
+    deps: unknown,
+  ) => number | null;
+
+  /**
+   * Two floor-list entries that compared exactly equal, including on distance
+   * (obj-list.ts, the comparator's final tiebreak).
+   *
+   * Return a negative/positive number to order them, or 0 to leave them equal
+   * (which is what faithful core does - it keeps collect order via a stable
+   * sort). Must be a consistent total order or the sort is meaningless.
+   *
+   * Serves: the bug-fixes mod's strict object-list ordering (#4664).
+   */
+  objectListTiebreak?: (
+    a: { readonly dy: number; readonly dx: number },
+    b: { readonly dy: number; readonly dx: number },
+  ) => number;
+
+  /**
+   * A finished, otherwise-accepted level, before cave_generate returns it
+   * (generate.ts, the accept branch).
+   *
+   * Return false to REJECT the level, which makes cave_generate re-roll exactly
+   * as it does for a monster-maximum overflow. May mutate the level to repair it
+   * and then return true.
+   *
+   * RNG-FREE: no rng is passed and none may be reached. A draw here shifts every
+   * subsequent draw and a seed stops reproducing its dungeon.
+   *
+   * Serves: the bug-fixes mod's reachable-staircase repair.
+   */
+  levelGenerated?: (gen: unknown, quest: boolean) => boolean;
+
+  /**
+   * An object about to be committed as an artifact, when it ALREADY carries one
+   * (obj/make.ts, the `obj.artifact` branch).
+   *
+   * Return false to refuse the commit; the caller then clears the artifact and
+   * reports failure. Faithful core commits it unconditionally.
+   *
+   * RNG-FREE, for the same reason as levelGenerated: this runs inside object
+   * creation, on the main stream.
+   *
+   * Serves: the bug-fixes mod's duplicate-artifact guard (#4510).
+   */
+  artifactCommit?: (aidx: number, alreadyCreated: boolean) => boolean;
+
+  /**
+   * A character-history entry about to be written (session/game.ts and any
+   * other historyAdd call site that passes its context).
+   *
+   * Return false to suppress the entry. Faithful core writes every entry it
+   * reaches, duplicates included.
+   *
+   * Serves: the bug-fixes mod's no-duplicate-unique-kill fix (#4245).
+   */
+  historyAdd?: (entry: { readonly what: string; readonly type: number; readonly duplicate: boolean }) => boolean;
+
+  /**
+   * Whether the noise and scent heatmaps belong in the save (session/save.ts,
+   * snapshotSquares' argument).
+   *
+   * Return true to persist them. Faithful core omits them, which is the upstream
+   * behaviour and the upstream bug.
+   *
+   * Serves: the bug-fixes mod's noise/scent persistence (#4605).
+   */
+  saveNoiseScent?: () => boolean;
+
+  /**
+   * Player-visible message text, on its way to the message line (the host's
+   * message sink).
+   *
+   * Return the text to show. Faithful core shows what it was given, warts and
+   * all. A hook here can only RESTATE a message - it must never change what a
+   * message means, or the port would be showing text upstream never wrote and no
+   * census could see it.
+   *
+   * Serves: the bug-fixes mod's cosmetic string corrections.
+   */
+  messageText?: (raw: string) => string;
+}
+
+/**
+ * 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: readonly ModHooks[],
+): ModHooks | undefined {
+  const list = contributions.filter((c) => Object.keys(c).length > 0);
+  if (list.length === 0) return undefined;
+
+  const out: ModHooks = {};
+
+  const walk = list.map((c) => c.walkBlockedByDiggable).filter(isFn);
+  if (walk.length > 0) {
+    out.walkBlockedByDiggable = (state, grid, deps): number | null => {
+      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): number => {
+      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): boolean => {
+      /* 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): boolean => {
+      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): boolean => {
+      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 = (): boolean => noise.some((fn) => fn());
+  }
+
+  const text = list.map((c) => c.messageText).filter(isFn);
+  if (text.length > 0) {
+    out.messageText = (raw): string => text.reduce((s, fn) => fn(s), raw);
+  }
+
+  return out;
+}
+
+function isFn<T>(v: T | undefined): v is T {
+  return typeof v === "function";
+}