@rpgm-tools/neo-angband-core 0.10.0

package/src/player/combat-regen.ts

@@ -0,0 +1,33 @@
+/**
+ * convert_mana_to_hp, ported from reference/src/player-util.c (L655, Angband
+ * 4.2.6). PF_COMBAT_REGEN characters trade the spell points just spent for a
+ * small recovery of lost hit points on a successful cast (player-spell.c
+ * L519-521 passes spell->smana << 16).
+ *
+ * This is entirely deterministic: the HP gain is pure fixed-point arithmetic
+ * routed through player_adjust_hp_precise, which draws no RNG. sp_long is the
+ * spell points in the 2^16 fixed-point form upstream uses.
+ */
+
+import type { Player } from "./player.js";
+import { playerAdjustHpPrecise } from "../game/loop.js";
+
+/** convert_mana_to_hp (player-util.c L655). No RNG. */
+export function convertManaToHp(p: Player, spLong: number): void {
+  if (spLong <= 0 || p.msp === 0 || p.mhp === p.chp) return;
+
+  /* Lost HP from max, in 2^16ths. */
+  let hpGain = (p.mhp - p.chp) * 65536;
+  hpGain -= p.chpFrac;
+
+  /* Spend X% of SP to recover X/2% of the lost HP (X/4% at 50% HP). sp_ratio
+   * is the max-to-spent SP ratio, doubled to suit the target rate; the msp<10
+   * floor keeps gains low where MP is already generous. */
+  let spRatio = Math.trunc((Math.max(10, p.msp) * 131072) / spLong);
+
+  /* Cap healing at 25% of the damage, so spending > 50% msp is inefficient. */
+  if (spRatio < 4) spRatio = 4;
+  hpGain = Math.trunc(hpGain / spRatio);
+
+  playerAdjustHpPrecise(p, hpGain);
+}

package/src/player/exp.ts

@@ -0,0 +1,275 @@
+/**
+ * Experience and level progression, ported from reference/src/player.c
+ * (Angband 4.2.6): the player_exp[] advancement table, player_exp_gain /
+ * player_exp_lose with the adjust_level engine (level loss below the
+ * threshold, level gain with stat restoration and highest-level tracking),
+ * player_stat_inc / player_stat_dec, plus roll_hp from player-birth.c (the
+ * per-level hitdice rolls constrained to the 3/8..5/8 band) and the
+ * monster-kill experience formula from mon-util.c player_kill_monster
+ * (mexp * rlev / plev with 16.16 fractional carry).
+ *
+ * Level changes ripple into derived state (hitpoints, spells, mana,
+ * bonuses); the caller supplies that recomputation through ExpDeps.
+ * onLevelChange, keeping this module free of the session's wiring. Each
+ * level gained also fires ExpDeps.onGainLevel (history_add(HIST_GAIN_LEVEL),
+ * player.c L246-247), which the session wires to player/history.ts.
+ *
+ * DEFERRED (ledgered in parity/ledger/player-exp.yaml): the PU_/PR_ update
+ * masks (display), and upstream's handle_stuff interleaving (the port
+ * recomputes once after the loops settle).
+ */
+
+import type { Rng } from "../rng.js";
+import type { MessageType } from "../msg.js";
+import { PY_MAX_LEVEL, STAT_MAX } from "./types.js";
+import type { Player } from "./player.js";
+
+/** player_exp[PY_MAX_LEVEL] (player.c L48): exp needed to reach level i+2. */
+export const PLAYER_EXP: readonly number[] = [
+  10, 25, 45, 70, 100, 140, 200, 280, 380, 500,
+  650, 850, 1100, 1400, 1800, 2300, 2900, 3600, 4400, 5400,
+  6800, 8400, 10200, 12500, 17500, 25000, 35000, 50000, 75000, 100000,
+  150000, 200000, 275000, 350000, 450000, 550000, 700000, 850000, 1000000,
+  1250000, 1500000, 1800000, 2100000, 2400000, 2700000, 3000000, 3500000,
+  4000000, 4500000, 5000000,
+];
+
+/** PY_MAX_EXP (player.h). */
+export const PY_MAX_EXP = 99999999;
+
+/** The world hooks a level change ripples through. */
+export interface ExpDeps {
+  /** RNG for rolling unrolled hitdice on the way up. */
+  rng: Rng;
+  /**
+   * "Welcome to level %d." - upstream's msgt(MSG_LEVEL, ...) (player.c L250),
+   * so the type rides along and the message picks up MSG_LEVEL's colour and
+   * sound at the presentation boundary rather than defaulting to MSG_GENERIC.
+   */
+  msg?(text: string, type?: MessageType): void;
+  /**
+   * PU_BONUS | PU_HP | PU_SPELLS: recompute mhp / spells / mana / bonuses
+   * from the new level. Runs once after the level loops settle.
+   */
+  onLevelChange?(p: Player): void;
+  /**
+   * history_add(HIST_GAIN_LEVEL) (player.c L246-247): fired once per level
+   * gained, inside the verbose block, immediately BEFORE the "Welcome to
+   * level %d." message. `lev` is the just-reached level (p.lev already
+   * incremented). Not called when verbose is false (a save-load replay of
+   * adjustLevel must not re-log levels already recorded).
+   */
+  onGainLevel?(p: Player, lev: number): void;
+}
+
+/** exp needed for level `lev` (adjust_level's table read with expfact). */
+function expToReach(p: Player, lev: number): number {
+  return Math.trunc(((PLAYER_EXP[lev - 2] ?? 0) * p.expFactor) / 100);
+}
+
+/**
+ * roll_hp (player-birth.c): roll the cumulative per-level hitdice, rerolling
+ * until the final total lands within the 3/8..5/8 band. Level 1 is the full
+ * hitdie (birth sets it); this fills levels 2..PY_MAX_LEVEL.
+ */
+export function rollHp(p: Player, rng: Rng): void {
+  const minValue =
+    Math.trunc((PY_MAX_LEVEL * (p.hitdie - 1) * 3) / 8) + PY_MAX_LEVEL;
+  const maxValue =
+    Math.trunc((PY_MAX_LEVEL * (p.hitdie - 1) * 5) / 8) + PY_MAX_LEVEL;
+  p.playerHp[0] = p.hitdie;
+  for (;;) {
+    for (let i = 1; i < PY_MAX_LEVEL; i++) {
+      p.playerHp[i] = (p.playerHp[i - 1] ?? 0) + rng.randint1(p.hitdie);
+    }
+    const total = p.playerHp[PY_MAX_LEVEL - 1] ?? 0;
+    if (total < minValue || total > maxValue) continue;
+    break;
+  }
+}
+
+/**
+ * adjust_level (player.c L208): clamp experience, sync max_exp, walk the
+ * level down while under the previous threshold and up while over the next,
+ * restoring drained stats and announcing each level gained, then track the
+ * highest level max_exp supports and recompute the derived state.
+ */
+export function adjustLevel(p: Player, deps: ExpDeps, verbose = true): void {
+  if (p.exp < 0) p.exp = 0;
+  if (p.maxExp < 0) p.maxExp = 0;
+  if (p.exp > PY_MAX_EXP) p.exp = PY_MAX_EXP;
+  if (p.maxExp > PY_MAX_EXP) p.maxExp = PY_MAX_EXP;
+  if (p.exp > p.maxExp) p.maxExp = p.exp;
+
+  const levBefore = p.lev;
+
+  while (p.lev > 1 && p.exp < expToReach(p, p.lev)) {
+    p.lev--;
+  }
+
+  while (p.lev < PY_MAX_LEVEL && p.exp >= expToReach(p, p.lev + 1)) {
+    p.lev++;
+    if (p.lev > p.maxLev) p.maxLev = p.lev;
+    if (verbose) {
+      deps.onGainLevel?.(p, p.lev);
+      deps.msg?.(`Welcome to level ${p.lev}.`, "LEVEL");
+    }
+    /* effect_simple(EF_RESTORE_STAT) x5: drained stats come back. */
+    for (let i = 0; i < STAT_MAX; i++) {
+      if ((p.statCur[i] ?? 0) < (p.statMax[i] ?? 0)) {
+        p.statCur[i] = p.statMax[i] ?? 0;
+      }
+    }
+  }
+
+  while (p.maxLev < PY_MAX_LEVEL && p.maxExp >= expToReach(p, p.maxLev + 1)) {
+    p.maxLev++;
+  }
+
+  if (p.lev !== levBefore) {
+    /* Roll any hitdice the new levels need (upstream rolls all at birth;
+     * a pre-roll_hp save may carry zeroes). */
+    for (let i = 1; i < p.lev; i++) {
+      if (!(p.playerHp[i] ?? 0)) {
+        p.playerHp[i] = (p.playerHp[i - 1] ?? 0) + deps.rng.randint1(p.hitdie);
+      }
+    }
+  }
+  deps.onLevelChange?.(p);
+}
+
+/** player_exp_gain (player.c L269). */
+export function playerExpGain(p: Player, amount: number, deps: ExpDeps): void {
+  p.exp += amount;
+  if (p.exp < p.maxExp) p.maxExp += Math.trunc(amount / 10);
+  adjustLevel(p, deps);
+}
+
+/** player_exp_lose (player.c L277). */
+export function playerExpLose(
+  p: Player,
+  amount: number,
+  permanent: boolean,
+  deps: ExpDeps,
+): void {
+  if (p.exp < amount) amount = p.exp;
+  p.exp -= amount;
+  if (permanent) p.maxExp -= amount;
+  adjustLevel(p, deps);
+}
+
+/**
+ * The kill reward slice of player_kill_monster (mon-util.c L1067): exp is
+ * mexp * rlev / plev, with the remainder carried in the 16.16 exp_frac
+ * accumulator, then granted through player_exp_gain.
+ */
+export function playerKillExp(
+  p: Player,
+  race: { mexp: number; level: number },
+  deps: ExpDeps,
+): void {
+  const div = p.lev;
+  const raw = race.mexp * race.level;
+  let newExp = Math.trunc(raw / div);
+  const newExpFrac = Math.trunc(((raw % div) * 0x10000) / div) + p.expFrac;
+  if (newExpFrac >= 0x10000) {
+    newExp++;
+    p.expFrac = newExpFrac - 0x10000;
+  } else {
+    p.expFrac = newExpFrac;
+  }
+  playerExpGain(p, newExp, deps);
+}
+
+/** player_stat_inc (player.c L145): raise a stat toward 18/100. */
+export function playerStatInc(p: Player, rng: Rng, stat: number): boolean {
+  const v = p.statCur[stat] ?? 0;
+  if (v >= 18 + 100) return false;
+  if (v < 18) {
+    p.statCur[stat] = v + 1;
+  } else if (v < 18 + 90) {
+    let gain = Math.trunc((Math.trunc((18 + 100 - v) / 2) + 3) / 2);
+    if (gain < 1) gain = 1;
+    p.statCur[stat] = Math.min(
+      v + rng.randint1(gain) + Math.trunc(gain / 2),
+      18 + 99,
+    );
+  } else {
+    p.statCur[stat] = 18 + 100;
+  }
+  if ((p.statCur[stat] ?? 0) > (p.statMax[stat] ?? 0)) {
+    p.statMax[stat] = p.statCur[stat] ?? 0;
+  }
+  return true;
+}
+
+/**
+ * player_stat_dec (player.c L171): drain a stat (a tenth over 18/10, to 18
+ * from the teens, one point above 3); permanent drains lower the max too.
+ */
+export function playerStatDec(
+  p: Player,
+  stat: number,
+  permanent: boolean,
+): boolean {
+  let cur = p.statCur[stat] ?? 0;
+  let max = p.statMax[stat] ?? 0;
+  if (cur > 18 + 10) cur -= 10;
+  else if (cur > 18) cur = 18;
+  else if (cur > 3) cur -= 1;
+  let res = cur !== (p.statCur[stat] ?? 0);
+
+  if (permanent) {
+    if (max > 18 + 10) max -= 10;
+    else if (max > 18) max = 18;
+    else if (max > 3) max -= 1;
+    res = max !== (p.statMax[stat] ?? 0);
+  }
+
+  if (res) {
+    p.statCur[stat] = cur;
+    p.statMax[stat] = max;
+  }
+  return res;
+}
+
+/**
+ * player_scramble_stats (player-util.c L375): swap the stats at random with
+ * a Fisher-Yates shuffle, recording the swaps in statMap so they can be
+ * reverted. The caller marks PU_BONUS.
+ */
+export function playerScrambleStats(p: Player, rng: Rng): void {
+  for (let i = STAT_MAX - 1; i > 0; --i) {
+    const j = rng.randint0(i);
+
+    const max1 = p.statMax[i]!;
+    const cur1 = p.statCur[i]!;
+    p.statMax[i] = p.statMax[j]!;
+    p.statCur[i] = p.statCur[j]!;
+    p.statMax[j] = max1;
+    p.statCur[j] = cur1;
+
+    /* Record what we did */
+    const swap = p.statMap[i]!;
+    p.statMap[i] = p.statMap[j]!;
+    p.statMap[j] = swap;
+  }
+}
+
+/**
+ * player_fix_scramble (player-util.c L409): revert all prior stat swaps.
+ * No effect if the stats have not been swapped. The caller marks PU_BONUS.
+ */
+export function playerFixScramble(p: Player): void {
+  const newCur = new Array<number>(STAT_MAX);
+  const newMax = new Array<number>(STAT_MAX);
+  for (let i = 0; i < STAT_MAX; ++i) {
+    newCur[p.statMap[i]!] = p.statCur[i]!;
+    newMax[p.statMap[i]!] = p.statMax[i]!;
+  }
+  for (let i = 0; i < STAT_MAX; ++i) {
+    p.statCur[i] = newCur[i]!;
+    p.statMax[i] = newMax[i]!;
+    p.statMap[i] = i;
+  }
+}

package/src/player/history.ts

@@ -0,0 +1,211 @@
+/**
+ * Character auto-history creation and management, ported from
+ * reference/src/player-history.c (Angband 4.2.6).
+ *
+ * struct history_info (player-history.h L47-54) becomes HistoryInfo below.
+ * Upstream's `type` field is a bitflag SET (bitflag type[HIST_SIZE]); the
+ * port models it as a single JS number bitmask, since HIST_MAX (11, see
+ * generated/history-types.ts) fits comfortably in bits 0..10 and at most two
+ * or three bits are ever combined (e.g. ARTIFACT_UNKNOWN|ARTIFACT_LOST on a
+ * "Missed X" entry). historyAdd sets exactly one bit (1 << typeBit),
+ * matching history_add's hist_wipe + hist_on(flags, type) (L127-134).
+ *
+ * Upstream's player_history struct additionally tracks `next`/`length` for
+ * its manually-grown C array (history_init/history_realloc); the port's
+ * Player.hist is a plain growable array, so array length stands in for
+ * `next` and there is nothing to persist beyond the entries themselves.
+ *
+ * This module is pure (player/ layer): every function takes explicit
+ * dlev/clev/turn stamps and a `nameFn` for artifact text, exactly like
+ * history_add_full's parameters, so it draws no RNG and depends on no
+ * GameState. The game-layer stamp (dlev/clev/turn off live state) and the
+ * artifact fake-name builder live in game/history.ts.
+ */
+
+import { HIST } from "../generated/index.js";
+import type { Player } from "./player.js";
+
+/** struct history_info (player-history.h L47-54). */
+export interface HistoryInfo {
+  /** bitflag type[HIST_SIZE]: bitmask of HIST_* bits (1 << HIST.X). */
+  type: number;
+  /** int16_t dlev: dungeon level (feet = dlev * 50) when recorded. */
+  dlev: number;
+  /** int16_t clev: character level when recorded. */
+  clev: number;
+  /** uint8_t a_idx: the artifact this item relates to (0 = none). */
+  aIdx: number;
+  /** int32_t turn: the turn this item was recorded on. */
+  turn: number;
+  /** char event[80]: the text of the item (truncated to 79 chars + NUL). */
+  event: string;
+}
+
+/** hist_has(f, flag): whether bit `flagBit` is set in the type bitmask. */
+export function histHas(type: number, flagBit: number): boolean {
+  return (type & (1 << flagBit)) !== 0;
+}
+
+/** hist_on(f, flag): set bit `flagBit` on the entry's type bitmask. */
+function histOn(entry: HistoryInfo, flagBit: number): void {
+  entry.type |= 1 << flagBit;
+}
+
+/** hist_off(f, flag): clear bit `flagBit` on the entry's type bitmask. */
+function histOff(entry: HistoryInfo, flagBit: number): void {
+  entry.type &= ~(1 << flagBit);
+}
+
+/** history_clear (player-history.c L56-67): empty the log. */
+export function historyClear(p: Player): void {
+  p.hist = [];
+}
+
+/**
+ * history_add_full (player-history.c L76-105): append a fully-specified
+ * entry. `text` is truncated to 79 characters (my_strcpy into event[80]
+ * leaves room for the NUL). Always succeeds (the port's array has no fixed
+ * capacity to fail against), matching the C's unconditional `return true`.
+ */
+export function historyAddFull(
+  p: Player,
+  type: number,
+  aIdx: number,
+  dlev: number,
+  clev: number,
+  turn: number,
+  text: string,
+): boolean {
+  p.hist.push({ type, dlev, clev, aIdx, turn, event: text.slice(0, 79) });
+  return true;
+}
+
+/**
+ * history_add (player-history.c L127-134): add an entry with a single HIST_*
+ * type bit, no artifact. Mirrors history_add_with_flags's stamp (aidx 0,
+ * p->depth, p->lev, p->total_energy/100) via the caller-supplied dlev/clev/
+ * turn (the game layer reads those off live state; see game/history.ts).
+ */
+export function historyAdd(
+  p: Player,
+  text: string,
+  typeBit: number,
+  dlev: number,
+  clev: number,
+  turn: number,
+): boolean {
+  return historyAddFull(p, 1 << typeBit, 0, dlev, clev, turn, text);
+}
+
+/**
+ * history_is_artifact_known (player-history.c L139-153): true if a KNOWN
+ * entry for this artifact exists. Scans newest-first, exactly as upstream.
+ */
+export function historyIsArtifactKnown(
+  p: Player,
+  art: { aidx: number },
+): boolean {
+  for (let i = p.hist.length - 1; i >= 0; i--) {
+    const e = p.hist[i]!;
+    if (histHas(e.type, HIST.ARTIFACT_KNOWN) && e.aIdx === art.aidx) return true;
+  }
+  return false;
+}
+
+/**
+ * history_mark_artifact_known (player-history.c L158-173): flip the first
+ * (newest) matching-aidx entry from UNKNOWN to KNOWN. Returns whether a
+ * matching entry was found.
+ */
+function historyMarkArtifactKnown(p: Player, art: { aidx: number }): boolean {
+  for (let i = p.hist.length - 1; i >= 0; i--) {
+    const e = p.hist[i]!;
+    if (e.aIdx === art.aidx) {
+      histOff(e, HIST.ARTIFACT_UNKNOWN);
+      histOn(e, HIST.ARTIFACT_KNOWN);
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * history_mark_artifact_lost (player-history.c L178-192): flip the LOST bit
+ * on the first (newest) matching-aidx entry. Returns whether found.
+ */
+function historyMarkArtifactLost(p: Player, art: { aidx: number }): boolean {
+  for (let i = p.hist.length - 1; i >= 0; i--) {
+    const e = p.hist[i]!;
+    if (e.aIdx === art.aidx) {
+      histOn(e, HIST.ARTIFACT_LOST);
+      return true;
+    }
+  }
+  return false;
+}
+
+/** An artifact-like value: only the fields history needs. */
+export interface HistoryArtifactRef {
+  aidx: number;
+}
+
+/**
+ * history_find_artifact (player-history.c L223-241): reveal an existing
+ * artifact entry, or log a new "Found <name>" KNOWN entry. `nameFn` builds
+ * the spoiled artifact name (get_artifact_name, L197-215); the game layer's
+ * artifactHistoryName is RNG-free (objectPrep with the "maximise" aspect).
+ */
+export function historyFindArtifact<A extends HistoryArtifactRef>(
+  p: Player,
+  art: A,
+  dlev: number,
+  clev: number,
+  turn: number,
+  nameFn: (art: A) => string,
+): void {
+  if (!historyMarkArtifactKnown(p, art)) {
+    const text = `Found ${nameFn(art)}`;
+    historyAddFull(p, 1 << HIST.ARTIFACT_KNOWN, art.aidx, dlev, clev, turn, text);
+  }
+}
+
+/**
+ * history_lose_artifact (player-history.c L246-266): mark an artifact lost,
+ * or log a new "Missed <name>" UNKNOWN|LOST entry.
+ */
+export function historyLoseArtifact<A extends HistoryArtifactRef>(
+  p: Player,
+  art: A,
+  dlev: number,
+  clev: number,
+  turn: number,
+  nameFn: (art: A) => string,
+): void {
+  if (!historyMarkArtifactLost(p, art)) {
+    const text = `Missed ${nameFn(art)}`;
+    const type = (1 << HIST.ARTIFACT_UNKNOWN) | (1 << HIST.ARTIFACT_LOST);
+    historyAddFull(p, type, art.aidx, dlev, clev, turn, text);
+  }
+}
+
+/**
+ * history_unmask_unknown (player-history.c L272-283): convert every
+ * ARTIFACT_UNKNOWN entry to ARTIFACT_KNOWN. Called once at death (matching
+ * player-util.c death_knowledge L309) so the memorial/char-dump shows real
+ * artifact names; 4.2.6 never writes a HIST_PLAYER_DEATH entry (verified:
+ * zero uses of that type in reference/src), so death logs nothing new here.
+ */
+export function historyUnmaskUnknown(p: Player): void {
+  for (let i = p.hist.length - 1; i >= 0; i--) {
+    const e = p.hist[i]!;
+    if (histHas(e.type, HIST.ARTIFACT_UNKNOWN)) {
+      histOff(e, HIST.ARTIFACT_UNKNOWN);
+      histOn(e, HIST.ARTIFACT_KNOWN);
+    }
+  }
+}
+
+/** history_get_list (player-history.c L288-294): the entries, oldest-first. */
+export function historyGetList(p: Player): readonly HistoryInfo[] {
+  return p.hist;
+}