hbengine 0.2.3 → 0.4.0

package/engine-examples/plinko-jar/math/plinko-jar-8-low.tsv

@@ -0,0 +1,9 @@
+70	{"k":4}
+56	{"k":3}
+56	{"k":5}
+28	{"k":2}
+28	{"k":6}
+8	{"k":1}
+8	{"k":7}
+1	{"k":0}
+1	{"k":8}

package/engine-examples/plinko-jar/math/plinko-jar-8-medium.tsv

@@ -0,0 +1,9 @@
+70	{"k":4}
+56	{"k":3}
+56	{"k":5}
+28	{"k":2}
+28	{"k":6}
+8	{"k":1}
+8	{"k":7}
+1	{"k":0}
+1	{"k":8}

package/engine-examples/plinko-jar/math/plinko-jar-meter-jar.tsv

@@ -0,0 +1,5 @@
+50	{"x":2}
+20	{"x":5}
+20	{"x":10}
+4	{"x":25}
+6	{"x":50}

package/engine-examples/plinko-jar/math-kit/pack.mjs

@@ -0,0 +1,242 @@
+/**
+ * The maths kit: a game's outcomes as weighted rows, its RTP exactly, and the
+ * pack the engine verifies (SPEC §1). A row is { weight, data, pay } where
+ * pay is { betId: multBp } (10000 = 1×, the total stake back) and data is
+ * what the bundle receives to show the round.
+ *
+ *   import { writePack, fit } from './pack.mjs';
+ *   const rows = fit(simulated, 9600);            // exact 96.00% (balance() when no row pays nothing)
+ *   writePack('math', { game: 'my-slot', rtpBp: 9600, modes: [{ id: 'base', rows, bets: ['spin'] }] });
+ *
+ * Every number here is an integer: weights are BigInt, RTP is a fraction.
+ */
+import { mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MAX_SUM = 1n << 63n;
+
+// A small seeded generator for building tables (never for play: the engine draws).
+export function rng(seed) {
+    let a = seed >>> 0;
+    const next = () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    next.int = (n) => Math.floor(next() * n);
+    return next;
+}
+
+export function binomial(n, k) {
+    let r = 1n;
+    for (let i = 1n; i <= BigInt(k); i++) r = (r * BigInt(n - k) + r * i) / i;
+    return r;
+}
+
+const gcd = (a, b) => { while (b) [a, b] = [b, a % b]; return a < 0n ? -a : a; };
+
+/** RTP of one bet over rows, exactly: { num, den } in basis points, and a 4-decimal string. */
+export function rtp(rows, bet) {
+    let num = 0n, den = 0n;
+    for (const r of rows) { den += r.weight; num += r.weight * BigInt(r.pay[bet] || 0); }
+    return { num, den, bp: bp4(num, den) };
+}
+
+export const bp4 = (num, den) => {
+    const x = (num * 10000n) / den; // bp × 10^4, truncated as the verifier reports it
+    return `${x / 10000n}.${String(x % 10000n).padStart(4, '0')}`;
+};
+
+/**
+ * Weights so that one bet's RTP is exactly targetBp: the paying rows keep
+ * their proportions (all multiplied by one integer), the rows that pay
+ * nothing share what is left in their own proportions. Needs rows that pay
+ * nothing, and paying rows that alone return more than the target.
+ */
+export function fit(rows, targetBp, bet = Object.keys(rows[0].pay)[0]) {
+    const T = BigInt(targetBp);
+    const wins = rows.filter((r) => r.pay[bet] > 0), zeros = rows.filter((r) => !(r.pay[bet] > 0));
+    if (!zeros.length) throw new Error('fit: no row pays nothing');
+    const S = wins.reduce((s, r) => s + r.weight * (BigInt(r.pay[bet]) - T), 0n); // what the wins return above T
+    if (S <= 0n) throw new Error(`fit: the paying rows alone return less than ${targetBp / 100}%`);
+    const k = T / gcd(S, T);     // so that k·S is a multiple of T
+    const Z = (k * S) / T;       // the weight the zero rows share
+    const zw = zeros.reduce((s, r) => s + r.weight, 0n);
+    let given = 0n;
+    const out = rows.map((r) => {
+        if (r.pay[bet] > 0) return { ...r, weight: r.weight * k };
+        const w = (Z * r.weight) / zw;
+        given += w;
+        return { ...r, weight: w };
+    });
+    // The rounding remainder goes to the first zero row; a zero weight is dropped.
+    const first = out.find((r) => !(r.pay[bet] > 0));
+    first.weight += Z - given;
+    const kept = out.filter((r) => r.weight > 0n);
+    const check = rtp(kept, bet);
+    if (check.num !== T * check.den) throw new Error('fit: not exact (a bug)');
+    return kept;
+}
+
+/**
+ * Weights so that one bet's RTP is exactly targetBp when every row pays
+ * something (a bonus buy, plinko): rows paying more than the target are
+ * all multiplied by one integer, rows paying less by another, so each
+ * group keeps its own proportions and the two balance at the target.
+ */
+export function balance(rows, targetBp, bet = Object.keys(rows[0].pay)[0]) {
+    const T = BigInt(targetBp);
+    const over = rows.reduce((s, r) => s + (BigInt(r.pay[bet] || 0) > T ? r.weight * (BigInt(r.pay[bet]) - T) : 0n), 0n);
+    const under = rows.reduce((s, r) => s + (BigInt(r.pay[bet] || 0) < T ? r.weight * (T - BigInt(r.pay[bet] || 0)) : 0n), 0n);
+    if (!over || !under) throw new Error('balance: needs rows on both sides of the target');
+    const g = gcd(over, under);
+    const out = rows.map((r) => ({ ...r, weight: r.weight * (BigInt(r.pay[bet] || 0) > T ? under / g : BigInt(r.pay[bet] || 0) < T ? over / g : 1n) }));
+    const check = rtp(out, bet);
+    if (check.num !== T * check.den) throw new Error('balance: not exact (a bug)');
+    return out;
+}
+
+/** Rows with the same data are one row with the sum of their weights. */
+export function merge(rows) {
+    const by = new Map();
+    for (const r of rows) {
+        const key = JSON.stringify(r.data);
+        const x = by.get(key);
+        if (x) x.weight += r.weight;
+        else by.set(key, { ...r, weight: r.weight });
+    }
+    return [...by.values()];
+}
+
+// Inclusive [lo, hi] ranges of sorted indexes.
+function ranges(ids) {
+    const out = [];
+    for (const i of ids) {
+        const last = out.at(-1);
+        if (last && last[1] === i - 1) last[1] = i;
+        else out.push([i, i]);
+    }
+    return out;
+}
+
+// The verifier's bound on one bet's pay tiers (housegames-backend mathpack.MaxTiers).
+export const MAX_TIERS = 16384;
+
+// The most a pack's maths may be: the files in math/ together, as their bytes
+// on disk. Housebets' limit, not a verifier's: the live engine holds a game's
+// tables in memory, and the upload's checks slow as they grow. Checked here,
+// by hbengine before it sends a pack, and by the upload's own check
+// (pipeline/job), so no way in passes a bigger one. The Go side's figure is
+// internal/archive MaxMathBytes (pack.test.mjs holds the two together).
+export const MAX_MATH_BYTES = 200 * 1024 * 1024;
+
+// The refusal of maths over MAX_MATH_BYTES, in the same words wherever it is
+// checked; the size is rounded up, so maths just over never reads as 200 MB.
+export const mathTooLarge = (bytes) => `The maths is ${Math.ceil((bytes * 10) / 1048576) / 10} MB; a pack's maths may be at most ${MAX_MATH_BYTES / 1048576} MB.`;
+
+// The bytes of the maths in dir: its files together (math/ holds nothing below them).
+export const mathBytes = (dir) => readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile()).reduce((n, e) => n + statSync(join(dir, e.name)).size, 0);
+
+/**
+ * What a meter adds to the RTP of every bet of its modes, exactly (GUIDE:
+ * Meters): E[award] ÷ fill, in basis points of the stake. `rows` are the
+ * award's outcomes, `pay` the multiplier of the reference in bp.
+ */
+export function meterRtp({ fill, rows }) {
+    const den = rows.reduce((s, r) => s + r.weight, 0n) * BigInt(fill);
+    const num = rows.reduce((s, r) => s + r.weight * BigInt(r.pay || 0), 0n);
+    return { num, den, bp: bp4(num, den) };
+}
+
+/**
+ * Writes manifest.json and one table per mode. A mode is { id, label?, rows,
+ * bets: [id | {id, label}], meter? }; its rows are sorted by what the first bet pays,
+ * so each pay tier is one range. Prints every bet's exact RTP, hit rate and
+ * largest multiplier; returns them.
+ *
+ * meters: [{ id, label?, fill, rows }] — progress that pays (GUIDE: Meters).
+ * A meter's rows are its award's outcomes, each { weight, pay, data? } with
+ * `pay` in bp of the meter's reference (20000 = twice the reference); a mode
+ * names the meter its rounds fill with `meter: id`. Every bet of such a mode
+ * reports base + meter RTP, and the base must clear 90% on its own.
+ */
+export function writePack(dir, { game, rtpBp, modes, meters = [] }) {
+    if (!Array.isArray(modes) || modes.length < 1 || modes.length > 64) throw new Error('a pack needs 1 to 64 modes');
+    for (const mode of modes) {
+        if (!Array.isArray(mode.bets) || mode.bets.length < 1 || mode.bets.length > 256) throw new Error(`${mode.id}: 1 to 256 bets per mode`);
+    }
+    const manifest = { format: 'house-engine-math/1', game, rtpBp, modes: [] };
+    const report = [];
+    const tables = new Map();
+    for (const mode of modes) {
+        const bets = mode.bets.map((b) => (typeof b === 'string' ? { id: b } : b));
+        const first = bets[0].id;
+        const rows = [...mode.rows].sort((a, b) => (a.pay[first] || 0) - (b.pay[first] || 0));
+        if (rows.length < 2 || rows.length > 1_000_000) throw new Error(`${mode.id}: 2 to 1,000,000 rows, not ${rows.length}`);
+        const sum = rows.reduce((s, r) => s + r.weight, 0n);
+        if (sum > MAX_SUM) throw new Error(`${mode.id}: weights sum to more than 2^63`);
+        const lines = rows.map((r) => {
+            if (r.weight <= 0n) throw new Error(`${mode.id}: a weight is not positive`);
+            const json = r.data === undefined ? '' : JSON.stringify(r.data);
+            if (Buffer.byteLength(json) > 4096) throw new Error(`${mode.id}: a row's data is over 4096 UTF-8 bytes`);
+            return json ? `${r.weight}\t${json}` : String(r.weight);
+        });
+        const table = `${game}-${mode.id}.tsv`;
+        tables.set(table, lines.join('\n') + '\n');
+        manifest.modes.push({
+            id: mode.id, ...(mode.label ? { label: mode.label } : {}), kind: 'table', table, ...(mode.meter ? { meter: mode.meter } : {}),
+            bets: bets.map((b) => {
+                const tiers = new Map();
+                rows.forEach((r, i) => { const m = r.pay[b.id] || 0; if (m > 0) (tiers.get(m) || tiers.set(m, []).get(m)).push(i); });
+                const { num, den, bp } = rtp(rows, b.id);
+                const hit = rows.reduce((s, r) => s + (r.pay[b.id] > 0 ? r.weight : 0n), 0n);
+                // The engine's verifier refuses a bet with more pay tiers than this (one tier per distinct
+                // multiplier): refused here, at the build, not at the upload (mathpack.MaxTiers).
+                if (tiers.size > MAX_TIERS) throw new Error(`${mode.id}: bet "${b.id}": ${tiers.size} distinct payouts (tiers), at most ${MAX_TIERS}: round the multipliers to fewer values`);
+                const max = Math.max(...tiers.keys());
+                const entry = { mode: mode.id, bet: b.id, rtp: bp, hit: bp4(hit * 10000n, den), max: max / 10000, rows: rows.length, exact: num % den === 0n };
+                if (mode.meter) {
+                    const mt = meters.find((x) => x.id === mode.meter);
+                    if (!mt) throw new Error(`${mode.id}: meter "${mode.meter}" is not in meters`);
+                    const add = meterRtp(mt);
+                    // base + E[award]/fill, as one exact fraction
+                    const tn = num * add.den + add.num * den, td = den * add.den;
+                    Object.assign(entry, { baseRtp: bp, meter: mode.meter, rtp: bp4(tn, td), exact: tn % td === 0n });
+                }
+                report.push(entry);
+                return { id: b.id, ...(b.label ? { label: b.label } : {}), tiers: [...tiers].map(([multBp, ids]) => ({ outcomes: ranges(ids), multBp })) };
+            }),
+        });
+    }
+    for (const mt of meters) {
+        if (!Number.isSafeInteger(mt.fill) || mt.fill < 2 || mt.fill > 1_000_000) throw new Error(`meter ${mt.id}: fill must be 2 to 1,000,000`);
+        if (!modes.some((m) => m.meter === mt.id)) throw new Error(`meter ${mt.id}: no mode fills it`);
+        const rows = [...mt.rows].sort((a, b) => (a.pay || 0) - (b.pay || 0));
+        if (rows.length < 1) throw new Error(`meter ${mt.id}: an award needs rows`);
+        const table = `${game}-meter-${mt.id}.tsv`;
+        tables.set(table, rows.map((r) => {
+            if (r.weight <= 0n) throw new Error(`meter ${mt.id}: a weight is not positive`);
+            const json = r.data === undefined ? '' : JSON.stringify(r.data);
+            return json ? `${r.weight}\t${json}` : String(r.weight);
+        }).join('\n') + '\n');
+        const tiers = new Map();
+        rows.forEach((r, i) => { const m = r.pay || 0; if (m > 0) (tiers.get(m) || tiers.set(m, []).get(m)).push(i); });
+        if (!tiers.size) throw new Error(`meter ${mt.id}: the award never pays`);
+        (manifest.meters ||= []).push({ id: mt.id, ...(mt.label ? { label: mt.label } : {}), fill: mt.fill, table,
+            award: [...tiers].map(([multBp, ids]) => ({ outcomes: ranges(ids), multBp })) });
+        const ev = meterRtp({ fill: 1, rows });
+        console.log(`meter ${mt.id}: fill ${mt.fill}  award E ${bp4(ev.num, ev.den * 10000n)}× the reference  adds ${meterRtp({ fill: mt.fill, rows }).bp} bp`);
+    }
+    tables.set('manifest.json', JSON.stringify(manifest) + '\n');
+    // The pack as it will be on disk, with what else is in dir already (the
+    // generator, often), measured before a file is written.
+    mkdirSync(dir, { recursive: true });
+    const others = readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile() && !tables.has(e.name));
+    const bytes = [...tables.values()].reduce((n, text) => n + Buffer.byteLength(text), 0) + others.reduce((n, e) => n + statSync(join(dir, e.name)).size, 0);
+    if (bytes > MAX_MATH_BYTES) throw new Error(mathTooLarge(bytes));
+    for (const [name, text] of tables) writeFileSync(join(dir, name), text);
+    for (const r of report) console.log(`${r.mode}/${r.bet}: RTP ${r.rtp} bp${r.meter ? ` (base ${r.baseRtp} + meter ${r.meter})` : ''}  hit ${r.hit} bp  max ${r.max}×  rows ${r.rows}`);
+    return report;
+}

package/engine-examples/plinko-jar/math-kit/package.json

@@ -0,0 +1,8 @@
+{
+    "name": "@housegames/engine-math",
+    "private": true,
+    "version": "0.1.0",
+    "type": "module",
+    "description": "The maths kit: outcomes as weighted rows, exact RTP, an exact fit to a target, the pack the engine verifies; a video slot model (reels, lines, wilds, scatters, free spins) and a tumble model (scatter pays, tumbles, multipliers).",
+    "exports": { "./pack.mjs": "./pack.mjs", "./slot.mjs": "./slot.mjs", "./tumble.mjs": "./tumble.mjs" }
+}

package/engine-examples/plinko-jar/math-kit/slot.mjs

@@ -0,0 +1,94 @@
+/**
+ * A video slot for the maths kit: reels, paylines, a wild, a scatter that
+ * starts free spins (with a multiplier, retriggers), and a win cap. It plays
+ * rounds with a seeded generator to make the table's rows ("books"): every
+ * row is a whole round, base spin and free spins, with what it pays. fit()
+ * then makes the table's RTP exact; the table is the game.
+ *
+ * Pays are in basis points of the total stake (10000 = 1×) for 3, 4, 5 of a
+ * kind on a line, left to right; scatters pay anywhere, times the stake.
+ *
+ * A row's data, for the bundle: { b: spin, f: [spin…], x: free multiplier }
+ * where a spin is [stop0…stopN, winBp, lineMask, scatterCount].
+ */
+export function slot(cfg) {
+    const { reels, freeReels = reels, rows, lines, pays, wild, scatter, maxWinBp } = cfg;
+    const n = reels.length;
+
+    const grid = (strips, stops) => stops.map((s, r) => Array.from({ length: rows }, (_, y) => strips[r][(s + y) % strips[r].length]));
+
+    // One spin's wins: each line pays its best run from the left (wilds stand in).
+    function evaluate(strips, stops) {
+        const g = grid(strips, stops);
+        let win = 0, mask = 0;
+        lines.forEach((line, li) => {
+            const cells = line.map((y, r) => g[r][y]);
+            const sym = cells.find((c) => c !== wild) ?? wild;
+            if (sym === scatter.symbol) return;
+            let count = 0;
+            while (count < n && (cells[count] === sym || cells[count] === wild)) count++;
+            const pay = (pays[sym] || {})[count] || 0;
+            // A run of wilds alone pays as wilds when that is more.
+            let wc = 0;
+            while (wc < n && cells[wc] === wild) wc++;
+            const best = Math.max(pay, (pays[wild] || {})[wc] || 0);
+            if (best > 0) { win += best; mask |= 1 << li; }
+        });
+        const scatters = g.flat().filter((c) => c === scatter.symbol).length;
+        win += (scatter.pays[scatters] || 0);
+        return { win, mask, scatters };
+    }
+
+    const spin = (strips, next) => strips.map((s) => next.int(s.length));
+
+    /** One whole round: the row's data and what it pays (bp of the stake).
+     * A bought round is the free spins alone, as three scatters start them. */
+    function round(next, buy = false) {
+        const stops = buy ? null : spin(reels, next);
+        const base = buy ? { win: 0, scatters: 3 } : evaluate(reels, stops);
+        const data = buy ? { buy: 1 } : { b: [...stops, base.win, base.mask, base.scatters] };
+        let total = base.win;
+        let left = scatter.spins[base.scatters] || 0;
+        if (left) {
+            data.f = [];
+            data.x = scatter.multiplier;
+            while (left > 0 && data.f.length < scatter.cap) {
+                left--;
+                const s = spin(freeReels, next);
+                const e = evaluate(freeReels, s);
+                data.f.push([...s, e.win * scatter.multiplier, e.mask, e.scatters]);
+                total += e.win * scatter.multiplier;
+                left += scatter.retrigger[e.scatters] || 0;
+            }
+        }
+        if (total > maxWinBp) { total = maxWinBp; data.cap = 1; }
+        return { data, pay: total };
+    }
+
+    return { evaluate, round, grid };
+}
+
+/**
+ * Plays `count` rounds (bought ones with `buy`) and keeps them as rows: every paying round, and up to
+ * `losing` different losing rounds that share the weight of every losing
+ * round played (so the rows keep the played RTP and hit rate before fit).
+ */
+export function books(game, next, count, losing = 4000, buy = false) {
+    const wins = new Map(), lose = new Map();
+    let lost = 0n;
+    for (let i = 0; i < count; i++) {
+        const { data, pay } = game.round(next, buy);
+        if (pay <= 0) {
+            lost++;
+            if (lose.size < losing) lose.set(JSON.stringify(data), { weight: 0n, data, pay: { spin: 0 } });
+            continue;
+        }
+        const key = JSON.stringify(data);
+        const r = wins.get(key);
+        if (r) r.weight += 1n;
+        else wins.set(key, { weight: 1n, data, pay: { spin: pay } });
+    }
+    const zeros = [...lose.values()];
+    zeros.forEach((r, i) => { r.weight = lost / BigInt(zeros.length) + (BigInt(i) < lost % BigInt(zeros.length) ? 1n : 0n); });
+    return [...zeros.filter((r) => r.weight > 0n), ...wins.values()];
+}

package/engine-examples/plinko-jar/math-kit/tumble.mjs

@@ -0,0 +1,94 @@
+/**
+ * A tumbling, scatter-pays slot for the maths kit: a cols × rows grid, every
+ * cell drawn by symbol weight; a symbol pays when enough of it is anywhere
+ * on the grid; winners vanish, the rest fall, new symbols drop in, until
+ * nothing pays. Scatters start free spins, where multiplier symbols land
+ * and multiply the spin's win. Like slot.mjs, it plays whole rounds into
+ * rows; fit() then makes the RTP exact.
+ *
+ * Symbols are single characters. Pays are basis points of the stake by
+ * count: { A: [[8, 2000], [10, 5000], [12, 10000]] } pays the highest band
+ * the count reaches.
+ *
+ * A row's data, for the page:
+ *   { b: spin, f: [spin…] }   spin = [grid, [tumble…], multipliers?]
+ *   grid    the first grid, column by column, top to bottom ("ABCDE…")
+ *   tumble  [winners, winBp, fill0, fill1, …]: the symbols that paid, what
+ *           they paid, and per column the new symbols that drop in (top first)
+ *   multipliers  free spins only: the values of the multiplier symbols on the
+ *           last grid, summed onto the spin's win when it won
+ */
+export function tumble(cfg) {
+    const { cols, rows, weights, freeWeights = weights, pays, scatter, bomb, maxWinBp } = cfg;
+    const pick = (w, next) => {
+        const total = w.reduce((s, [, n]) => s + n, 0);
+        let x = next() * total;
+        for (const [s, n] of w) if ((x -= n) < 0) return s;
+        return w[w.length - 1][0];
+    };
+    const table = (o) => Object.entries(o);
+    const base = table(weights), free = table(freeWeights);
+    const counts = Object.keys(scatter.spins).map(Number), least = Math.min(...counts), most = Math.max(...counts);
+
+    // One spin: the grid, its tumbles, and (free spins) its multipliers.
+    function spin(next, inFree) {
+        const w = inFree ? free : base;
+        const draw = () => {
+            const s = pick(w, next);
+            return s === bomb?.symbol && !inFree ? pick(base.filter(([x]) => x !== bomb.symbol), next) : s;
+        };
+        let grid = Array.from({ length: cols }, () => Array.from({ length: rows }, draw));
+        const first = grid.map((c) => c.join('')).join('');
+        const tumbles = [];
+        let win = 0;
+        for (;;) {
+            const counts = {};
+            for (const c of grid) for (const s of c) counts[s] = (counts[s] || 0) + 1;
+            let paid = '', bp = 0;
+            for (const [s, bands] of Object.entries(pays)) {
+                const band = bands.filter(([n]) => counts[s] >= n).at(-1);
+                if (band) { paid += s; bp += band[1]; }
+            }
+            if (!paid) break;
+            win += bp;
+            const fills = grid.map((c) => {
+                const kept = c.filter((s) => !paid.includes(s));
+                const add = Array.from({ length: rows - kept.length }, draw);
+                c.splice(0, rows, ...add, ...kept); // new symbols on top
+                return add.join('');
+            });
+            tumbles.push([paid, bp, ...fills]);
+        }
+        const out = [first, tumbles];
+        const scatters = grid.flat().filter((s) => s === scatter.symbol).length; // on the last grid
+        let total = win;
+        if (inFree && bomb) {
+            const bombs = grid.flat().filter((s) => s === bomb.symbol).map(() => pick(bomb.values, next));
+            if (bombs.length) out.push(bombs);
+            if (win && bombs.length) total = win * bombs.reduce((a, b) => a + b, 0);
+        }
+        return { out, total, scatters };
+    }
+
+    /** One whole round: the row's data and what it pays (bp of the stake). */
+    function round(next) {
+        const b = spin(next, false);
+        const data = { b: b.out };
+        let total = b.total + (scatter.pays[Math.min(b.scatters, most)] || 0);
+        let left = b.scatters >= least ? scatter.spins[Math.min(b.scatters, most)] : 0;
+        if (left) {
+            data.f = [];
+            while (left > 0 && data.f.length < scatter.cap) {
+                left--;
+                const f = spin(next, true);
+                data.f.push(f.out);
+                total += f.total;
+                if (f.scatters >= scatter.retrigger.count) left += scatter.retrigger.spins;
+            }
+        }
+        if (total > maxWinBp) { total = maxWinBp; data.cap = 1; }
+        return { data, pay: total };
+    }
+
+    return { round };
+}

package/engine-examples/tumble/math-kit/pack.mjs

@@ -10,7 +10,7 @@
  *
  * Every number here is an integer: weights are BigInt, RTP is a fraction.
  */
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 const MAX_SUM = 1n << 63n;
@@ -121,16 +121,55 @@ function ranges(ids) {
     return out;
 }
 
+// The verifier's bound on one bet's pay tiers (housegames-backend mathpack.MaxTiers).
+export const MAX_TIERS = 16384;
+
+// The most a pack's maths may be: the files in math/ together, as their bytes
+// on disk. Housebets' limit, not a verifier's: the live engine holds a game's
+// tables in memory, and the upload's checks slow as they grow. Checked here,
+// by hbengine before it sends a pack, and by the upload's own check
+// (pipeline/job), so no way in passes a bigger one. The Go side's figure is
+// internal/archive MaxMathBytes (pack.test.mjs holds the two together).
+export const MAX_MATH_BYTES = 200 * 1024 * 1024;
+
+// The refusal of maths over MAX_MATH_BYTES, in the same words wherever it is
+// checked; the size is rounded up, so maths just over never reads as 200 MB.
+export const mathTooLarge = (bytes) => `The maths is ${Math.ceil((bytes * 10) / 1048576) / 10} MB; a pack's maths may be at most ${MAX_MATH_BYTES / 1048576} MB.`;
+
+// The bytes of the maths in dir: its files together (math/ holds nothing below them).
+export const mathBytes = (dir) => readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile()).reduce((n, e) => n + statSync(join(dir, e.name)).size, 0);
+
+/**
+ * What a meter adds to the RTP of every bet of its modes, exactly (GUIDE:
+ * Meters): E[award] ÷ fill, in basis points of the stake. `rows` are the
+ * award's outcomes, `pay` the multiplier of the reference in bp.
+ */
+export function meterRtp({ fill, rows }) {
+    const den = rows.reduce((s, r) => s + r.weight, 0n) * BigInt(fill);
+    const num = rows.reduce((s, r) => s + r.weight * BigInt(r.pay || 0), 0n);
+    return { num, den, bp: bp4(num, den) };
+}
+
 /**
  * Writes manifest.json and one table per mode. A mode is { id, label?, rows,
- * bets: [id | {id, label}] }; its rows are sorted by what the first bet pays,
+ * bets: [id | {id, label}], meter? }; its rows are sorted by what the first bet pays,
  * so each pay tier is one range. Prints every bet's exact RTP, hit rate and
  * largest multiplier; returns them.
+ *
+ * meters: [{ id, label?, fill, rows }] — progress that pays (GUIDE: Meters).
+ * A meter's rows are its award's outcomes, each { weight, pay, data? } with
+ * `pay` in bp of the meter's reference (20000 = twice the reference); a mode
+ * names the meter its rounds fill with `meter: id`. Every bet of such a mode
+ * reports base + meter RTP, and the base must clear 90% on its own.
  */
-export function writePack(dir, { game, rtpBp, modes }) {
-    mkdirSync(dir, { recursive: true });
+export function writePack(dir, { game, rtpBp, modes, meters = [] }) {
+    if (!Array.isArray(modes) || modes.length < 1 || modes.length > 64) throw new Error('a pack needs 1 to 64 modes');
+    for (const mode of modes) {
+        if (!Array.isArray(mode.bets) || mode.bets.length < 1 || mode.bets.length > 256) throw new Error(`${mode.id}: 1 to 256 bets per mode`);
+    }
     const manifest = { format: 'house-engine-math/1', game, rtpBp, modes: [] };
     const report = [];
+    const tables = new Map();
     for (const mode of modes) {
         const bets = mode.bets.map((b) => (typeof b === 'string' ? { id: b } : b));
         const first = bets[0].id;
@@ -141,25 +180,63 @@ export function writePack(dir, { game, rtpBp, modes }) {
         const lines = rows.map((r) => {
             if (r.weight <= 0n) throw new Error(`${mode.id}: a weight is not positive`);
             const json = r.data === undefined ? '' : JSON.stringify(r.data);
-            if (json.length > 4096) throw new Error(`${mode.id}: a row's data is over 4096 bytes`);
+            if (Buffer.byteLength(json) > 4096) throw new Error(`${mode.id}: a row's data is over 4096 UTF-8 bytes`);
             return json ? `${r.weight}\t${json}` : String(r.weight);
         });
         const table = `${game}-${mode.id}.tsv`;
-        writeFileSync(join(dir, table), lines.join('\n') + '\n');
+        tables.set(table, lines.join('\n') + '\n');
         manifest.modes.push({
-            id: mode.id, ...(mode.label ? { label: mode.label } : {}), kind: 'table', table,
+            id: mode.id, ...(mode.label ? { label: mode.label } : {}), kind: 'table', table, ...(mode.meter ? { meter: mode.meter } : {}),
             bets: bets.map((b) => {
                 const tiers = new Map();
                 rows.forEach((r, i) => { const m = r.pay[b.id] || 0; if (m > 0) (tiers.get(m) || tiers.set(m, []).get(m)).push(i); });
                 const { num, den, bp } = rtp(rows, b.id);
                 const hit = rows.reduce((s, r) => s + (r.pay[b.id] > 0 ? r.weight : 0n), 0n);
+                // The engine's verifier refuses a bet with more pay tiers than this (one tier per distinct
+                // multiplier): refused here, at the build, not at the upload (mathpack.MaxTiers).
+                if (tiers.size > MAX_TIERS) throw new Error(`${mode.id}: bet "${b.id}": ${tiers.size} distinct payouts (tiers), at most ${MAX_TIERS}: round the multipliers to fewer values`);
                 const max = Math.max(...tiers.keys());
-                report.push({ mode: mode.id, bet: b.id, rtp: bp, hit: bp4(hit * 10000n, den), max: max / 10000, rows: rows.length, exact: num % den === 0n });
+                const entry = { mode: mode.id, bet: b.id, rtp: bp, hit: bp4(hit * 10000n, den), max: max / 10000, rows: rows.length, exact: num % den === 0n };
+                if (mode.meter) {
+                    const mt = meters.find((x) => x.id === mode.meter);
+                    if (!mt) throw new Error(`${mode.id}: meter "${mode.meter}" is not in meters`);
+                    const add = meterRtp(mt);
+                    // base + E[award]/fill, as one exact fraction
+                    const tn = num * add.den + add.num * den, td = den * add.den;
+                    Object.assign(entry, { baseRtp: bp, meter: mode.meter, rtp: bp4(tn, td), exact: tn % td === 0n });
+                }
+                report.push(entry);
                 return { id: b.id, ...(b.label ? { label: b.label } : {}), tiers: [...tiers].map(([multBp, ids]) => ({ outcomes: ranges(ids), multBp })) };
             }),
         });
     }
-    writeFileSync(join(dir, 'manifest.json'), JSON.stringify(manifest) + '\n');
-    for (const r of report) console.log(`${r.mode}/${r.bet}: RTP ${r.rtp} bp  hit ${r.hit} bp  max ${r.max}×  rows ${r.rows}`);
+    for (const mt of meters) {
+        if (!Number.isSafeInteger(mt.fill) || mt.fill < 2 || mt.fill > 1_000_000) throw new Error(`meter ${mt.id}: fill must be 2 to 1,000,000`);
+        if (!modes.some((m) => m.meter === mt.id)) throw new Error(`meter ${mt.id}: no mode fills it`);
+        const rows = [...mt.rows].sort((a, b) => (a.pay || 0) - (b.pay || 0));
+        if (rows.length < 1) throw new Error(`meter ${mt.id}: an award needs rows`);
+        const table = `${game}-meter-${mt.id}.tsv`;
+        tables.set(table, rows.map((r) => {
+            if (r.weight <= 0n) throw new Error(`meter ${mt.id}: a weight is not positive`);
+            const json = r.data === undefined ? '' : JSON.stringify(r.data);
+            return json ? `${r.weight}\t${json}` : String(r.weight);
+        }).join('\n') + '\n');
+        const tiers = new Map();
+        rows.forEach((r, i) => { const m = r.pay || 0; if (m > 0) (tiers.get(m) || tiers.set(m, []).get(m)).push(i); });
+        if (!tiers.size) throw new Error(`meter ${mt.id}: the award never pays`);
+        (manifest.meters ||= []).push({ id: mt.id, ...(mt.label ? { label: mt.label } : {}), fill: mt.fill, table,
+            award: [...tiers].map(([multBp, ids]) => ({ outcomes: ranges(ids), multBp })) });
+        const ev = meterRtp({ fill: 1, rows });
+        console.log(`meter ${mt.id}: fill ${mt.fill}  award E ${bp4(ev.num, ev.den * 10000n)}× the reference  adds ${meterRtp({ fill: mt.fill, rows }).bp} bp`);
+    }
+    tables.set('manifest.json', JSON.stringify(manifest) + '\n');
+    // The pack as it will be on disk, with what else is in dir already (the
+    // generator, often), measured before a file is written.
+    mkdirSync(dir, { recursive: true });
+    const others = readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile() && !tables.has(e.name));
+    const bytes = [...tables.values()].reduce((n, text) => n + Buffer.byteLength(text), 0) + others.reduce((n, e) => n + statSync(join(dir, e.name)).size, 0);
+    if (bytes > MAX_MATH_BYTES) throw new Error(mathTooLarge(bytes));
+    for (const [name, text] of tables) writeFileSync(join(dir, name), text);
+    for (const r of report) console.log(`${r.mode}/${r.bet}: RTP ${r.rtp} bp${r.meter ? ` (base ${r.baseRtp} + meter ${r.meter})` : ''}  hit ${r.hit} bp  max ${r.max}×  rows ${r.rows}`);
     return report;
 }