@rpgm-tools/neo-angband-core 0.10.0

package/src/score/display.ts

@@ -0,0 +1,125 @@
+/**
+ * High-score row formatting, ported from reference/src/ui-score.c
+ * (Angband 4.2.6) display_score_page (L30). The C draws three lines per record
+ * with Term calls; this produces the same strings as DATA (ScoreRow), leaving
+ * the Term paging/scroll/keypress loop (display_scores_aux, L117) to the shell.
+ *
+ * The number fields the C reads back from the fixed-width record (pts printed
+ * with "%9s"; user/gold/turns are the space-padded numbers with their leading
+ * whitespace stripped) are reconstructed here from the typed HighScore, giving
+ * byte-identical output.
+ */
+
+import { COLOUR_L_GREEN, COLOUR_WHITE } from "../color.js";
+import { SCORES_PER_PAGE } from "./types.js";
+import type { HighScore, ScoreRow } from "./types.js";
+
+/**
+ * Resolvers for the race/class name a record's indices map to
+ * (player_id2race / player_id2class in display_score_page). Return null for an
+ * unknown index; the C prints "<none>" then. Supply from a PlayerRegistry:
+ * `{ raceName: (i) => reg.races[i]?.name ?? null, ... }`.
+ */
+export interface ScoreNameResolver {
+  raceName(ridx: number): string | null;
+  className(cidx: number): string | null;
+}
+
+/** printf "%Ns": right-justify a string into at least N columns. */
+function padStart(s: string, width: number): string {
+  return s.length >= width ? s : " ".repeat(width - s.length) + s;
+}
+
+/**
+ * Clean up the stored "when" for display (ui-score.c L100): an "@YYYYMMDD"
+ * stamp (a leading '@' with total length 9) becomes "YYYY-MM-DD"; anything
+ * else (e.g. "TODAY") is shown unchanged.
+ */
+function formatWhen(day: string): string {
+  if (day.startsWith("@") && day.length === 9) {
+    return `${day.slice(1, 5)}-${day.slice(5, 7)}-${day.slice(7, 9)}`;
+  }
+  return day;
+}
+
+/**
+ * Build the three display lines for a single record at `start`, highlighted
+ * when start === highlight. Faithful to the body of display_score_page's loop.
+ */
+export function scoreRow(
+  scores: readonly HighScore[],
+  start: number,
+  highlight: number,
+  names: ScoreNameResolver,
+): ScoreRow {
+  const score = scores[start]!;
+  const highlighted = start === highlight;
+  const color = highlighted ? COLOUR_L_GREEN : COLOUR_WHITE;
+
+  const race = names.raceName(score.pRace);
+  const cls = names.className(score.pClass);
+  const clev = score.curLev;
+  const mlev = score.maxLev;
+  const cdun = score.curDun;
+  const mdun = score.maxDun;
+
+  // Line 1: "%3d.%9s  %s the %s %s, level %d" (+ " (Max %d)" if mlev > clev).
+  let line1 =
+    `${padStart(String(start + 1), 3)}.${padStart(String(score.pts), 9)}` +
+    `  ${score.who} the ${race ?? "<none>"} ${cls ?? "<none>"}, level ${clev}`;
+  if (mlev > clev) line1 += ` (Max ${mlev})`;
+
+  // Line 2: town vs dungeon death (+ " (Max %d)" if mdun > cdun).
+  let line2 = !cdun
+    ? `Killed by ${score.how} in the town`
+    : `Killed by ${score.how} on dungeon level ${cdun}`;
+  if (mdun > cdun) line2 += ` (Max ${mdun})`;
+
+  // Line 3: "(User %s, Date %s, Gold %s, Turn %s)." - the numeric fields are
+  // the stripped (no leading space) decimal values.
+  const line3 =
+    `(User ${score.uid}, Date ${formatWhen(score.day)}, ` +
+    `Gold ${score.gold}, Turn ${score.turns}).`;
+
+  return { rank: start + 1, highlighted, color, line1, line2, line3 };
+}
+
+/**
+ * display_score_page (ui-score.c L30): the rows for one page - up to 5 entries
+ * starting at `start`, stopping at `count`. `highlight` is the index to draw in
+ * L_GREEN (or -1 for none).
+ */
+export function scorePageRows(
+  scores: readonly HighScore[],
+  start: number,
+  count: number,
+  highlight: number,
+  names: ScoreNameResolver,
+): ScoreRow[] {
+  const rows: ScoreRow[] = [];
+  for (let n = 0; start < count && n < SCORES_PER_PAGE; start++, n++) {
+    rows.push(scoreRow(scores, start, highlight, names));
+  }
+  return rows;
+}
+
+/**
+ * All rows for the inclusive-exclusive range [from, to) clamped to the real
+ * record count, in one flat list (convenience over paging). `highlight` is the
+ * highlighted index or -1. Useful for a scroll surface that renders every row.
+ */
+export function scoreRows(
+  scores: readonly HighScore[],
+  from: number,
+  to: number,
+  highlight: number,
+  names: ScoreNameResolver,
+): ScoreRow[] {
+  const start = Math.max(0, from);
+  const end = Math.min(to, scores.length);
+  const rows: ScoreRow[] = [];
+  for (let i = start; i < end; i++) {
+    rows.push(scoreRow(scores, i, highlight, names));
+  }
+  return rows;
+}

package/src/score/score.ts

@@ -0,0 +1,341 @@
+/**
+ * High-score logic, ported from reference/src/score.c and score-util.c
+ * (Angband 4.2.6): the scoring formula, the build/where/add/count/regularize
+ * table operations, and the enter-score gating. All operations here are pure
+ * over an in-memory HighScore[]; persistence arrives through the injected
+ * ScoreStore seam (types.ts), never a filesystem.
+ *
+ * The port operates on a COMPACT list (only real records, no empty padding),
+ * capped at MAX_HISCORES, rather than the C's fixed array of MAX_HISCORES
+ * records with empty slots at the tail. The observable results (insert slot,
+ * shift-and-truncate on add, sort order, count) are identical; see
+ * parity/ledger/high-scores.yaml for the equivalence argument.
+ */
+
+import type { Player } from "../player/player.js";
+import { ENGINE_VERSION } from "../version.js";
+import { MAX_HISCORES, WINNING_HOW } from "./types.js";
+import type { HighScore, ScoreStore } from "./types.js";
+
+/**
+ * Default build id stamped into a record's `what` (score.c build_score uses the
+ * global `buildid`). The web shell may pass a specific build id via
+ * BuildScoreDeps.buildid.
+ *
+ * This was a hardcoded copy of the version, on the reasoning that importing the
+ * barrel's ENGINE_VERSION would make a cycle. True of the barrel, but version.ts
+ * exists precisely so a core module can cite the version without it - and the
+ * copy did exactly what a copy does: the port went to 0.9.0 and every score kept
+ * being stamped 0.1.0.
+ */
+const DEFAULT_BUILDID = ENGINE_VERSION;
+
+/**
+ * total_points (score.c L28): the whole score is max experience plus a flat
+ * bonus per deepest dungeon level reached. Ported EXACTLY.
+ */
+export function totalPoints(p: Player): number {
+  return p.maxExp + 100 * p.maxDepth;
+}
+
+/**
+ * The non-Player state build_score reads (score.c build_score, L216). Upstream
+ * pulls these from globals (turn, player_uid, buildid) or the live world
+ * (p->depth is the current cave depth, distinct from p->max_depth). The port
+ * keeps them off Player, so buildScore takes them as deps, matching the
+ * char-sheet's deps idiom (game/char-sheet.ts).
+ */
+export interface BuildScoreDeps {
+  /** died_from: the method-of-death string (p->died_from, or "nobody (yet!)"). */
+  diedFrom: string;
+  /** turn (game-world.c): the game-turn counter at death. */
+  turn: number;
+  /** p->depth: the LIVE dungeon depth (cur_dun), not max_depth. */
+  depth: number;
+  /** p->full_name: the character's name (only first 15 chars are kept). */
+  fullName?: string;
+  /** player_uid: the OS player id. Default 0 (the port has no OS uid). */
+  uid?: number;
+  /** buildid the record is stamped with (what[]). Default ENGINE_VERSION. */
+  buildid?: string;
+  /**
+   * The time of death, for the "@YYYYMMDD" day stamp. NULL/undefined (the
+   * player is not dead) yields "TODAY", exactly as build_score.
+   */
+  deathTime?: Date | null;
+}
+
+/** strftime "@%Y%m%d" in LOCAL time (build_score L235 uses localtime). */
+function formatDay(deathTime: Date | null | undefined): string {
+  if (!deathTime) return "TODAY";
+  const y = String(deathTime.getFullYear()).padStart(4, "0");
+  const m = String(deathTime.getMonth() + 1).padStart(2, "0");
+  const d = String(deathTime.getDate()).padStart(2, "0");
+  return `@${y}${m}${d}`;
+}
+
+/**
+ * build_score (score.c L216): fill a score record from the player plus the
+ * death-time and cause. The C truncates who to 15 chars ("%-.15s") and how to
+ * 31 (my_strcpy into how[32]); reproduced here. `what` marks the record in
+ * use (a non-empty build id).
+ */
+export function buildScore(p: Player, deps: BuildScoreDeps): HighScore {
+  return {
+    what: (deps.buildid ?? DEFAULT_BUILDID).slice(0, 7),
+    pts: totalPoints(p),
+    gold: p.au,
+    turns: deps.turn,
+    day: formatDay(deps.deathTime),
+    who: (deps.fullName ?? "").slice(0, 15),
+    uid: deps.uid ?? 0,
+    pRace: p.race.ridx,
+    pClass: p.cls.cidx,
+    curLev: p.lev,
+    curDun: deps.depth,
+    maxLev: p.maxLev,
+    maxDun: p.maxDepth,
+    how: deps.diedFrom.slice(0, 31),
+  };
+}
+
+/** A record is "empty"/unused when its build-id marker is blank (what[0]). */
+function isEmpty(s: HighScore): boolean {
+  return s.what.length === 0;
+}
+
+/**
+ * highscore_valid (score-util.c L95): a non-empty record must have parseable
+ * numeric fields. With typed storage the only ways a record can be invalid are
+ * a blank build id (treated as empty) or a non-finite number in a numeric
+ * field; NaN/Infinity would break the strtol-equivalent ordering, so they are
+ * rejected exactly as an unparseable C field would be.
+ */
+export function highscoreValid(s: HighScore): boolean {
+  if (isEmpty(s)) return true; // an empty record is valid (all-empty in C)
+  const nums = [
+    s.pts,
+    s.gold,
+    s.turns,
+    s.uid,
+    s.pRace,
+    s.pClass,
+    s.curLev,
+    s.curDun,
+    s.maxLev,
+    s.maxDun,
+  ];
+  return nums.every((n) => Number.isFinite(n));
+}
+
+/**
+ * highscore_cmp (score-util.c L43): order two records best-first. Winners
+ * (how == WINNING_HOW) precede non-winners; then more points precede fewer;
+ * ties keep their existing order (the C uses the record address, which for a
+ * contiguous array is the current order - a stable sort reproduces this).
+ * Returns <0 if a precedes b, >0 if a follows b, 0 for a true tie.
+ */
+export function highscoreCmp(a: HighScore, b: HighScore): number {
+  const ae = isEmpty(a);
+  const be = isEmpty(b);
+  if (ae) return be ? 0 : 1; // empty records sort after non-empty ones
+  if (be) return -1;
+
+  const awinner = a.how === WINNING_HOW;
+  const bwinner = b.how === WINNING_HOW;
+  if (awinner !== bwinner) return awinner ? -1 : 1;
+
+  if (a.pts !== b.pts) return a.pts > b.pts ? -1 : 1;
+  return 0; // true tie: stable sort keeps current order
+}
+
+/**
+ * highscore_where (score-util.c L276): the index a new (valid, non-empty)
+ * entry would take in a best-first list. Ties prefer the NEW entry
+ * (entry_pts >= score_pts). If it does not fit before any existing record it
+ * takes the first free slot (list length while below the cap) or, when the
+ * list is full, replaces the last record (index MAX_HISCORES - 1).
+ */
+export function highscoreWhere(
+  entry: HighScore,
+  scores: readonly HighScore[],
+): number {
+  const entryWinner = entry.how === WINNING_HOW;
+  const entryPts = entry.pts;
+
+  for (let i = 0; i < scores.length; i++) {
+    const s = scores[i]!;
+    const scoreWinner = s.how === WINNING_HOW;
+    if (entryWinner !== scoreWinner) {
+      if (entryWinner) return i;
+      continue;
+    }
+    if (entryPts >= s.pts) return i;
+  }
+
+  // Did not fit before any record: first free slot, else replace the last.
+  return scores.length < MAX_HISCORES ? scores.length : MAX_HISCORES - 1;
+}
+
+/**
+ * highscore_add (score.c L72): insert an entry at its slot, shifting lower
+ * records down and dropping anything past MAX_HISCORES. Mutates `scores` in
+ * place (like the C on its array) and returns the slot used.
+ *
+ * The full-list case matches the C's memmove-with-zero-count: highscoreWhere
+ * returns MAX_HISCORES - 1, splicing there pushes the old last record off the
+ * end, and the truncation drops it - i.e. the last entry is replaced.
+ */
+export function highscoreAdd(entry: HighScore, scores: HighScore[]): number {
+  const slot = highscoreWhere(entry, scores);
+  scores.splice(slot, 0, entry);
+  if (scores.length > MAX_HISCORES) scores.length = MAX_HISCORES;
+  return slot;
+}
+
+/** highscore_count (score.c L84): number of real records. */
+export function highscoreCount(scores: readonly HighScore[]): number {
+  let n = 0;
+  for (const s of scores) {
+    if (isEmpty(s)) break; // empties are tail-only; stop at the first
+    n++;
+  }
+  return n;
+}
+
+/**
+ * highscore_regularize (score-util.c L199): force the list valid and ordered.
+ * Invalid or empty records are dropped, and the remainder is stable-sorted
+ * best-first (winners, then points, ties in place). Returns a NEW list plus a
+ * flag reporting whether anything changed (the C's `irregular` return).
+ */
+export function highscoreRegularize(scores: readonly HighScore[]): {
+  scores: HighScore[];
+  irregular: boolean;
+} {
+  const kept: HighScore[] = [];
+  let irregular = false;
+  for (const s of scores) {
+    if (!highscoreValid(s) || isEmpty(s)) {
+      irregular = true; // an invalid/empty record in the body is an irregularity
+      continue;
+    }
+    kept.push(s);
+  }
+  // Detect out-of-order before sorting (stable sort would otherwise hide it).
+  for (let i = 1; i < kept.length; i++) {
+    if (highscoreCmp(kept[i - 1]!, kept[i]!) > 0) {
+      irregular = true;
+      break;
+    }
+  }
+  kept.sort(highscoreCmp);
+  return { scores: kept, irregular };
+}
+
+/**
+ * The outcome of enterScore: either entered (with its slot) or rejected with
+ * the reason the C would msg() about. The C is void + msg(); the port returns
+ * the decision so the shell owns the message.
+ */
+export type EnterScoreOutcome =
+  | { entered: true; slot: number }
+  | {
+      entered: false;
+      reason: "cheater" | "wizard" | "borg" | "interrupted" | "retired";
+    };
+
+/**
+ * The gating inputs enter_score checks (score.c L272). The port has no options
+ * table or noscore flags on Player yet, so they arrive as an explicit seam
+ * (defaults = a clean, scored character).
+ */
+export interface EnterScoreGating {
+  /** Any OP_SCORE ("cheating") option is on (score.c L277 loop). */
+  cheated?: boolean;
+  /** p->noscore & (NOSCORE_WIZARD | NOSCORE_DEBUG): a wizard/debug character. */
+  noscore?: boolean;
+  /**
+   * p->noscore & NOSCORE_BORG (score.c:291, the !SCORE_BORGS branch): played by
+   * the Borg. Checked AFTER the wizard bits, so a character that is both is
+   * reported as a wizard, matching the C's else-if chain.
+   */
+  borg?: boolean;
+  /** p->total_winner: a winner is scored even when interrupted/retiring. */
+  totalWinner?: boolean;
+  /** p->died_from (score.c L299/L302): "Interrupting" / "Retiring" are gated. */
+  diedFrom: string;
+}
+
+/** The host's score gate: Angband NOSCORE bits plus the port-only mod ratchet. */
+export function scoreGateNoscore(playerNoscore: boolean, modNoscore: boolean): boolean {
+  return playerNoscore || modNoscore;
+}
+
+/**
+ * enter_score (score.c L272): enter a character on the high-score table "if
+ * legal". Cheaters, wizards/debug characters, and non-winning interrupted or
+ * retiring deaths are not scored (in that priority order). Otherwise the entry
+ * is built and added to the store's list.
+ *
+ * Faithful divergence from the C's read/add/write: here read/write go through
+ * the injected ScoreStore, and highscoreAdd already truncates at MAX_HISCORES.
+ */
+export function enterScore(
+  store: ScoreStore,
+  player: Player,
+  build: BuildScoreDeps,
+  gating: EnterScoreGating,
+): EnterScoreOutcome {
+  if (gating.cheated) return { entered: false, reason: "cheater" };
+  if (gating.noscore) return { entered: false, reason: "wizard" };
+  if (gating.borg) return { entered: false, reason: "borg" };
+  if (!gating.totalWinner && gating.diedFrom === "Interrupting") {
+    return { entered: false, reason: "interrupted" };
+  }
+  if (!gating.totalWinner && gating.diedFrom === "Retiring") {
+    return { entered: false, reason: "retired" };
+  }
+
+  const entry = buildScore(player, build);
+  const scores = store.read();
+  const slot = highscoreAdd(entry, scores);
+  store.write(scores);
+  return { entered: true, slot };
+}
+
+/** The score range and highlight predict_score resolves for display. */
+export interface PredictedScores {
+  /** The score list to page over (the provisional entry inserted if alive). */
+  scores: HighScore[];
+  /** First index to show (from). */
+  from: number;
+  /** One past the last index to show (to). */
+  to: number;
+  /** The index to highlight (the current character), or -1 for none. */
+  highlight: number;
+}
+
+/**
+ * predict_score (ui-score.c L193): find where the current character sits and
+ * pick the neighbourhood to show. A dead character is already in `scores`
+ * (enter_score ran), so we only locate it (highscore_where); a live character
+ * is provisionally inserted (highscore_add) so it appears in the table. On the
+ * top ten we show ranks 1..15; otherwise a window around the entry.
+ *
+ * This is the DATA half; the shell (display_scores_aux) owns the paging loop.
+ */
+export function predictScore(
+  scores: HighScore[],
+  entry: HighScore,
+  isDead: boolean,
+): PredictedScores {
+  const j = isDead
+    ? highscoreWhere(entry, scores)
+    : highscoreAdd(entry, scores);
+
+  if (j < 10) {
+    return { scores, from: 0, to: 15, highlight: j };
+  }
+  return { scores, from: j - 2, to: j + 7, highlight: j };
+}

package/src/score/types.ts

@@ -0,0 +1,104 @@
+/**
+ * High-score domain types, ported from reference/src/score.h (Angband 4.2.6).
+ *
+ * Upstream struct high_score packs every field as a fixed-width, null-
+ * terminated, space-padded ASCII string in a 128-byte record (the "number"
+ * fields right-justified so a strcmp on "pts" orders scores). This port keeps
+ * data as JSON with TYPED fields (PORT_PLAN.md decision 9): the numeric fields
+ * become numbers, the string fields stay strings. The LOGIC (scoring math,
+ * sort/insert order, gating, display formatting) is ported faithfully; only
+ * the on-disk representation diverges from the binary scores.raw file. See
+ * parity/ledger/high-scores.yaml.
+ */
+
+/** Maximum number of high scores kept (score.h MAX_HISCORES). */
+export const MAX_HISCORES = 100;
+
+/**
+ * The value the `how` (method-of-death) field holds for a winner (score.h
+ * WINNING_HOW). A winning record sorts before any non-winning record.
+ */
+export const WINNING_HOW = "Ripe Old Age";
+
+/**
+ * One high-score record (struct high_score). The fixed-width string fields of
+ * the C become typed fields here; the port reconstructs the exact display
+ * strings (see display.ts) from these values.
+ *
+ * `what` (upstream: version info) doubles as the "slot in use" marker in the C
+ * (an empty `what` marks an unused record). This port stores only real records
+ * in a compact array, so `what` is simply the build id; an empty string still
+ * counts as an empty/invalid record for regularize.
+ */
+export interface HighScore {
+  /** buildid the score was recorded under (score.h what[8], <= 7 chars). */
+  what: string;
+  /** total_points(): max_exp + 100 * max_depth (score.h pts). */
+  pts: number;
+  /** Gold at death (player->au; score.h gold). */
+  gold: number;
+  /** Game turn at death (the `turn` counter; score.h turns). */
+  turns: number;
+  /** Time stamp: "@YYYYMMDD" for a death, or "TODAY" (score.h day). */
+  day: string;
+  /** Player name, first 15 chars of full_name (score.h who[16]). */
+  who: string;
+  /** Player uid (score.h uid). */
+  uid: number;
+  /** Player race index (race->ridx; score.h p_r). */
+  pRace: number;
+  /** Player class index (class->cidx; score.h p_c). */
+  pClass: number;
+  /** Level at death (player->lev; score.h cur_lev). */
+  curLev: number;
+  /** Dungeon level at death (player->depth, the live cave depth; cur_dun). */
+  curDun: number;
+  /** Deepest character level reached (player->max_lev; max_lev). */
+  maxLev: number;
+  /** Deepest dungeon level reached (player->max_depth; max_dun). */
+  maxDun: number;
+  /** Method of death, first 31 chars of died_from (score.h how[32]). */
+  how: string;
+}
+
+/**
+ * The persistence seam. Core never touches storage directly (no filesystem,
+ * no localStorage); a platform supplies read/write of the compact score list.
+ * Mirrors highscore_read / highscore_write, minus the binary file, locking and
+ * setuid dance of score.c (all platform concerns).
+ */
+export interface ScoreStore {
+  /** Read the stored scores, best-first. Empty array when nothing is stored. */
+  read(): HighScore[];
+  /** Persist the (already ordered, already truncated) score list. */
+  write(scores: HighScore[]): void;
+}
+
+/**
+ * One rendered score entry (the three text lines display_score_page draws per
+ * record, plus its colour and rank). The Term paging/scroll loop is the
+ * shell's; this is the front-end-agnostic row data.
+ */
+export interface ScoreRow {
+  /** 1-based rank (start + 1 in display_score_page). */
+  rank: number;
+  /** True when this row is the highlighted (current) entry. */
+  highlighted: boolean;
+  /** COLOUR_* attribute: L_GREEN when highlighted, else WHITE. */
+  color: number;
+  /** Line 1: "  1.  <pts>  <name> the <race> <class>, level N (Max M)". */
+  line1: string;
+  /** Line 2: "Killed by X on dungeon level N (Max M)" / "... in the town". */
+  line2: string;
+  /** Line 3: "(User u, Date d, Gold g, Turn t).". */
+  line3: string;
+}
+
+/**
+ * Column at which display_score_page draws the 2nd and 3rd lines of each entry
+ * (c_put_str(..., n * 4 + 3, 15) / (..., n * 4 + 4, 15)). Line 1 is at col 0.
+ */
+export const SCORE_DETAIL_INDENT = 15;
+
+/** Entries shown per page (display_score_page dumps at most 5). */
+export const SCORES_PER_PAGE = 5;