@rpgm-tools/neo-angband-core 0.10.0

package/src/mon/types.ts

@@ -0,0 +1,286 @@
+/**
+ * Monster domain types, ported from reference/src/monster.h and
+ * reference/src/mon-blows.h (Angband 4.2.6).
+ *
+ * These are the bound, typed shapes produced by bind.ts from the compiled
+ * pack JSON (monster.json, monster_base.json, monster_spell.json,
+ * blow_methods.json, blow_effects.json, pain.json, summon.json, pit.json).
+ * World coupling stays out of this module: races reference each other and
+ * their bases directly, but objects (mimic kinds, drops) are kept as tval
+ * and sval names, to be resolved by the object domain later.
+ */
+
+import type { FlagSet } from "../bitflag.js";
+import type { Dice } from "../dice.js";
+import {
+  MON_RACE_FLAG_ENTRIES,
+  MON_SPELL_ENTRIES,
+  MON_TEMP_FLAG_ENTRIES,
+} from "../generated/index.js";
+import { flagSize } from "../bitflag.js";
+import { RSF } from "../generated/index.js";
+
+/** Byte size of a race FlagSet (upstream RF_SIZE = FLAG_SIZE(RF_MAX)). */
+export const RF_SIZE = flagSize(MON_RACE_FLAG_ENTRIES.length);
+
+/** Byte size of a spell FlagSet (upstream RSF_SIZE = FLAG_SIZE(RSF_MAX)). */
+export const RSF_SIZE = flagSize(RSF.MAX);
+
+/** Byte size of a temp-flag FlagSet (upstream MFLAG_SIZE). */
+export const MFLAG_SIZE = flagSize(MON_TEMP_FLAG_ENTRIES.length);
+
+/**
+ * struct monster_pain: one pain-message family; pain.txt `type` values are
+ * the pain_idx keys monster_base pain: refers to.
+ */
+export interface Pain {
+  painIdx: number;
+  /** Up to seven messages, ordered from least to most hurt. */
+  messages: string[];
+}
+
+/** struct blow_method (mon-blows.h), bound from blow_methods.json. */
+export interface BlowMethod {
+  name: string;
+  cut: boolean;
+  stun: boolean;
+  miss: boolean;
+  phys: boolean;
+  /** MSG_ type name (upstream stores the resolved msgt int). */
+  msgt: string;
+  /** Action messages ({target} substitution done by combat code later). */
+  messages: string[];
+  desc: string;
+}
+
+/** struct blow_effect (mon-blows.h), bound from blow_effects.json. */
+export interface BlowEffect {
+  name: string;
+  power: number;
+  eval: number;
+  desc: string;
+  /** Lore colors kept as color names (upstream resolves to attrs). */
+  loreColorBase: string;
+  loreColorResist: string;
+  loreColorImmune: string;
+  effectType: string;
+  /** Element name for resist checks (upstream resolves to an index). */
+  resist: string | null;
+  /** Projection type name used by LASH. */
+  lashType: string | null;
+}
+
+/** struct monster_blow: one melee blow of a race. */
+export interface MonsterBlow {
+  method: BlowMethod;
+  effect: BlowEffect;
+  /** Damage dice, or null when the blow has no damage (upstream zero rand). */
+  dice: Dice | null;
+  /** The raw damage string from monster.txt, e.g. "20d10", or null. */
+  diceRaw: string | null;
+}
+
+/** One effect line of a monster spell (kept close to the pack record). */
+export interface MonsterSpellEffect {
+  eff: string;
+  type: string | null;
+  radius: number;
+  other: number;
+  /** Parsed dice (expressions bound where present), or null. */
+  dice: Dice | null;
+  diceRaw: string | null;
+  /** expr bindings as written: name, base value name, operations string. */
+  exprs: Array<{ name: string; base: string; expr: string }>;
+}
+
+/**
+ * struct monster_spell_level: power-cutoff dependent lore and messages.
+ * The first level always has power 0; power-cutoff directives append more.
+ */
+export interface MonsterSpellLevel {
+  power: number;
+  loreDesc: string;
+  loreColorBase: string;
+  loreColorResist: string;
+  loreColorImmune: string;
+  message: string;
+  blindMessage: string;
+  missMessage: string;
+  saveMessage: string;
+}
+
+/** struct monster_spell: one RSF_ spell bound from monster_spell.json. */
+export interface MonsterSpell {
+  /** RSF_ index. */
+  index: number;
+  name: string;
+  /** MSG_ type name for message coloring. */
+  msgt: string;
+  /** To-hit level of the attack. */
+  hit: number;
+  effects: MonsterSpellEffect[];
+  levels: MonsterSpellLevel[];
+}
+
+/** struct monster_base: race template bound from monster_base.json. */
+export interface MonsterBase {
+  name: string;
+  /** In-game name (desc line). */
+  text: string;
+  flags: FlagSet;
+  /** Default display glyph. */
+  glyph: string;
+  pain: Pain;
+}
+
+/** enum monster_group_role. */
+export const MON_GROUP = {
+  LEADER: 0,
+  SERVANT: 1,
+  BODYGUARD: 2,
+  MEMBER: 3,
+  SUMMON: 4,
+} as const;
+export type MonsterGroupRole = (typeof MON_GROUP)[keyof typeof MON_GROUP];
+
+/** struct monster_friends: specific-race companion line. */
+export interface MonsterFriends {
+  /** Raw name; "same" binds to the owning race. */
+  name: string;
+  /** Resolved after all races bind. */
+  race: MonsterRace | null;
+  role: MonsterGroupRole;
+  percentChance: number;
+  numberDice: number;
+  numberSide: number;
+}
+
+/** struct monster_friends_base: base-template companion line. */
+export interface MonsterFriendsBase {
+  base: MonsterBase;
+  role: MonsterGroupRole;
+  percentChance: number;
+  numberDice: number;
+  numberSide: number;
+}
+
+/**
+ * struct monster_drop, minimal model: object kinds stay unresolved names
+ * until the object domain binds them (drop-base lines have sval null).
+ */
+export interface MonsterDrop {
+  tval: string;
+  sval: string | null;
+  percentChance: number;
+  min: number;
+  max: number;
+}
+
+/** struct monster_mimic, minimal: kind kept as tval/sval names. */
+export interface MonsterMimic {
+  tval: string;
+  sval: string;
+}
+
+/** struct monster_shape: race resolved second-pass; base wins if it names one. */
+export interface MonsterShape {
+  name: string;
+  race: MonsterRace | null;
+  base: MonsterBase | null;
+}
+
+/** struct monster_altmsg: per-race override of a spell message. */
+export type MonsterAltMsgType = "seen" | "unseen" | "miss";
+export interface MonsterAltMsg {
+  /** RSF_ index of the spell. */
+  index: number;
+  msgType: MonsterAltMsgType;
+  message: string;
+}
+
+/** struct monster_race (monster.h), bound from monster.json. */
+export interface MonsterRace {
+  /** Index in the race array; record order mirrors monster.txt. */
+  ridx: number;
+  name: string;
+  text: string;
+  plural: string | null;
+  base: MonsterBase;
+  /** Average hit points (4.2 stores avg_hp, not hdice). */
+  avgHp: number;
+  ac: number;
+  sleep: number;
+  /** Scaled by max_sight / 20 at bind time, as parse_monster_hearing. */
+  hearing: number;
+  smell: number;
+  speed: number;
+  light: number;
+  mexp: number;
+  /** Stored as 100 / pct like upstream freq_innate / freq_spell. */
+  freqInnate: number;
+  freqSpell: number;
+  /** Defaults to level; overridden by spell-power. */
+  spellPower: number;
+  flags: FlagSet;
+  spellFlags: FlagSet;
+  blows: MonsterBlow[];
+  level: number;
+  rarity: number;
+  /** Display attr (COLOUR_ index) and glyph. */
+  dAttr: number;
+  dChar: string;
+  /** Population cap: 100, or 1 for uniques (player-birth.c). */
+  maxNum: number;
+  /** Mutable per-level population count. */
+  curNum: number;
+  spellMsgs: MonsterAltMsg[];
+  drops: MonsterDrop[];
+  friends: MonsterFriends[];
+  friendsBase: MonsterFriendsBase[];
+  mimicKinds: MonsterMimic[];
+  shapes: MonsterShape[];
+}
+
+/** summon.txt record, loaded with minimal binding (details deferred). */
+export interface SummonType {
+  name: string;
+  msgt: string;
+  uniquesAllowed: boolean;
+  baseNames: string[];
+  raceFlag: string | null;
+  fallbackName: string | null;
+  desc: string;
+}
+
+/** pit.txt record, loaded with minimal binding (details deferred). */
+export interface PitProfile {
+  name: string;
+  room: number;
+  allocRarity: number;
+  allocLevel: number;
+  objRarity: number;
+  baseNames: string[];
+  colors: string[];
+  flagsReq: string[];
+  flagsBan: string[];
+  spellReq: string[];
+  spellBan: string[];
+  monBan: string[];
+  freqInnate: number;
+}
+
+/**
+ * The RSF_ index whose list-mon-spells.h type expression contains any of
+ * the given RST_ names (create_mon_spell_mask). Entry i of
+ * MON_SPELL_ENTRIES is RSF value i.
+ */
+export function monSpellsOfTypes(...types: string[]): number[] {
+  const out: number[] = [];
+  for (let i = 0; i < MON_SPELL_ENTRIES.length; i++) {
+    const entry = MON_SPELL_ENTRIES[i];
+    if (!entry || typeof entry.type !== "string") continue;
+    const parts = entry.type.split("|").map((s) => s.trim());
+    if (types.some((t) => parts.includes(t))) out.push(i);
+  }
+  return out;
+}

package/src/msg.ts

@@ -0,0 +1,146 @@
+/**
+ * Message handling, ported from reference/src/message.c and message.h
+ * (Angband 4.2.6).
+ *
+ * MessageLog stores the rolling log (most recent first, duplicate
+ * squashing with counts, capacity 2048). Messages is the engine-facing
+ * facade: msg()/msgt() add to the log and signal the event bus; sound()
+ * and bell() are event-only. Message types are numeric MSG_* indices
+ * (the generated list-message module supplies names); colors are numeric
+ * COLOUR_* indices as upstream.
+ *
+ * Not ported here: message_lookup_by_name / by_sound_name (they need the
+ * generated list-message table; they land with the pref-file loader).
+ * C's printf-style formatting is dropped; callers use template strings.
+ */
+
+import { colorCharToAttr, COLOUR_DARK, COLOUR_WHITE } from "./color.js";
+import { MSG } from "./generated/message.js";
+import type { GameEvents } from "./events.js";
+
+/** A message type as it appears at engine call sites or after codegen. */
+export type MessageType = number | string;
+
+/** MSG_GENERIC: the default message type (index 0 of list-message.h). */
+export const MSG_GENERIC = 0;
+
+/**
+ * message.prf:103,115,196: these are the three non-white default message
+ * colours. All other listed defaults are `w`, so message.c:269-285's white
+ * fallback gives the same result without duplicating a 100-line table.
+ */
+const DEFAULT_MESSAGE_COLORS = new Map<number, number>([
+  [MSG.BELL, colorCharToAttr("o")],
+  [MSG.HITPOINT_WARN, colorCharToAttr("o")],
+  [MSG.AFRAID, colorCharToAttr("o")],
+]);
+
+interface LogEntry {
+  str: string;
+  type: number;
+  count: number;
+}
+
+/** The rolling message memory (msgqueue_t). */
+export class MessageLog {
+  /** Newest first, index 0 = age 0 (upstream walks head -> older). */
+  private entries: LogEntry[] = [];
+  // message.c:269-285: message types start with their loaded defaults and
+  // an explicit COLOUR_DARK remains the unset/white sentinel.
+  private colors = new Map(DEFAULT_MESSAGE_COLORS);
+
+  constructor(private max = 2048) {}
+
+  /** messages_num. */
+  num(): number {
+    return this.entries.length;
+  }
+
+  /**
+   * message_add: append, or bump the count when identical to the newest
+   * entry (count saturates at 0xFFFF exactly like the uint16_t check).
+   */
+  add(str: string, type: number): void {
+    const head = this.entries[0];
+    if (head && head.type === type && head.str === str && head.count !== 0xffff) {
+      head.count++;
+      return;
+    }
+    this.entries.unshift({ str, type, count: 1 });
+    if (this.entries.length > this.max) this.entries.pop();
+  }
+
+  /** message_str: text of the message of the given age ("" if absent). */
+  str(age: number): string {
+    return this.entries[age]?.str ?? "";
+  }
+
+  /** message_count: repeat count of the message of the given age. */
+  count(age: number): number {
+    return this.entries[age]?.count ?? 0;
+  }
+
+  /** message_type. */
+  type(age: number): number {
+    return this.entries[age]?.type ?? 0;
+  }
+
+  /** message_color. */
+  color(age: number): number {
+    const e = this.entries[age];
+    return e ? this.typeColor(e.type) : COLOUR_WHITE;
+  }
+
+  /** message_color_define. */
+  colorDefine(type: number, color: number): void {
+    this.colors.set(type, color);
+  }
+
+  /** message_type_color: COLOUR_DARK means "unset" and yields white. */
+  typeColor(type: number): number {
+    const c = this.colors.get(type);
+    return c !== undefined && c !== COLOUR_DARK ? c : COLOUR_WHITE;
+  }
+}
+
+/** MSG_BELL index in list-message.h; bell() signals with this type. */
+export const MSG_BELL = MSG.BELL;
+
+/**
+ * The msg()/msgt()/sound()/bell() facade: adds to the log and signals the
+ * event bus, honoring the use_sound option via an injected getter.
+ */
+export class Messages {
+  constructor(
+    readonly log: MessageLog,
+    private events: GameEvents,
+    private soundEnabled: () => boolean = () => false,
+  ) {}
+
+  /** msg: log with MSG_GENERIC and signal EVENT_MESSAGE. */
+  msg(text: string): void {
+    this.log.add(text, MSG_GENERIC);
+    this.events.emit("message", { msg: text, type: MSG_GENERIC });
+  }
+
+  /** msgt: log with a type, make the type's sound, signal EVENT_MESSAGE. */
+  msgt(type: number, text: string): void {
+    this.log.add(text, type);
+    this.sound(type);
+    this.events.emit("message", { msg: text, type });
+  }
+
+  /**
+   * sound: EVENT_SOUND only, gated by the use_sound option. The payload's
+   * message is null, not "" -- message.c:374 passes NULL.
+   */
+  sound(type: number): void {
+    if (!this.soundEnabled()) return;
+    this.events.emit("sound", { msg: null, type });
+  }
+
+  /** bell: EVENT_BELL, likewise with a NULL message (message.c:381). */
+  bell(): void {
+    this.events.emit("bell", { msg: null, type: MSG_BELL });
+  }
+}

package/src/obj/artifact-fake.ts

@@ -0,0 +1,63 @@
+/**
+ * make_fake_artifact (obj-make.c L728-745): build a throwaway artifact object
+ * directly from a blank object, used purely to DESCRIBE an artifact - the
+ * artifact-knowledge recall (desc_art_fake, ui-knowledge.c L1610-1654) and the
+ * spoiler dumps. As upstream warns, the result is in no way marked "fake", so
+ * it must NEVER become a live game object.
+ *
+ * DETERMINISM (the reason this lives in one place): object_prep with the
+ * "maximise" aspect draws no entropy, but copy_artifact_data's copy_curses step
+ * ALWAYS rolls the curse timeout on the "randomise" aspect regardless of the
+ * caller's aspect (obj-curse.c L67, ported faithfully in copyCurses). A
+ * browsing preview must not perturb the shared game RNG stream, so this builder
+ * draws from a DEDICATED throwaway Rng (a fresh Rng at a fixed seed), never the
+ * game stream. The fixed seed also makes the same artifact preview identically
+ * every time it is browsed.
+ *
+ * Attribution: neostryder / RPGM Tools.
+ */
+
+import type { Constants } from "../constants.js";
+import { Rng } from "../rng.js";
+import type { ObjRegistry } from "./bind.js";
+import { copyArtifactData, objectPrep } from "./make.js";
+import type { GameObject } from "./object.js";
+import type { Artifact } from "./types.js";
+
+/**
+ * The fixed seed for the throwaway prep Rng. object_prep(maximise) consumes no
+ * entropy and copy_artifact_data draws only the curse timeout, so a constant
+ * seed yields a stable, game-RNG-independent preview.
+ */
+export const FAKE_ARTIFACT_SEED = 1;
+
+/**
+ * make_fake_artifact(obj, artifact) (obj-make.c L728): look up the base kind,
+ * object_prep it with the MAXIMISE aspect, stamp on the artifact, then
+ * copy_artifact_data. Returns null when the artifact has no tval or its base
+ * kind is missing (upstream returns false - L733, L737).
+ *
+ * The build uses its own throwaway Rng (see the module note); the caller's game
+ * RNG stream is never touched.
+ */
+export function makeFakeArtifact(
+  reg: ObjRegistry,
+  constants: Constants,
+  art: Artifact,
+  seed: number = FAKE_ARTIFACT_SEED,
+): GameObject | null {
+  /* Don't bother with empty artifacts (L733). */
+  if (!art.tval) return null;
+
+  /* Get the "kind" index (L736). */
+  const kind = reg.lookupKind(art.tval, art.sval);
+  if (!kind) return null;
+
+  /* Create the artifact on a dedicated throwaway stream (L740-742). */
+  const rng = new Rng(seed);
+  const obj = objectPrep(rng, reg, constants, kind, 0, "maximise");
+  obj.artifact = art;
+  copyArtifactData(rng, reg, obj, art);
+  obj.number = 1;
+  return obj;
+}

package/src/obj/artifact-known.ts

@@ -0,0 +1,69 @@
+/**
+ * Artifact-knowledge gating for the "known artifacts" browser, ported from
+ * find_artifact (reference/src/ui-knowledge.c L1537-1610), object_is_known_
+ * artifact (obj-knowledge.c L552-556) and artifact_is_known (ui-knowledge.c
+ * L1687-1707) of Angband 4.2.6.
+ *
+ * The point of the gate is to never leak an artifact the player has not yet
+ * identified: an artifact is only "known" once it has been created AND there is
+ * no live, still-unidentified copy of it anywhere in the world. Wizard mode
+ * reveals everything.
+ *
+ * Attribution: neostryder / RPGM Tools.
+ */
+
+import { OBJ_NOTICE } from "./knowledge.js";
+import type { GameObject } from "./object.js";
+import type { Artifact } from "./types.js";
+
+/**
+ * object_is_known_artifact for a LIVE object (obj-knowledge.c L552): upstream
+ * reads obj->known->artifact, which objectKnownShadow (known-object.ts L512)
+ * sets to obj->artifact only when the object is ASSESSED (touched / picked up).
+ * So for a live object this is exactly "it is an artifact and it has been
+ * assessed" - computed here without building a full known shadow.
+ */
+export function liveObjectIsKnownArtifact(obj: GameObject): boolean {
+  return obj.artifact !== null && (obj.notice & OBJ_NOTICE.ASSESSED) !== 0;
+}
+
+/** The world-scan + created-flags view artifact_is_known needs. */
+export interface ArtifactKnownEnv {
+  /**
+   * Every live object find_artifact scans (ui-knowledge.c L1537): floor piles,
+   * player gear, monster-held objects, store stock and stored (cached) level
+   * chunks. Order does not matter - a fixed artifact has at most one live copy.
+   */
+  worldObjects(): Iterable<GameObject>;
+  /** is_artifact_created(art) (obj-util.c): the per-game created flag. */
+  isCreated(aidx: number): boolean;
+  /** player->wizard: wizard mode reveals every artifact. */
+  wizard: boolean;
+}
+
+/**
+ * find_artifact (ui-knowledge.c L1537-1610): the live object that is this
+ * artifact, or null if no copy exists in the world right now.
+ */
+export function findArtifact(env: ArtifactKnownEnv, aidx: number): GameObject | null {
+  for (const obj of env.worldObjects()) {
+    if (obj.artifact && obj.artifact.aidx === aidx) return obj;
+  }
+  return null;
+}
+
+/**
+ * artifact_is_known (ui-knowledge.c L1687-1707): should the browser list this
+ * artifact? Requires a name; wizard mode always yes; otherwise it must be
+ * created, and if a live copy exists it must already be identified as an
+ * artifact (else the copy is a not-yet-found artifact and listing it would
+ * leak it).
+ */
+export function artifactIsKnown(art: Artifact, env: ArtifactKnownEnv): boolean {
+  if (!art.name) return false;
+  if (env.wizard) return true;
+  if (!env.isCreated(art.aidx)) return false;
+  const obj = findArtifact(env, art.aidx);
+  if (obj && !liveObjectIsKnownArtifact(obj)) return false;
+  return true;
+}