@rpgm-tools/neo-angband-core 0.10.0

package/dist/rng.js

@@ -0,0 +1,404 @@
+/**
+ * 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;
+/** LCRNG(X) = X * 1103515245 + 12345, in uint32. */
+function lcrng(x) {
+    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 = [
+    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 {
+    state = new Uint32Array(RAND_DEG);
+    stateI = 0;
+    quick;
+    /** Rand_value: the quick-mode LCRNG state. */
+    value;
+    fixed = false;
+    fixval = 0;
+    constructor(seed, opts) {
+        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) {
+        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]);
+        }
+        for (let i = 0; i < RAND_DEG * 10; i++) {
+            const j = (this.stateI + 1) % RAND_DEG;
+            this.state[j] =
+                ((this.state[j] + this.state[this.stateI]) >>>
+                    0);
+            this.stateI = j;
+        }
+    }
+    /** WELLRNG1024a step. */
+    well() {
+        const s = this.state;
+        const i = this.stateI;
+        const v0 = s[i];
+        const vm1 = s[(i + 3) & 31];
+        const vm2 = s[(i + 24) & 31];
+        const vm3 = s[(i + 10) & 31];
+        const vrm1 = s[(i + 31) & 31];
+        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];
+    }
+    /**
+     * Rand_div: extract a random number from 0 to m - 1 via unbiased
+     * partitioned division of 28-bit values.
+     */
+    randDiv(m) {
+        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;
+            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) {
+        return this.randDiv(m);
+    }
+    /** randint1(M): 1 <= X <= M, uniform. */
+    randint1(m) {
+        return this.randDiv(m) + 1;
+    }
+    /** one_in_(x): true one time in x. */
+    oneIn(x) {
+        return this.randint0(x) === 0;
+    }
+    /** rand_range: A <= X <= B, uniform. */
+    randRange(a, b) {
+        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, d) {
+        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, stand) {
+        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] < 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, upper, lower, standU, standL) {
+        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, sides) {
+        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. */
+    simulateDivision(dividend, divisor) {
+        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, level) {
+        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, level, aspect) {
+        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, sides, aspect) {
+        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, level, aspect) {
+        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, test) {
+        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) {
+        return (this.randcalc(v, 0, "minimise") !== this.randcalc(v, 0, "maximise"));
+    }
+    /** random_chance_check: roll a numerator-in-denominator chance. */
+    randomChanceCheck(c) {
+        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) {
+        this.fixed = true;
+        this.fixval = val >>> 0;
+    }
+    /** Undo randFix (upstream never needs this; tests do). */
+    randUnfix() {
+        this.fixed = false;
+        this.fixval = 0;
+    }
+    /** Snapshot the full generator state for savefiles. */
+    getState() {
+        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) {
+        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, scale) {
+    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 {
+    streams = new Map();
+    /** Create (or re-seed) the named stream. */
+    create(name, seed) {
+        const rng = new Rng(seed);
+        this.streams.set(name, rng);
+        return rng;
+    }
+    /** Get a stream; throws if it was never created. */
+    get(name) {
+        const rng = this.streams.get(name);
+        if (!rng)
+            throw new Error(`RNG stream not created: ${name}`);
+        return rng;
+    }
+    has(name) {
+        return this.streams.has(name);
+    }
+    names() {
+        return Array.from(this.streams.keys());
+    }
+    /** Snapshot every stream, for savefiles. */
+    getState() {
+        const out = {};
+        for (const [name, rng] of this.streams)
+            out[name] = rng.getState();
+        return out;
+    }
+    /** Restore a snapshot taken with getState(). */
+    setState(states) {
+        this.streams.clear();
+        for (const [name, s] of Object.entries(states)) {
+            const rng = new Rng(0);
+            rng.setState(s);
+            this.streams.set(name, rng);
+        }
+    }
+}
+//# sourceMappingURL=rng.js.map

package/dist/rng.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng.js","sourceRoot":"","sources":["../src/rng.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,CAAC;AA6C3B,oDAAoD;AACpD,SAAS,KAAK,CAAC,CAAS;IACtB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,iBAAiB,GAAsB;IAC3C,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IAC5C,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IAC9C,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IAC9C,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACrD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK;IACtD,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,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"}

package/dist/save/buffer.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Savefile serialization primitives - a faithful port of the block-based
+ * reader/writer in reference/src/savefile.c.
+ *
+ * The upstream format (unchanged here):
+ * - A 4-byte file magic {83,97,118,101} = "Save", then a 4-byte version
+ *   stamp.
+ * - A sequence of blocks. Each block is a 28-byte header (16-byte
+ *   zero-padded name, u32 version, u32 payload size, u32 checksum) then
+ *   the payload, then zero-to-three padding bytes so the payload aligns
+ *   to a 4-byte boundary. Padding is not part of the payload or checksum.
+ * - Every multi-byte value is little-endian.
+ * - The block checksum is a running uint32 additive sum of every payload
+ *   byte, matching savefile.c's `buffer_check += v`. It detects
+ *   CORRUPTION; it is trivially recomputable and is NOT tamper-proof.
+ *   For a tamper deterrent, see ./integrity (a whole-file hash seam);
+ *   for real anti-tamper, saves must be server-authoritative.
+ *
+ * Parity note: the upstream 4-byte alignment padding is the literal byte
+ * 'x' (0x78). We reproduce that so byte streams match upstream exactly.
+ */
+/** File magic: the ASCII bytes of "Save". */
+export declare const SAVEFILE_MAGIC: readonly number[];
+/** Fixed block-header size: 16-byte name + three u32 fields. */
+export declare const SAVEFILE_HEAD_SIZE = 28;
+/** A parsed block header. */
+export interface BlockHeader {
+    name: string;
+    version: number;
+    size: number;
+    check: number;
+}
+/**
+ * Writes a single block's payload while maintaining the additive
+ * checksum, exactly like savefile.c's sf_put path.
+ */
+export declare class SaveWriter {
+    private buf;
+    private check;
+    /** wr_byte: append one byte and fold it into the checksum. */
+    putByte(v: number): void;
+    /** wr_u16b: little-endian unsigned 16-bit. */
+    putU16(v: number): void;
+    /** wr_s16b: signed 16-bit (same bytes as u16). */
+    putS16(v: number): void;
+    /** wr_u32b: little-endian unsigned 32-bit. */
+    putU32(v: number): void;
+    /** wr_s32b: signed 32-bit (same bytes as u32). */
+    putS32(v: number): void;
+    /** wr_string: bytes of the string then a null terminator. */
+    putString(str: string): void;
+    /** pad_bytes: n zero bytes (checksummed, as upstream pads inside blocks). */
+    pad(n: number): void;
+    /** Current checksum (uint32) over everything written so far. */
+    checksum(): number;
+    /** The payload bytes written so far. */
+    payload(): Uint8Array;
+    /** Byte length of the payload. */
+    get length(): number;
+}
+/**
+ * Reads a block's payload while maintaining the additive checksum, so a
+ * caller can compare it against the header's stored checksum. Mirrors
+ * savefile.c's sf_get path. Reading past the end throws, matching the
+ * upstream "Broken savefile" quit.
+ */
+export declare class SaveReader {
+    private readonly buf;
+    private pos;
+    private check;
+    constructor(buf: Uint8Array);
+    private next;
+    /** rd_byte. */
+    getByte(): number;
+    /** rd_u16b: little-endian unsigned 16-bit. */
+    getU16(): number;
+    /** rd_s16b: signed 16-bit. */
+    getS16(): number;
+    /** rd_u32b: little-endian unsigned 32-bit. */
+    getU32(): number;
+    /** rd_s32b: signed 32-bit. */
+    getS32(): number;
+    /** rd_string: read up to a null terminator, capping at max chars. */
+    getString(max: number): string;
+    /** strip_bytes: discard n bytes (still checksummed). */
+    strip(n: number): void;
+    /** Running checksum (uint32) over everything read so far. */
+    checksum(): number;
+    /** Bytes consumed so far. */
+    get position(): number;
+}
+/** A block ready to serialize: name, version, and a payload writer. */
+export interface SaveBlock {
+    name: string;
+    version: number;
+    write(w: SaveWriter): void;
+}
+/** A loader for one block name+version: reads from a SaveReader. */
+export type BlockLoader<T> = (r: SaveReader, header: BlockHeader) => T;
+/**
+ * Assemble the full savefile byte stream: magic + version stamp + each
+ * block framed exactly as try_save does (28-byte header, payload,
+ * 4-byte alignment padding of 'x').
+ */
+export declare function writeSavefile(version: number, blocks: SaveBlock[]): Uint8Array;
+/** The result of splitting a savefile into its framed blocks. */
+export interface ParsedSavefile {
+    version: number;
+    blocks: Array<{
+        header: BlockHeader;
+        payload: Uint8Array;
+    }>;
+}
+/**
+ * Split a savefile stream into blocks and VERIFY each block's additive
+ * checksum. Throws on a bad magic or a checksum mismatch (the corruption
+ * signal). Callers then feed each payload to a SaveReader + BlockLoader.
+ */
+export declare function readSavefile(buf: Uint8Array): ParsedSavefile;
+//# sourceMappingURL=buffer.d.ts.map

package/dist/save/buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../src/save/buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,6CAA6C;AAC7C,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAAuB,CAAC;AAEpE,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAKrC,6BAA6B;AAC7B,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,GAAG,CAAgB;IAC3B,OAAO,CAAC,KAAK,CAAK;IAElB,8DAA8D;IAC9D,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAMxB,8CAA8C;IAC9C,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAKvB,kDAAkD;IAClD,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAIvB,8CAA8C;IAC9C,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAOvB,kDAAkD;IAClD,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAIvB,6DAA6D;IAC7D,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAO5B,6EAA6E;IAC7E,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAIpB,gEAAgE;IAChE,QAAQ,IAAI,MAAM;IAIlB,wCAAwC;IACxC,OAAO,IAAI,UAAU;IAIrB,kCAAkC;IAClC,IAAI,MAAM,IAAI,MAAM,CAEnB;CACF;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IAIT,OAAO,CAAC,QAAQ,CAAC,GAAG;IAHhC,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,KAAK,CAAK;gBAEW,GAAG,EAAE,UAAU;IAE5C,OAAO,CAAC,IAAI;IASZ,eAAe;IACf,OAAO,IAAI,MAAM;IAIjB,8CAA8C;IAC9C,MAAM,IAAI,MAAM;IAMhB,8BAA8B;IAC9B,MAAM,IAAI,MAAM;IAKhB,8CAA8C;IAC9C,MAAM,IAAI,MAAM;IAQhB,8BAA8B;IAC9B,MAAM,IAAI,MAAM;IAIhB,qEAAqE;IACrE,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAU9B,wDAAwD;IACxD,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAItB,6DAA6D;IAC7D,QAAQ,IAAI,MAAM;IAIlB,6BAA6B;IAC7B,IAAI,QAAQ,IAAI,MAAM,CAErB;CACF;AAED,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;CAC5B;AAED,oEAAoE;AACpE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,KAAK,CAAC,CAAC;AAMvE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,UAAU,CAwB9E;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;CAC7D;AAYD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,cAAc,CAiC5D"}