@rpgm-tools/neo-angband-core 0.10.0

package/src/world/projection.ts

@@ -0,0 +1,228 @@
+/**
+ * Projection runtime data and player damage-vs-resistance scaling, ported from
+ * reference/src/project.h (struct projection, loaded from projection.txt) and
+ * reference/src/project-player.c adjust_dam (L48), Angband 4.2.6.
+ *
+ * The generated projections.ts carries only the PROJ names / enum. The
+ * behavioural data - the resistance numerator / denominator, the damage
+ * divisor and cap, and the obvious / wake flags project_m and project_p read -
+ * lives in projection.json and is bound here into ProjectionInfo[], indexed by
+ * PROJ value.
+ *
+ * adjust_dam is the player-side analog of project-mon.c's resist helpers: it
+ * scales incoming damage by the player's resistance level for the projection
+ * type. It stays pure - the caller looks up the resistance (with the ICE->COLD
+ * remap and equip_learn side effect) and passes it in, exactly the split the
+ * effect handlers and project_p need.
+ *
+ * desc / playerDesc / lashDesc are the display-only strings (struct
+ * projection's desc / player_desc / lash_desc) consumed by
+ * effects/effect-info.ts (effect_projection, effect_describe): desc is always
+ * present; playerDesc and lashDesc are absent (null) for projection types the
+ * pack never gives a "player-desc" / "lash-desc" line, exactly as upstream
+ * leaves those fields NULL.
+ */
+
+import { Dice } from "../dice.js";
+import type { Aspect, Rng } from "../rng.js";
+import { ELEMENT_ENTRIES, PROJ, PROJECTION_ENTRIES } from "../generated/index.js";
+import { messageLookupByName } from "../sound/engine.js";
+
+/** struct projection: the behavioural data for one PROJ_ type. */
+export interface ProjectionInfo {
+  /** PROJ_ value (index into the table). */
+  index: number;
+  /** Upstream code, e.g. "ACID". */
+  code: string;
+  /** In-game name, e.g. "acid". */
+  name: string;
+  /** "element" | "environs" | "monster". */
+  type: string;
+  /** Resistance numerator (0 when the type has no variable resistance). */
+  numerator: number;
+  /** Resistance denominator dice ("3", "8+1d4"), or null when absent. */
+  denominator: Dice | null;
+  /** diameter-of-source divisor (default 1). */
+  divisor: number;
+  /** Maximum damage the projection can deal (0 when uncapped/absent). */
+  damageCap: number;
+  /** Whether the effect's nature is obvious to the player. */
+  obvious: boolean;
+  /** Whether the projection forces affected monsters awake. */
+  wake: boolean;
+  /** MSG_ type name for messaging, or null. */
+  msgt: string | null;
+  /** Colour name (resolved to an attr by the render layer). */
+  color: string | null;
+  /** "hit by X" description used when the player cannot see the source. */
+  blindDesc: string | null;
+  /** Generic description ("acid", "fear", ...); always present. */
+  desc: string;
+  /** Description as experienced by the player ("acid", "frost", ...), or null. */
+  playerDesc: string | null;
+  /** Description for the LASH effect handler ("acid", "venom", ...), or null. */
+  lashDesc: string | null;
+}
+
+/** One projection.json record (only the fields bound here are typed). */
+export interface ProjectionRecordJson {
+  code: string;
+  name?: string;
+  type: string;
+  numerator?: number;
+  denominator?: string;
+  divisor?: number;
+  "damage-cap"?: number;
+  obvious?: number;
+  wake?: number;
+  msgt?: string;
+  color?: string;
+  desc?: string;
+  "player-desc"?: string;
+  "lash-desc"?: string;
+  "blind-desc"?: string;
+}
+
+/**
+ * Bind projection.json into a ProjectionInfo table indexed by PROJ value. The
+ * projection.txt / .json record order does NOT match the PROJ enum (upstream
+ * matches records to slots by code at load), so each record is placed at its
+ * resolved PROJ[code] slot. An unknown code, or an unfilled or duplicated slot,
+ * throws so pack / codegen drift is caught at load.
+ */
+export function bindProjections(
+  records: ProjectionRecordJson[],
+): ProjectionInfo[] {
+  /* 25 elements (list-elements.h) precede the list-projections.h entries. */
+  const total = PROJECTION_ENTRIES.length + ELEMENT_ENTRIES.length;
+  const out: Array<ProjectionInfo | null> = new Array<ProjectionInfo | null>(
+    total,
+  ).fill(null);
+
+  /*
+   * parse_projection_code (obj-init.c) numbers records sequentially and
+   * returns PARSE_ERROR_ELEMENT_NAME_MISMATCH when a record whose position is
+   * below ELEM_MAX does not carry element_names[position] as its code
+   * (proj.c test_code_mismatch0). Binding below is by code, so position would
+   * otherwise be free - but el_info[] is indexed by ELEM value and the
+   * ordering invariant is what upstream relies on to keep the two in step, so
+   * the port enforces it too, on the same input, before binding anything.
+   *
+   * A record that is absent entirely is NOT this error: upstream never runs
+   * the check for a position no record reached, and reports the short file as
+   * PARSE_ERROR_TOO_FEW_ENTRIES from finish_parse_projection instead. That is
+   * the "no record for PROJ value" throw at the bottom of this function, so
+   * missing positions are deliberately skipped here.
+   */
+  for (let i = 0; i < ELEMENT_ENTRIES.length && i < records.length; i++) {
+    const rec = records[i] as ProjectionRecordJson;
+    const expected = (ELEMENT_ENTRIES[i] as { name: string }).name;
+    if (rec.code !== expected) {
+      throw new Error(
+        `projection: record ${String(i)} is ${rec.code}, expected the ` +
+          `element ${expected} (PARSE_ERROR_ELEMENT_NAME_MISMATCH)`,
+      );
+    }
+  }
+
+  for (const rec of records) {
+    const index = (PROJ as Record<string, number>)[rec.code];
+    if (index === undefined) {
+      throw new Error(`projection: unknown code ${rec.code}`);
+    }
+    if (out[index]) {
+      throw new Error(`projection: duplicate code ${rec.code}`);
+    }
+    /* parse_projection_message_type: an unknown MSG_ name is
+     * PARSE_ERROR_INVALID_MESSAGE (proj.c test_msgt_bad0). */
+    if (rec.msgt !== undefined && messageLookupByName(rec.msgt) < 0) {
+      throw new Error(
+        `projection: ${rec.code}: invalid msgt ${rec.msgt} ` +
+          `(PARSE_ERROR_INVALID_MESSAGE)`,
+      );
+    }
+    let denominator: Dice | null = null;
+    if (rec.denominator !== undefined) {
+      denominator = new Dice();
+      denominator.parseString(rec.denominator);
+    }
+    out[index] = {
+      index,
+      code: rec.code,
+      name: rec.name ?? rec.code,
+      type: rec.type,
+      numerator: rec.numerator ?? 0,
+      denominator,
+      divisor: rec.divisor ?? 1,
+      damageCap: rec["damage-cap"] ?? 0,
+      obvious: rec.obvious === 1,
+      wake: rec.wake === 1,
+      msgt: rec.msgt ?? null,
+      color: rec.color ?? null,
+      blindDesc: rec["blind-desc"] ?? null,
+      desc: rec.desc ?? "",
+      playerDesc: rec["player-desc"] ?? null,
+      lashDesc: rec["lash-desc"] ?? null,
+    };
+  }
+
+  for (let i = 0; i < total; i++) {
+    if (!out[i]) throw new Error(`projection: no record for PROJ value ${i}`);
+  }
+  return out as ProjectionInfo[];
+}
+
+/** RES_LEVEL that means full immunity (el_info res_level 3). */
+const RESIST_IMMUNE = 3;
+/** RES_LEVEL that means vulnerability. */
+const RESIST_VULNERABLE = -1;
+
+/**
+ * adjust_dam: scale `dam` for the player's `resistLevel` against projection
+ * `type`. resistLevel is the caller-supplied el_info[res_type].res_level (the
+ * caller applies the ICE->COLD remap and any equip-learn side effect): 3 is
+ * immune, -1 vulnerable, positive values each divide by numerator/denominator.
+ *
+ * `minusAc` is minus_ac(p): acid damage is halved when the player has armour
+ * that acid can damage. Immunity and vulnerability short-circuit exactly as
+ * upstream; the variable-resist denominator is evaluated with the aspect
+ * inverted (least damage uses the largest divisor).
+ */
+export function adjustDam(
+  rng: Rng,
+  projections: readonly ProjectionInfo[],
+  type: number,
+  dam: number,
+  aspect: Aspect,
+  resistLevel: number,
+  minusAc = false,
+): number {
+  /* Immune */
+  if (resistLevel === RESIST_IMMUNE) return 0;
+
+  /* Hack - acid damage is halved by armour. */
+  if (type === PROJ.ACID && minusAc) dam = Math.trunc((dam + 1) / 2);
+
+  /* Vulnerable */
+  if (resistLevel === RESIST_VULNERABLE) return Math.trunc((dam * 4) / 3);
+
+  const info = projections[type];
+  let denom = 0;
+  if (info && info.denominator) {
+    /*
+     * Variable resists vary the denominator, so invert the aspect: the
+     * minimum damage uses the maximum divisor and vice versa.
+     */
+    let denomAspect: Aspect = aspect;
+    if (aspect === "minimise") denomAspect = "maximise";
+    else if (aspect === "maximise") denomAspect = "minimise";
+    denom = info.denominator.evaluate(rng, 0, denomAspect);
+  }
+
+  const numerator = info ? info.numerator : 0;
+  for (let i = resistLevel; i > 0; i--) {
+    if (denom) dam = Math.trunc((dam * numerator) / denom);
+  }
+
+  return dam;
+}

package/src/world/scatter.ts

@@ -0,0 +1,72 @@
+/**
+ * scatter / scatter_ext from cave.c: randomly selected locations near a
+ * grid, fully in bounds, optionally in line of sight and satisfying a
+ * predicate.
+ *
+ * Upstream provenance: reference/src/cave.c (scatter, scatter_ext).
+ */
+
+import { distance } from "../loc.js";
+import type { Loc } from "../loc.js";
+import { loc } from "../loc.js";
+import type { Rng } from "../rng.js";
+import type { Chunk } from "./chunk.js";
+import { los } from "./view.js";
+
+export type ScatterPred = (c: Chunk, grid: Loc) => boolean;
+
+/**
+ * Find up to n distinct random locations within distance d of grid.
+ * Mirrors scatter_ext: collect every feasible grid in the (2d+1)^2 box
+ * (skipping the exact-distance check when d <= 1, as upstream does),
+ * then draw without replacement using rng.randint0.
+ */
+export function scatterExt(
+  c: Chunk,
+  rng: Rng,
+  n: number,
+  grid: Loc,
+  d: number,
+  needLos: boolean,
+  pred?: ScatterPred,
+): Loc[] {
+  const feas: Loc[] = [];
+  for (let y = grid.y - d; y <= grid.y + d; y++) {
+    for (let x = grid.x - d; x <= grid.x + d; x++) {
+      const g = loc(x, y);
+      if (!c.inBoundsFully(g)) continue;
+      if (d > 1 && distance(grid, g) > d) continue;
+      if (needLos && !los(c, grid, g)) continue;
+      if (pred && !pred(c, g)) continue;
+      feas.push(g);
+    }
+  }
+
+  const places: Loc[] = [];
+  let nfeas = feas.length;
+  while (places.length < n && nfeas > 0) {
+    const choice = rng.randint0(nfeas);
+    // feas entries below nfeas are always defined; the picked one is
+    // replaced by the last feasible entry, exactly as upstream shifts.
+    places.push(feas[choice] as Loc);
+    nfeas--;
+    feas[choice] = feas[nfeas] as Loc;
+  }
+  return places;
+}
+
+/**
+ * scatter: the single-location convenience wrapper. Returns the found
+ * location, or null when no feasible grid exists (upstream leaves the
+ * output loc untouched in that case; callers there always pre-fill it).
+ */
+export function scatter(
+  c: Chunk,
+  rng: Rng,
+  grid: Loc,
+  d: number,
+  needLos: boolean,
+): Loc | null {
+  const found = scatterExt(c, rng, 1, grid, d, needLos);
+  return found.length > 0 ? (found[0] as Loc) : null;
+}

package/src/world/trap.ts

@@ -0,0 +1,155 @@
+/**
+ * Trap kinds bound from trap.json (upstream lib/gamedata/trap.txt via
+ * init.c parse_trap_*), ported from the data half of reference/src/trap.c
+ * (Angband 4.2.6). Pure data: the live trap instances and their behaviour
+ * live in game/trap.ts (they mutate GameState).
+ *
+ * The "visibility" line is the kind's power random-value (rolled at
+ * placement against trap_level and matched against the SEARCH skill when
+ * revealing). Effects stay raw EffectRecordJson chains, built per
+ * activation exactly like object effects (game/obj-cmd.ts).
+ */
+
+import { FlagSet, flagSize } from "../bitflag.js";
+import { Dice } from "../dice.js";
+import { OF, TRAP_FLAG_ENTRIES, TRF } from "../generated/index.js";
+import { myStristr } from "../guard.js";
+import type { RandomValue } from "../rng.js";
+import type { EffectRecordJson } from "../obj/types.js";
+
+/** TRF_SIZE = FLAG_SIZE(TRF_MAX): byte size of a trap FlagSet. */
+export const TRF_SIZE = flagSize(TRAP_FLAG_ENTRIES.length);
+
+/** struct trap_kind. */
+export interface TrapKind {
+  /** Index in the bound table (t_idx). */
+  tidx: number;
+  /** Short name ("pit"); lookup_trap matches on desc. */
+  name: string;
+  /** Longer description used by lookup_trap ("spiked pit"). */
+  desc: string;
+  /**
+   * trap->text (trap.c parse_trap_desc / init.c L1887): the long recall
+   * paragraph shown by trap_lore (ui-knowledge.c L2588). Compiled from the
+   * JSON `desc` lines; empty when the record has none.
+   */
+  text: string;
+  glyph: string;
+  color: string;
+  /** appear: rarity (0 = never placed randomly), min depth, max number. */
+  rarity: number;
+  minDepth: number;
+  maxNum: number;
+  /** visibility: the power random-value. */
+  power: RandomValue;
+  flags: FlagSet;
+  effect: EffectRecordJson[];
+  effectXtra: EffectRecordJson[];
+  /** save: OF_ flag indexes that let the player evade entirely. */
+  saveFlags: number[];
+  msg: string;
+  msgGood: string;
+  msgBad: string;
+  msgXtra: string;
+}
+
+/** trap.json record shape (compiled from trap.txt). */
+export interface TrapRecordJson {
+  name: { name: string; desc: string };
+  graphics: { glyph: string; color: string };
+  appear?: { rarity: number; mindepth: number; maxnum: number };
+  visibility?: string;
+  flags?: string[];
+  effect?: EffectRecordJson[];
+  "effect-xtra"?: EffectRecordJson[];
+  save?: string;
+  desc?: string[];
+  msg?: string[];
+  "msg-good"?: string[];
+  "msg-bad"?: string[];
+  "msg-xtra"?: string[];
+}
+
+function parseTrapFlags(lines: string[] | undefined): FlagSet {
+  const flags = new FlagSet(TRF_SIZE);
+  if (!lines) return flags;
+  for (const line of lines) {
+    /* A non-string entry is the compiler's presence marker for "flags:"
+     * with no value: parse_trap_flags (init.c L1612-1614) returns
+     * PARSE_ERROR_NONE with t->flags untouched (partrap.c test_flags0). */
+    if (typeof line !== "string") continue;
+    for (const raw of line.split("|")) {
+      const name = raw.trim();
+      if (!name) continue;
+      const value = (TRF as Record<string, number>)[name];
+      if (value === undefined || value === 0) {
+        throw new Error(`trap: unknown flag ${name}`);
+      }
+      flags.on(value);
+    }
+  }
+  return flags;
+}
+
+function parsePower(expr: string | undefined): RandomValue {
+  if (!expr) return { base: 0, dice: 0, sides: 0, mBonus: 0 };
+  const d = new Dice();
+  if (!d.parseString(expr)) throw new Error(`trap: bad power "${expr}"`);
+  return d.randomValue();
+}
+
+function parseSaveFlags(save: string | undefined): number[] {
+  if (!save) return [];
+  const out: number[] = [];
+  for (const raw of save.split("|")) {
+    const name = raw.trim();
+    if (!name) continue;
+    const value = (OF as Record<string, number>)[name];
+    if (value === undefined) throw new Error(`trap: unknown save flag ${name}`);
+    out.push(value);
+  }
+  return out;
+}
+
+const joined = (lines: string[] | undefined): string =>
+  lines ? lines.join("") : "";
+
+/** Bind trap.json records into the trap_kind table (index = t_idx). */
+export function bindTraps(records: readonly TrapRecordJson[]): TrapKind[] {
+  return records.map((rec, tidx) => ({
+    tidx,
+    name: rec.name.name,
+    desc: rec.name.desc,
+    text: joined(rec.desc),
+    glyph: rec.graphics.glyph,
+    color: rec.graphics.color,
+    rarity: rec.appear?.rarity ?? 0,
+    minDepth: rec.appear?.mindepth ?? 0,
+    maxNum: rec.appear?.maxnum ?? 0,
+    power: parsePower(rec.visibility),
+    flags: parseTrapFlags(rec.flags),
+    effect: rec.effect ?? [],
+    effectXtra: rec["effect-xtra"] ?? [],
+    saveFlags: parseSaveFlags(rec.save),
+    msg: joined(rec.msg),
+    msgGood: joined(rec["msg-good"]),
+    msgBad: joined(rec["msg-bad"]),
+    msgXtra: joined(rec["msg-xtra"]),
+  }));
+}
+
+/**
+ * lookup_trap (trap.c:44-63): exact desc match wins, otherwise the FIRST close
+ * match. The two tests differ in case sensitivity and the port had them the same:
+ * equality is `streq` (:54) but the close match is `my_stristr` (:57), i.e.
+ * case-INsensitive. Found by W1-CITED.
+ */
+export function lookupTrap(kinds: readonly TrapKind[], desc: string): TrapKind | null {
+  let closest: TrapKind | null = null;
+  for (const kind of kinds) {
+    if (!kind.name) continue;
+    if (kind.desc === desc) return kind;
+    if (!closest && myStristr(kind.desc, desc)) closest = kind;
+  }
+  return closest;
+}