hbengine 0.2.3

package/engine-examples/lines/bundle/i18n.json

@@ -0,0 +1,242 @@
+{
+ "en": {
+  "freeSpins": "Free spins {i} of {n}",
+  "winsTimes": "wins ×{x}",
+  "tapToSkip": "tap to skip",
+  "freePaid": "Free spins paid {w}",
+  "buyHint": "Free spins for {n} spins: the stake is the price",
+  "maxWin": "max win",
+  "modes": {
+   "base": "Spin",
+   "buy": "Buy free spins"
+  }
+ },
+ "ar": {
+  "freeSpins": "دورات مجانية {i} من {n}",
+  "winsTimes": "الأرباح ×{x}",
+  "tapToSkip": "اضغط للتخطي",
+  "freePaid": "دفعت الدورات المجانية {w}",
+  "buyHint": "دورات مجانية مقابل {n} دورة: الرهان هو السعر",
+  "maxWin": "أقصى ربح",
+  "modes": {
+   "base": "دوران",
+   "buy": "شراء الدورات المجانية"
+  }
+ },
+ "da": {
+  "freeSpins": "Gratis spins {i} af {n}",
+  "winsTimes": "gevinster ×{x}",
+  "tapToSkip": "tryk for at springe over",
+  "freePaid": "Gratis spins betalte {w}",
+  "buyHint": "Gratis spins for {n} spins: indsatsen er prisen",
+  "maxWin": "maks. gevinst",
+  "modes": {
+   "base": "Spin",
+   "buy": "Køb gratis spins"
+  }
+ },
+ "de": {
+  "freeSpins": "Freispiele {i} von {n}",
+  "winsTimes": "Gewinne ×{x}",
+  "tapToSkip": "zum Überspringen tippen",
+  "freePaid": "Freispiele zahlten {w}",
+  "buyHint": "Freispiele für {n} Spins: der Einsatz ist der Preis",
+  "maxWin": "Maximalgewinn",
+  "modes": {
+   "base": "Drehen",
+   "buy": "Freispiele kaufen"
+  }
+ },
+ "es": {
+  "freeSpins": "Giros gratis {i} de {n}",
+  "winsTimes": "premios ×{x}",
+  "tapToSkip": "toca para saltar",
+  "freePaid": "Los giros gratis pagaron {w}",
+  "buyHint": "Giros gratis por {n} giros: la apuesta es el precio",
+  "maxWin": "premio máximo",
+  "modes": {
+   "base": "Girar",
+   "buy": "Comprar giros gratis"
+  }
+ },
+ "fi": {
+  "freeSpins": "Ilmaiskierrokset {i}/{n}",
+  "winsTimes": "voitot ×{x}",
+  "tapToSkip": "ohita napauttamalla",
+  "freePaid": "Ilmaiskierrokset maksoivat {w}",
+  "buyHint": "Ilmaiskierrokset {n} kierroksen hinnalla: panos on hinta",
+  "maxWin": "maksimivoitto",
+  "modes": {
+   "base": "Pyöräytä",
+   "buy": "Osta ilmaiskierrokset"
+  }
+ },
+ "fr": {
+  "freeSpins": "Tours gratuits {i} sur {n}",
+  "winsTimes": "gains ×{x}",
+  "tapToSkip": "touchez pour passer",
+  "freePaid": "Les tours gratuits ont payé {w}",
+  "buyHint": "Tours gratuits pour {n} tours : la mise est le prix",
+  "maxWin": "gain maximal",
+  "modes": {
+   "base": "Lancer",
+   "buy": "Acheter les tours gratuits"
+  }
+ },
+ "hi": {
+  "freeSpins": "फ्री स्पिन {i} / {n}",
+  "winsTimes": "जीत ×{x}",
+  "tapToSkip": "छोड़ने के लिए टैप करें",
+  "freePaid": "फ्री स्पिन से {w} मिला",
+  "buyHint": "{n} स्पिन की कीमत पर फ्री स्पिन: दांव ही कीमत है",
+  "maxWin": "अधिकतम जीत",
+  "modes": {
+   "base": "स्पिन",
+   "buy": "फ्री स्पिन खरीदें"
+  }
+ },
+ "hu": {
+  "freeSpins": "Ingyenes pörgetés {i}/{n}",
+  "winsTimes": "nyeremények ×{x}",
+  "tapToSkip": "koppints az átugráshoz",
+  "freePaid": "Az ingyenes pörgetések {w} fizettek",
+  "buyHint": "Ingyenes pörgetések {n} pörgetés áráért: a tét az ár",
+  "maxWin": "max. nyeremény",
+  "modes": {
+   "base": "Pörgetés",
+   "buy": "Ingyenes pörgetések vásárlása"
+  }
+ },
+ "id": {
+  "freeSpins": "Putaran gratis {i} dari {n}",
+  "winsTimes": "kemenangan ×{x}",
+  "tapToSkip": "ketuk untuk lewati",
+  "freePaid": "Putaran gratis membayar {w}",
+  "buyHint": "Putaran gratis seharga {n} putaran: taruhan adalah harganya",
+  "maxWin": "kemenangan maks",
+  "modes": {
+   "base": "Putar",
+   "buy": "Beli putaran gratis"
+  }
+ },
+ "it": {
+  "freeSpins": "Giri gratis {i} di {n}",
+  "winsTimes": "vincite ×{x}",
+  "tapToSkip": "tocca per saltare",
+  "freePaid": "I giri gratis hanno pagato {w}",
+  "buyHint": "Giri gratis per {n} giri: la puntata è il prezzo",
+  "maxWin": "vincita massima",
+  "modes": {
+   "base": "Gira",
+   "buy": "Compra giri gratis"
+  }
+ },
+ "ja": {
+  "freeSpins": "フリースピン {i}/{n}",
+  "winsTimes": "配当 ×{x}",
+  "tapToSkip": "タップでスキップ",
+  "freePaid": "フリースピン配当 {w}",
+  "buyHint": "{n}スピン分でフリースピン購入：ベット額が価格です",
+  "maxWin": "最大配当",
+  "modes": {
+   "base": "スピン",
+   "buy": "フリースピン購入"
+  }
+ },
+ "ko": {
+  "freeSpins": "프리 스핀 {i}/{n}",
+  "winsTimes": "당첨 ×{x}",
+  "tapToSkip": "탭하여 건너뛰기",
+  "freePaid": "프리 스핀 당첨 {w}",
+  "buyHint": "{n}스핀 가격으로 프리 스핀: 베팅액이 가격입니다",
+  "maxWin": "최대 당첨",
+  "modes": {
+   "base": "스핀",
+   "buy": "프리 스핀 구매"
+  }
+ },
+ "pl": {
+  "freeSpins": "Darmowe spiny {i} z {n}",
+  "winsTimes": "wygrane ×{x}",
+  "tapToSkip": "dotknij, aby pominąć",
+  "freePaid": "Darmowe spiny wypłaciły {w}",
+  "buyHint": "Darmowe spiny za {n} spinów: stawka to cena",
+  "maxWin": "maks. wygrana",
+  "modes": {
+   "base": "Spin",
+   "buy": "Kup darmowe spiny"
+  }
+ },
+ "pt": {
+  "freeSpins": "Giros grátis {i} de {n}",
+  "winsTimes": "ganhos ×{x}",
+  "tapToSkip": "toque para pular",
+  "freePaid": "Os giros grátis pagaram {w}",
+  "buyHint": "Giros grátis por {n} giros: a aposta é o preço",
+  "maxWin": "ganho máximo",
+  "modes": {
+   "base": "Girar",
+   "buy": "Comprar giros grátis"
+  }
+ },
+ "ru": {
+  "freeSpins": "Бесплатные вращения {i} из {n}",
+  "winsTimes": "выигрыши ×{x}",
+  "tapToSkip": "нажмите, чтобы пропустить",
+  "freePaid": "Бесплатные вращения принесли {w}",
+  "buyHint": "Бесплатные вращения за {n} спинов: ставка — это цена",
+  "maxWin": "максимальный выигрыш",
+  "modes": {
+   "base": "Вращение",
+   "buy": "Купить бесплатные вращения"
+  }
+ },
+ "th": {
+  "freeSpins": "ฟรีสปิน {i} จาก {n}",
+  "winsTimes": "รางวัล ×{x}",
+  "tapToSkip": "แตะเพื่อข้าม",
+  "freePaid": "ฟรีสปินจ่าย {w}",
+  "buyHint": "ฟรีสปินในราคา {n} สปิน: เงินเดิมพันคือราคา",
+  "maxWin": "รางวัลสูงสุด",
+  "modes": {
+   "base": "หมุน",
+   "buy": "ซื้อฟรีสปิน"
+  }
+ },
+ "tr": {
+  "freeSpins": "Bedava dönüş {i}/{n}",
+  "winsTimes": "kazançlar ×{x}",
+  "tapToSkip": "geçmek için dokun",
+  "freePaid": "Bedava dönüşler {w} ödedi",
+  "buyHint": "{n} dönüş fiyatına bedava dönüşler: bahis fiyattır",
+  "maxWin": "maksimum kazanç",
+  "modes": {
+   "base": "Çevir",
+   "buy": "Bedava dönüş satın al"
+  }
+ },
+ "vi": {
+  "freeSpins": "Lượt quay miễn phí {i}/{n}",
+  "winsTimes": "thắng ×{x}",
+  "tapToSkip": "chạm để bỏ qua",
+  "freePaid": "Lượt quay miễn phí trả {w}",
+  "buyHint": "Lượt quay miễn phí với giá {n} lượt: tiền cược là giá",
+  "maxWin": "thắng tối đa",
+  "modes": {
+   "base": "Quay",
+   "buy": "Mua lượt quay miễn phí"
+  }
+ },
+ "zh": {
+  "freeSpins": "免费旋转 {i}/{n}",
+  "winsTimes": "奖金 ×{x}",
+  "tapToSkip": "点击跳过",
+  "freePaid": "免费旋转赢得 {w}",
+  "buyHint": "以 {n} 次旋转的价格购买免费旋转：投注额即价格",
+  "maxWin": "最高奖金",
+  "modes": {
+   "base": "旋转",
+   "buy": "购买免费旋转"
+  }
+ }
+}

package/engine-examples/lines/bundle/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>Lines</title>
+<link rel="stylesheet" href="./game.css">
+<script type="module" src="/engine-sdk/bet-field.js"></script>
+<script type="module" src="./game.js"></script>
+</head>
+<body>
+<hb-game id="game">
+  <div slot="zone" class="slot" id="slot">
+    <div class="banner" id="banner" aria-live="polite"></div>
+    <div class="board">
+      <div class="reels" id="reels"></div>
+      <svg class="lines" id="lines" aria-hidden="true"></svg>
+    </div>
+    <div class="win" id="win" aria-live="polite"></div>
+  </div>
+</hb-game>
+</body>
+</html>

package/engine-examples/lines/bundle/model.json

@@ -0,0 +1 @@
+{"rows":3,"reels":[["K","A","J","seven","J","J","S","Q","Q","J","Q","gem","W","J","Q","K","Q","seven","bell","bell","star","A","K","star","J","K","A","bell","A","A","K","Q","W","star","gem"],["J","W","Q","J","seven","S","Q","A","K","W","star","bell","K","star","Q","K","J","K","bell","A","A","Q","Q","J","seven","K","star","gem","A","A","bell","gem","J","J","Q"],["bell","gem","A","K","star","seven","Q","bell","seven","Q","Q","star","star","W","A","W","Q","A","A","K","J","Q","K","bell","A","gem","S","K","J","J","K","J","J","J","Q"],["Q","K","bell","Q","gem","J","star","Q","gem","K","seven","bell","star","bell","J","A","A","W","A","J","K","K","J","S","J","A","A","J","star","Q","K","Q","Q","W","seven"],["Q","K","Q","J","J","A","W","Q","Q","star","J","Q","K","J","Q","bell","A","seven","K","A","K","bell","seven","K","A","A","star","gem","J","J","star","W","S","gem","bell"]],"freeReels":[["K","A","K","Q","bell","gem","J","J","bell","gem","star","star","J","J","bell","J","star","Q","W","K","Q","seven","A","Q","Q","A","Q","seven","K","A","W","S","W","A","J","K"],["A","Q","gem","Q","J","Q","bell","star","star","Q","S","gem","J","A","K","J","W","Q","star","seven","K","bell","A","A","K","W","Q","K","A","K","seven","J","bell","W","J","J"],["K","Q","seven","A","J","W","star","J","W","Q","K","seven","S","A","K","K","bell","gem","A","K","bell","A","bell","Q","J","star","Q","star","gem","Q","J","J","A","J","Q","W"],["A","K","J","star","Q","A","W","K","Q","gem","J","K","star","J","A","J","A","bell","seven","W","A","bell","K","Q","Q","star","W","K","S","seven","J","Q","bell","gem","J","Q"],["bell","J","A","gem","A","seven","J","Q","W","J","star","W","bell","W","K","J","A","K","A","K","Q","Q","K","seven","J","star","bell","Q","gem","A","K","S","J","Q","Q","star"]],"lines":[[1,1,1,1,1],[0,0,0,0,0],[2,2,2,2,2],[0,1,2,1,0],[2,1,0,1,2],[0,0,1,2,2],[2,2,1,0,0],[1,0,0,0,1],[1,2,2,2,1],[1,0,1,2,1]],"pays":{"seven":{"3":40000,"4":160000,"5":800000},"gem":{"3":32000,"4":120000,"5":480000},"star":{"3":24000,"4":80000,"5":320000},"bell":{"3":16000,"4":64000,"5":200000},"A":{"3":8000,"4":32000,"5":120000},"K":{"3":6400,"4":24000,"5":96000},"Q":{"3":4800,"4":20000,"5":80000},"J":{"3":4000,"4":16000,"5":64000},"W":{"3":80000,"4":400000,"5":1600000}},"wild":"W","scatter":{"symbol":"S","pays":{"3":20000,"4":100000,"5":500000},"spins":{"3":10,"4":12,"5":15},"retrigger":{"3":5,"4":5,"5":5},"multiplier":2,"cap":60},"maxWinBp":50000000,"price":27}

package/engine-examples/lines/math/gen.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// The lines slot's maths: five reels, ten lines, a wild, a scatter that
+// starts ten free spins at 2× (retriggers +5), a 5,000× cap. The maths kit
+// plays 400,000 rounds into rows and fits the table to exactly 96.00%. The
+// reels, lines and pays go to the bundle too, so the page draws what pays.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { balance, fit, rng, writePack } from '../math-kit/pack.mjs';
+import { books, slot } from '../math-kit/slot.mjs';
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+const project = join(DIR, '..', 'hbengine.json');
+const GAME = process.argv[2] || (existsSync(project) ? JSON.parse(readFileSync(project, 'utf8')).slug : 'lines'), RTP = 9600, ROUNDS = Number(process.env.ROUNDS || 400_000), SEED = 20261015;
+
+// One strip per reel: symbols repeated by weight.
+const strip = (w) => Object.entries(w).flatMap(([s, n]) => Array(n).fill(s));
+const shuffle = (a, next) => { for (let i = a.length - 1; i > 0; i--) { const j = next.int(i + 1); [a[i], a[j]] = [a[j], a[i]]; } return a; };
+const weights = { gem: 2, star: 3, bell: 3, seven: 2, A: 5, K: 5, Q: 6, J: 6, W: 2, S: 1 };
+const freeWeights = { ...weights, W: 3 };
+const order = rng(7);
+const model = {
+    rows: 3,
+    reels: [0, 1, 2, 3, 4].map(() => shuffle(strip(weights), order)),
+    freeReels: [0, 1, 2, 3, 4].map(() => shuffle(strip(freeWeights), order)),
+    lines: [[1, 1, 1, 1, 1], [0, 0, 0, 0, 0], [2, 2, 2, 2, 2], [0, 1, 2, 1, 0], [2, 1, 0, 1, 2], [0, 0, 1, 2, 2], [2, 2, 1, 0, 0], [1, 0, 0, 0, 1], [1, 2, 2, 2, 1], [1, 0, 1, 2, 1]],
+    // line pays for 3, 4, 5 in units of 0.08× the stake; scatters (below) in basis points of the stake
+    pays: Object.fromEntries(Object.entries({
+        seven: [50, 200, 1000], gem: [40, 150, 600], star: [30, 100, 400], bell: [20, 80, 250],
+        A: [10, 40, 150], K: [8, 30, 120], Q: [6, 25, 100], J: [5, 20, 80], W: [100, 500, 2000],
+    }).map(([s, [a, b, c]]) => [s, { 3: a * 800, 4: b * 800, 5: c * 800 }])),
+    wild: 'W',
+    scatter: { symbol: 'S', pays: { 3: 20000, 4: 100000, 5: 500000 }, spins: { 3: 10, 4: 12, 5: 15 }, retrigger: { 3: 5, 4: 5, 5: 5 }, multiplier: 2, cap: 60 },
+    maxWinBp: 50_000_000,
+};
+
+const rows = books(slot(model), rng(SEED), ROUNDS);
+const raw = rows.reduce((a, r) => [a[0] + r.weight * BigInt(r.pay.spin), a[1] + r.weight], [0n, 0n]);
+const hits = rows.reduce((a, r) => a + (r.pay.spin > 0 ? r.weight : 0n), 0n);
+console.log(`played ${ROUNDS}: before the fit RTP ${(Number(raw[0] * 1000000n / raw[1]) / 1e6 / 100).toFixed(2)}%, hit rate ${(Number(hits * 10000n / BigInt(ROUNDS)) / 100).toFixed(2)}%`);
+// Bonus buy: the free spins alone. The stake is the price; the price is what
+// the free spins return on average over the target, in whole spins, so the
+// balance to exactly 96.00% only nudges. A bought round pays its free
+// spins' win per stake, rounded down to the basis point.
+const freeRounds = books(slot(model), rng(SEED + 1), ROUNDS / 8, 4000, true);
+const mean = freeRounds.reduce((a, r) => [a[0] + r.weight * BigInt(r.pay.spin), a[1] + r.weight], [0n, 0n]);
+const PRICE = Math.round(Number(mean[0] / mean[1]) / RTP);
+const bought = freeRounds.map((r) => ({ ...r, pay: { buy: Math.floor(r.pay.spin / PRICE) } }));
+console.log(`free spins return ${(Number(mean[0] / mean[1]) / 10000).toFixed(2)} spins on average: the buy costs ${PRICE} spins`);
+writePack(join(DIR), { game: GAME, rtpBp: RTP, modes: [
+    { id: 'base', label: 'Spin', rows: fit(rows, RTP), bets: [{ id: 'spin', label: 'Spin' }] },
+    { id: 'buy', label: `Buy free spins (${PRICE}×)`, rows: balance(bought, RTP), bets: [{ id: 'buy', label: 'Buy' }] },
+] });
+writeFileSync(join(DIR, '..', 'bundle', 'model.json'), JSON.stringify({ ...model, price: PRICE }) + '\n');

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

@@ -0,0 +1,165 @@
+/**
+ * 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, 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;
+}
+
+/**
+ * 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,
+ * so each pay tier is one range. Prints every bet's exact RTP, hit rate and
+ * largest multiplier; returns them.
+ */
+export function writePack(dir, { game, rtpBp, modes }) {
+    mkdirSync(dir, { recursive: true });
+    const manifest = { format: 'house-engine-math/1', game, rtpBp, modes: [] };
+    const report = [];
+    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 (json.length > 4096) throw new Error(`${mode.id}: a row's data is over 4096 bytes`);
+            return json ? `${r.weight}\t${json}` : String(r.weight);
+        });
+        const table = `${game}-${mode.id}.tsv`;
+        writeFileSync(join(dir, table), lines.join('\n') + '\n');
+        manifest.modes.push({
+            id: mode.id, ...(mode.label ? { label: mode.label } : {}), kind: 'table', table,
+            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);
+                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 });
+                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}`);
+    return report;
+}

package/engine-examples/lines/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/lines/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()];
+}