@rpgm-tools/neo-angband-core 0.10.0

package/src/rng.ts

@@ -0,0 +1,476 @@
+/**
+ * Random number generation, ported from reference/src/z-rand.c (Angband
+ * 4.2.6).
+ *
+ * The upstream implementation is a single global WELL1024a stream with a
+ * "quick" LCRNG mode and a seed-swap trick for stable seeds (flavors,
+ * randarts). This port makes the generator instantiable so the engine can
+ * run named, independently seeded streams instead of swapping seeds on one
+ * global; each individual stream is bit-for-bit faithful to upstream.
+ *
+ * All arithmetic reproduces C uint32 semantics exactly (Math.imul for
+ * wrapping multiplication, >>> 0 for unsigned truncation, Math.trunc for
+ * C integer division). Golden vectors generated by an independent Python
+ * oracle (scripts/gen-rng-vectors.py) pin the outputs.
+ */
+
+/**
+ * Assumed maximum dungeon level, used for object/monster creation math.
+ */
+export const MAX_RAND_DEPTH = 128;
+
+/**
+ * The number of 32-bit integers worth of WELL seed state.
+ */
+export const RAND_DEG = 32;
+
+/**
+ * Random aspects used by damcalc, mBonusCalc, and randcalc.
+ * Order mirrors the upstream enum: MINIMISE, AVERAGE, MAXIMISE, EXTREMIFY,
+ * RANDOMISE.
+ */
+export type Aspect =
+  | "minimise"
+  | "average"
+  | "maximise"
+  | "extremify"
+  | "randomise";
+
+/**
+ * A strategy for making a dice roll: base + XdY + BONUS, where mBonus is
+ * used in a tricky way to determine BONUS.
+ */
+export interface RandomValue {
+  base: number;
+  dice: number;
+  sides: number;
+  mBonus: number;
+}
+
+/**
+ * A random chance of success, such as 8 in 125 (6.4 percent).
+ */
+export interface RandomChance {
+  numerator: number;
+  denominator: number;
+}
+
+/**
+ * Serializable snapshot of a generator, for savefiles.
+ */
+export interface RngState {
+  quick: boolean;
+  value: number;
+  state: number[];
+  stateI: number;
+  fixed: boolean;
+  fixval: number;
+}
+
+/** LCRNG(X) = X * 1103515245 + 12345, in uint32. */
+function lcrng(x: number): number {
+  return (Math.imul(x, 1103515245) + 12345) >>> 0;
+}
+
+/**
+ * The normal distribution table for randNormal(); entry 64*N is the number
+ * of times out of 32767 that a normally distributed variable falls within N
+ * standard deviations of the mean. Copied verbatim from z-rand.c.
+ */
+const RAND_NORMAL_TABLE: readonly number[] = [
+  206, 613, 1022, 1430, 1838, 2245, 2652, 3058,
+  3463, 3867, 4271, 4673, 5075, 5475, 5874, 6271,
+  6667, 7061, 7454, 7845, 8234, 8621, 9006, 9389,
+  9770, 10148, 10524, 10898, 11269, 11638, 12004, 12367,
+  12727, 13085, 13440, 13792, 14140, 14486, 14828, 15168,
+  15504, 15836, 16166, 16492, 16814, 17133, 17449, 17761,
+  18069, 18374, 18675, 18972, 19266, 19556, 19842, 20124,
+  20403, 20678, 20949, 21216, 21479, 21738, 21994, 22245,
+  22493, 22737, 22977, 23213, 23446, 23674, 23899, 24120,
+  24336, 24550, 24759, 24965, 25166, 25365, 25559, 25750,
+  25937, 26120, 26300, 26476, 26649, 26818, 26983, 27146,
+  27304, 27460, 27612, 27760, 27906, 28048, 28187, 28323,
+  28455, 28585, 28711, 28835, 28955, 29073, 29188, 29299,
+  29409, 29515, 29619, 29720, 29818, 29914, 30007, 30098,
+  30186, 30272, 30356, 30437, 30516, 30593, 30668, 30740,
+  30810, 30879, 30945, 31010, 31072, 31133, 31192, 31249,
+  31304, 31358, 31410, 31460, 31509, 31556, 31601, 31646,
+  31688, 31730, 31770, 31808, 31846, 31882, 31917, 31950,
+  31983, 32014, 32044, 32074, 32102, 32129, 32155, 32180,
+  32205, 32228, 32251, 32273, 32294, 32314, 32333, 32352,
+  32370, 32387, 32404, 32420, 32435, 32450, 32464, 32477,
+  32490, 32503, 32515, 32526, 32537, 32548, 32558, 32568,
+  32577, 32586, 32595, 32603, 32611, 32618, 32625, 32632,
+  32639, 32645, 32651, 32657, 32662, 32667, 32672, 32677,
+  32682, 32686, 32690, 32694, 32698, 32702, 32705, 32708,
+  32711, 32714, 32717, 32720, 32722, 32725, 32727, 32729,
+  32731, 32733, 32735, 32737, 32739, 32740, 32742, 32743,
+  32745, 32746, 32747, 32748, 32749, 32750, 32751, 32752,
+  32753, 32754, 32755, 32756, 32757, 32757, 32758, 32758,
+  32759, 32760, 32760, 32761, 32761, 32761, 32762, 32762,
+  32763, 32763, 32763, 32764, 32764, 32764, 32764, 32765,
+  32765, 32765, 32765, 32766, 32766, 32766, 32766, 32767,
+];
+
+/**
+ * A single RNG stream: WELL1024a (the upstream "complex" RNG) with an
+ * optional LCRNG "quick" mode, faithful to z-rand.c.
+ */
+export class Rng {
+  private state = new Uint32Array(RAND_DEG);
+  private stateI = 0;
+  private quick: boolean;
+  /** Rand_value: the quick-mode LCRNG state. */
+  private value: number;
+  private fixed = false;
+  private fixval = 0;
+
+  constructor(seed: number, opts?: { quick?: boolean }) {
+    this.quick = opts?.quick ?? false;
+    this.value = seed >>> 0;
+    if (!this.quick) {
+      this.stateInit(seed);
+    }
+  }
+
+  /**
+   * Rand_state_init: seed the WELL table via LCRNG propagation, then cycle
+   * the table ten times per degree.
+   */
+  stateInit(seed: number): void {
+    this.state.fill(0);
+    this.stateI = 0;
+    this.state[0] = seed >>> 0;
+    for (let i = 1; i < RAND_DEG; i++) {
+      this.state[i] = lcrng(this.state[i - 1] as number);
+    }
+    for (let i = 0; i < RAND_DEG * 10; i++) {
+      const j = (this.stateI + 1) % RAND_DEG;
+      this.state[j] =
+        (((this.state[j] as number) + (this.state[this.stateI] as number)) >>>
+          0);
+      this.stateI = j;
+    }
+  }
+
+  /** WELLRNG1024a step. */
+  private well(): number {
+    const s = this.state;
+    const i = this.stateI;
+    const v0 = s[i] as number;
+    const vm1 = s[(i + 3) & 31] as number;
+    const vm2 = s[(i + 24) & 31] as number;
+    const vm3 = s[(i + 10) & 31] as number;
+    const vrm1 = s[(i + 31) & 31] as number;
+    const z0 = vrm1;
+    const z1 = (v0 ^ (vm1 ^ (vm1 >>> 8))) >>> 0;
+    const z2 = ((vm2 ^ ((vm2 << 19) >>> 0)) ^ (vm3 ^ ((vm3 << 14) >>> 0))) >>> 0;
+    s[i] = (z1 ^ z2) >>> 0;
+    const newV0 =
+      ((z0 ^ ((z0 << 11) >>> 0)) ^
+        (z1 ^ ((z1 << 7) >>> 0)) ^
+        (z2 ^ ((z2 << 13) >>> 0))) >>>
+      0;
+    s[(i + 31) & 31] = newV0;
+    this.stateI = (i + 31) & 31;
+    return this.state[this.stateI] as number;
+  }
+
+  /**
+   * Rand_div: extract a random number from 0 to m - 1 via unbiased
+   * partitioned division of 28-bit values.
+   */
+  randDiv(m: number): number {
+    if (m > 0x10000000) {
+      throw new RangeError(`Rand_div: m must be <= 0x10000000, got ${m}`);
+    }
+    if (m <= 1) return 0;
+    if (this.fixed) {
+      // C evaluates rand_fixval * 1000 * (m - 1) in uint32 with wrap.
+      let t = Math.imul(this.fixval, 1000) >>> 0;
+      t = Math.imul(t, m - 1) >>> 0;
+      return Math.trunc(t / (100 * 1000));
+    }
+    const n = Math.trunc(0x10000000 / m);
+    for (;;) {
+      let r: number;
+      if (this.quick) {
+        this.value = lcrng(this.value);
+        r = Math.trunc(((this.value >>> 4) & 0x0fffffff) / n);
+      } else {
+        r = Math.trunc(((this.well() >>> 4) & 0x0fffffff) / n);
+      }
+      if (r < m) return r;
+    }
+  }
+
+  /** randint0(M): 0 <= X < M, uniform. */
+  randint0(m: number): number {
+    return this.randDiv(m);
+  }
+
+  /** randint1(M): 1 <= X <= M, uniform. */
+  randint1(m: number): number {
+    return this.randDiv(m) + 1;
+  }
+
+  /** one_in_(x): true one time in x. */
+  oneIn(x: number): boolean {
+    return this.randint0(x) === 0;
+  }
+
+  /** rand_range: A <= X <= B, uniform. */
+  randRange(a: number, b: number): number {
+    if (a === b) return a;
+    if (a > b) {
+      throw new RangeError(`rand_range: A (${a}) must be <= B (${b})`);
+    }
+    return a + this.randDiv(1 + b - a);
+  }
+
+  /** rand_spread(A, D): A - D <= X <= A + D, uniform. */
+  randSpread(a: number, d: number): number {
+    return a + this.randint0(1 + d + d) - d;
+  }
+
+  /**
+   * Rand_normal: a random integer from a (table-driven pseudo-)normal
+   * distribution with the given mean and standard deviation.
+   */
+  randNormal(mean: number, stand: number): number {
+    if (stand < 1) return mean;
+    const tmp = this.randint0(32768);
+    let low = 0;
+    let high = 256;
+    while (low < high) {
+      const mid = (low + high) >> 1;
+      if ((RAND_NORMAL_TABLE[mid] as number) < tmp) {
+        low = mid + 1;
+      } else {
+        high = mid;
+      }
+    }
+    const offset = Math.trunc((stand * low) / 64);
+    if (this.oneIn(2)) return mean - offset;
+    return mean + offset;
+  }
+
+  /**
+   * Rand_sample: an integer from a distribution with known mean and
+   * approximate bounds; standU/standL are 10x the assumed standard
+   * deviations to each bound.
+   */
+  randSample(
+    mean: number,
+    upper: number,
+    lower: number,
+    standU: number,
+    standL: number,
+  ): number {
+    let pick = this.randNormal(0, 1000);
+    if (pick > 0) {
+      pick *= upper - mean;
+      pick = Math.trunc(pick / (100 * standU));
+    } else if (pick < 0) {
+      pick *= mean - lower;
+      pick = Math.trunc(pick / (100 * standL));
+    }
+    return mean + pick;
+  }
+
+  /** damroll: sum of `num` rolls of a `sides`-sided die. */
+  damroll(num: number, sides: number): number {
+    if (sides <= 0) return 0;
+    let sum = 0;
+    for (let i = 0; i < num; i++) sum += this.randint1(sides);
+    return sum;
+  }
+
+  /** Division that rounds up or down randomly, weighted by the remainder. */
+  private simulateDivision(dividend: number, divisor: number): number {
+    let quotient = Math.trunc(dividend / divisor);
+    const remainder = dividend % divisor;
+    if (this.randint0(divisor) < remainder) quotient++;
+    return quotient;
+  }
+
+  /**
+   * m_bonus: an enchantment bonus from a normal distribution whose mean
+   * approaches max as level approaches MAX_RAND_DEPTH.
+   */
+  mBonus(max: number, level: number): number {
+    if (level >= MAX_RAND_DEPTH) level = MAX_RAND_DEPTH - 1;
+    const bonus = this.simulateDivision(max * level, MAX_RAND_DEPTH);
+    const stand = this.simulateDivision(max, 4);
+    const value = this.randNormal(bonus, stand);
+    if (value < 0) return 0;
+    if (value > max) return max;
+    return value;
+  }
+
+  /** m_bonus_calc: aspect-parameterized companion of mBonus. */
+  mBonusCalc(max: number, level: number, aspect: Aspect): number {
+    switch (aspect) {
+      case "extremify":
+      case "maximise":
+        return max;
+      case "randomise":
+        return this.mBonus(max, level);
+      case "minimise":
+        return 0;
+      case "average":
+        return Math.trunc((max * level) / MAX_RAND_DEPTH);
+    }
+  }
+
+  /** damcalc: aspect-parameterized companion of damroll. */
+  damcalc(num: number, sides: number, aspect: Aspect): number {
+    switch (aspect) {
+      case "maximise":
+      case "extremify":
+        return num * sides;
+      case "randomise":
+        return this.damroll(num, sides);
+      case "minimise":
+        return num;
+      case "average":
+        return Math.trunc((num * (sides + 1)) / 2);
+    }
+  }
+
+  /** randcalc: evaluate a RandomValue under an aspect. */
+  randcalc(v: RandomValue, level: number, aspect: Aspect): number {
+    if (aspect === "extremify") {
+      const min = this.randcalc(v, level, "minimise");
+      const max = this.randcalc(v, level, "maximise");
+      return Math.abs(min) > Math.abs(max) ? min : max;
+    }
+    const dmg = this.damcalc(v.dice, v.sides, aspect);
+    const bonus = this.mBonusCalc(v.mBonus, level, aspect);
+    return v.base + dmg + bonus;
+  }
+
+  /** Whether `test` lies within the RandomValue's possible range. */
+  randcalcValid(v: RandomValue, test: number): boolean {
+    if (test < this.randcalc(v, 0, "minimise")) return false;
+    if (test > this.randcalc(v, 0, "maximise")) return false;
+    return true;
+  }
+
+  /** Whether the RandomValue actually varies. */
+  randcalcVaries(v: RandomValue): boolean {
+    return (
+      this.randcalc(v, 0, "minimise") !== this.randcalc(v, 0, "maximise")
+    );
+  }
+
+  /** random_chance_check: roll a numerator-in-denominator chance. */
+  randomChanceCheck(c: RandomChance): boolean {
+    return this.randint0(c.denominator) >= c.denominator - c.numerator;
+  }
+
+  /**
+   * rand_fix: make randDiv return a fixed percentage of its maximum rather
+   * than a random value (upstream test hook).
+   */
+  randFix(val: number): void {
+    this.fixed = true;
+    this.fixval = val >>> 0;
+  }
+
+  /** Undo randFix (upstream never needs this; tests do). */
+  randUnfix(): void {
+    this.fixed = false;
+    this.fixval = 0;
+  }
+
+  /** Snapshot the full generator state for savefiles. */
+  getState(): RngState {
+    return {
+      quick: this.quick,
+      value: this.value,
+      state: Array.from(this.state),
+      stateI: this.stateI,
+      fixed: this.fixed,
+      fixval: this.fixval,
+    };
+  }
+
+  /**
+   * Restore a snapshot taken with getState() (or a savefile rd_randomizer).
+   * Matches load.c L388-415: state_i is reduced modulo RAND_DEG and
+   * Rand_quick is forced false so the WELL stream continues (never the
+   * simple LCRNG). Fixed/fixval are not part of the C save block; they
+   * remain as restored for the port's test/debug seams only when present.
+   */
+  setState(s: RngState): void {
+    if (s.state.length !== RAND_DEG) {
+      throw new RangeError(
+        `RngState.state must have ${RAND_DEG} entries, got ${s.state.length}`,
+      );
+    }
+    this.value = s.value >>> 0;
+    this.state = Uint32Array.from(s.state);
+    /* for safety, make sure state_i < RAND_DEG (load.c L399-400) */
+    this.stateI = ((s.stateI % RAND_DEG) + RAND_DEG) % RAND_DEG;
+    this.quick = false;
+    this.fixed = s.fixed;
+    this.fixval = s.fixval;
+  }
+}
+
+/**
+ * random_chance_scaled: rescale a chance ratio to a new denominator
+ * (pure arithmetic; no RNG state involved).
+ */
+export function randomChanceScaled(c: RandomChance, scale: number): number {
+  return Math.trunc((scale * c.numerator) / c.denominator);
+}
+
+/**
+ * A set of named, independently seeded RNG streams. This replaces the
+ * upstream seed-swap trick (seed_flavor, seed_randart) with first-class
+ * streams; each stream is a faithful WELL1024a generator.
+ */
+export class RngStreams {
+  private streams = new Map<string, Rng>();
+
+  /** Create (or re-seed) the named stream. */
+  create(name: string, seed: number): Rng {
+    const rng = new Rng(seed);
+    this.streams.set(name, rng);
+    return rng;
+  }
+
+  /** Get a stream; throws if it was never created. */
+  get(name: string): Rng {
+    const rng = this.streams.get(name);
+    if (!rng) throw new Error(`RNG stream not created: ${name}`);
+    return rng;
+  }
+
+  has(name: string): boolean {
+    return this.streams.has(name);
+  }
+
+  names(): string[] {
+    return Array.from(this.streams.keys());
+  }
+
+  /** Snapshot every stream, for savefiles. */
+  getState(): Record<string, RngState> {
+    const out: Record<string, RngState> = {};
+    for (const [name, rng] of this.streams) out[name] = rng.getState();
+    return out;
+  }
+
+  /** Restore a snapshot taken with getState(). */
+  setState(states: Record<string, RngState>): void {
+    this.streams.clear();
+    for (const [name, s] of Object.entries(states)) {
+      const rng = new Rng(0);
+      rng.setState(s);
+      this.streams.set(name, rng);
+    }
+  }
+}