hbengine 0.2.3 → 0.4.0

package/engine-examples/lines/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;
 }

package/engine-examples/plinko/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;
 }

package/engine-examples/plinko-jar/AGENTS.md

@@ -0,0 +1,3 @@
+# For agents
+
+This is a House Engine game (Housebets). Read the guide first: `engine_guide` (MCP) or `engine-sdk/GUIDE.md`. Then `hbengine verify`, `hbengine dev`, `hbengine upload` (or the `engine_*` tools). The math is `math/`, the frontend `bundle/`; never compute money or outcomes in the frontend.

package/engine-examples/plinko-jar/README.md

@@ -0,0 +1,16 @@
+# Plinko with a jar — a meter that pays
+
+The plinko board with a **jar** (a House Engine meter, GUIDE §2.2). Every drop
+pours its stake into the jar; the jar is full after 200 × its reference stake
+(the stake of the drop that started it) and the drop that fills it also pays
+2×, 5×, 10×, 25× or 50× the reference (8× on average). The server keeps the jar
+per player and coin, in the same transaction as each drop: nothing in the page
+can change it, and it is there again on any device.
+
+RTP: each bet is its base (≈ 95%) + 8 / 200 = 4% from the jar, exactly; the
+verifier checks both, and the base alone stays above 90%.
+
+    node math/gen.mjs && npx hbengine verify .
+
+The page reads the jar with `engine.meters()` at boot and `round.meter` after
+each drop; `round.payout` already includes the jar's bonus.

package/engine-examples/plinko-jar/bundle/assets.json

@@ -0,0 +1 @@
+{ "groups": { "boot": { "files": ["index.html", "game.js", "game.css", "model.json"] } } }

package/engine-examples/plinko-jar/bundle/game.css

@@ -0,0 +1,10 @@
+body { margin: 0; background: #08141a; }
+.plinko { position: relative; width: 100%; height: 100%; min-height: 360px; display: grid; place-items: center; padding: 12px; box-sizing: border-box; }
+canvas { display: block; }
+.last { position: absolute; top: 12px; right: 14px; font: 700 15px/20px 'Red Hat Display', 'Figtree', system-ui, sans-serif; color: #8F96A8; font-variant-numeric: tabular-nums; }
+.last.win { color: #FDDC73; }
+.jar { position: absolute; top: 12px; left: 14px; display: grid; justify-items: center; gap: 4px; }
+.jar-glass { width: 30px; height: 64px; border: 2px solid #5b6b78; border-radius: 6px 6px 10px 10px; overflow: hidden; display: flex; align-items: flex-end; background: #0D2A38; }
+.jar-fill { width: 100%; height: 0; background: linear-gradient(#FDDC73, #c99a2e); transition: height .4s ease; }
+.jar.full .jar-glass { border-color: #FDDC73; box-shadow: 0 0 14px #FDDC7399; }
+.jar-text { font: 700 12px/16px 'Red Hat Display', 'Figtree', system-ui, sans-serif; color: #8F96A8; font-variant-numeric: tabular-nums; }

package/engine-examples/plinko-jar/bundle/game.js

@@ -0,0 +1,113 @@
+// Plinko with a jar (GUIDE §2.2, meters): the board is the plinko template's;
+// the jar is a meter the server keeps. Every drop pours its stake in; the drop
+// that fills it also pays the jar's bonus, already in its payout. The page
+// only shows the jar: engine.meters() at boot, round.meter after each drop.
+import { mount } from '/engine-sdk/ui.js';
+
+const board = await (await fetch('./model.json')).json();
+const el = document.getElementById('game'), zone = document.getElementById('zone'), last = document.getElementById('last');
+const canvas = document.getElementById('board'), ctx = canvas.getContext('2d');
+const jar = document.getElementById('jar'), jarFill = document.getElementById('jar-fill'), jarText = document.getElementById('jar-text');
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+let mode = Object.keys(board)[0], ball = null, lit = -1, size = { w: 0, h: 0, gap: 0 };
+
+// Bucket colours: deep tones by how far from the centre (the big shapes stay muted).
+const tone = (k, n) => { const d = Math.abs(k - n / 2) / (n / 2); return d > 0.85 ? '#7e1f3a' : d > 0.55 ? '#7d5410' : d > 0.25 ? '#0d5f6e' : '#0D2A38'; };
+// Every multiplier is a whole 0.001×: shown exactly, trailing zeros dropped.
+const label = (bp) => String(bp / 10000) + '×';
+
+function layout() {
+    const n = board[mode].length - 1, dpr = devicePixelRatio || 1;
+    const w = Math.min(zone.clientWidth - 24, 640), h = Math.min(zone.clientHeight - 24, w * 0.95);
+    const gap = Math.min(w / (n + 2), h / (n + 2.4));
+    size = { w: gap * (n + 2), h: gap * (n + 2.4), gap, n };
+    canvas.width = size.w * dpr; canvas.height = size.h * dpr;
+    canvas.style.width = size.w + 'px'; canvas.style.height = size.h + 'px';
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    draw();
+}
+const peg = (row, i) => ({ x: size.w / 2 + (i - row / 2) * size.gap, y: size.gap * (0.9 + row) });
+
+function draw() {
+    const { w, h, gap, n } = size, pays = board[mode];
+    ctx.clearRect(0, 0, w, h);
+    ctx.fillStyle = '#5b6b78';
+    for (let r = 1; r <= n; r++) for (let i = 0; i <= r; i++) { const p = peg(r, i); ctx.beginPath(); ctx.arc(p.x, p.y, Math.max(2, gap * 0.09), 0, 7); ctx.fill(); }
+    const by = gap * (n + 1.25), bh = gap * 0.85;
+    ctx.font = `700 ${Math.max(9, Math.min(13, gap * 0.34))}px 'Red Hat Display', Figtree, system-ui, sans-serif`;
+    ctx.textAlign = 'center'; ctx.textBaseline = 'middle';
+    pays.forEach((bp, k) => {
+        const x = size.w / 2 + (k - n / 2) * gap;
+        ctx.fillStyle = tone(k, n);
+        ctx.beginPath(); ctx.roundRect(x - gap * 0.46, by, gap * 0.92, bh, 5); ctx.fill();
+        if (k === lit) { ctx.strokeStyle = '#FDDC73'; ctx.lineWidth = 2; ctx.stroke(); }
+        ctx.fillStyle = '#F9F9FB';
+        ctx.fillText(label(bp), x, by + bh / 2);
+    });
+    if (ball) { ctx.fillStyle = '#F9F9FB'; ctx.beginPath(); ctx.arc(ball.x, ball.y, gap * 0.2, 0, 7); ctx.fill(); }
+}
+
+// Which of the n steps go right: k of them, shuffled by the round's nonce.
+function path(n, k, seed) {
+    const steps = Array.from({ length: n }, (_, i) => i < k);
+    let s = (seed >>> 0) || 1;
+    for (let i = n - 1; i > 0; i--) { s ^= s << 13; s ^= s >>> 17; s ^= s << 5; const j = (s >>> 0) % (i + 1); [steps[i], steps[j]] = [steps[j], steps[i]]; }
+    return steps;
+}
+
+function fall(steps) {
+    const { gap } = size;
+    const points = [{ x: size.w / 2, y: gap * 0.1 }];
+    let i = 0;
+    steps.forEach((right, r) => { if (right) i++; const p = peg(r + 1, i); points.push({ x: p.x + (right ? -0.5 : 0.5) * gap, y: p.y - gap * 0.35 }); });
+    const end = size.w / 2 + (i - steps.length / 2) * gap;
+    points.push({ x: end, y: gap * (steps.length + 1.6) });
+    const per = 90, total = per * (points.length - 1);
+    return new Promise((done) => {
+        const t0 = performance.now();
+        const frame = (t) => {
+            const f = Math.min(1, (t - t0) / total), seg = Math.min(points.length - 2, Math.floor(f * (points.length - 1))), u = f * (points.length - 1) - seg;
+            const a = points[seg], b = points[seg + 1];
+            ball = { x: a.x + (b.x - a.x) * u, y: a.y + (b.y - a.y) * u - Math.sin(u * Math.PI) * gap * 0.25 };
+            draw();
+            if (f < 1) requestAnimationFrame(frame); else done();
+        };
+        requestAnimationFrame(frame);
+    });
+}
+
+// The jar, from the server's figures: filled ÷ target (target 0: empty).
+function showJar(v) {
+    const f = Number(v.filled), t = Number(v.target), pct = t > 0 ? Math.min(100, (f / t) * 100) : 0;
+    jarFill.style.height = pct + '%';
+    jar.setAttribute('aria-valuenow', String(Math.round(pct)));
+    jarText.textContent = 'Jar ' + Math.floor(pct) + '%';
+}
+
+const game = await mount(el, {
+    async reveal(round) {
+        const k = round.data[0].k, n = size.n;
+        lit = -1; last.textContent = ''; last.classList.remove('win');
+        await fall(path(n, k, Number(round.nonce) || round.id?.length || 1));
+        ball = null; lit = k; draw();
+        last.textContent = label(board[mode][k]);
+        last.classList.toggle('win', round.payout > 0 && board[mode][k] >= 10000);
+        const m = round.meter;
+        if (m && m.award) {
+            // Full: the jar pays x × its reference stake on this drop.
+            showJar({ filled: 1, target: 1 });
+            jar.classList.add('full');
+            last.textContent += ' + jar ' + m.award.data.x + '× ' + game.engine.money.format(m.award.reference);
+            last.classList.add('win');
+            await wait(1200);
+            jar.classList.remove('full');
+        }
+        if (m) showJar(m.after);
+        await wait(150);
+    },
+});
+for (const m of await game.engine.meters()) if (m.id === 'jar') showJar(m);
+mode = game.mode;
+new ResizeObserver(layout).observe(zone);
+layout();
+el.addEventListener('select', (e) => { if (e.detail.mode !== mode) { mode = e.detail.mode; lit = -1; layout(); } });

package/engine-examples/plinko-jar/bundle/hbtest.json

@@ -0,0 +1,4 @@
+{
+  "stake": { "page": "index.html", "selector": "hb-game hb-bet-amount input", "value": "1.00" },
+  "bet": { "page": "index.html", "selector": "hb-game [data-main]" }
+}

package/engine-examples/plinko-jar/bundle/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>Plinko jar</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="plinko" id="zone"><canvas id="board" aria-label="Plinko board"></canvas><div class="jar" id="jar" role="meter" aria-label="Jar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0"><div class="jar-glass"><div class="jar-fill" id="jar-fill"></div></div><div class="jar-text" id="jar-text">Jar 0%</div></div><div class="last" id="last" aria-live="polite"></div></div>
+</hb-game>
+</body>
+</html>

package/engine-examples/plinko-jar/bundle/model.json

@@ -0,0 +1 @@
+{"8-low":[55000,21000,11000,10000,3570,10000,11000,21000,55000],"8-medium":[130000,30000,13000,7000,2570,7000,13000,30000,130000],"8-high":[290000,40000,15000,3000,510,3000,15000,40000,290000],"12-low":[100000,30000,16000,14000,11000,10000,3230,10000,11000,14000,16000,30000,100000],"12-medium":[330000,110000,40000,20000,11000,6000,1230,6000,11000,20000,40000,110000,330000],"12-high":[1700000,240000,81000,20000,7000,2000,170,2000,7000,20000,81000,240000,1700000],"16-low":[160000,90000,20000,14000,14000,12000,11000,10000,2960,10000,11000,12000,14000,14000,20000,90000,160000],"16-medium":[1100000,410000,100000,50000,30000,15000,10000,5000,960,5000,10000,15000,30000,50000,100000,410000,1100000],"16-high":[10000000,1200000,220000,80000,35000,15000,2000,2000,6640,2000,2000,15000,35000,80000,220000,1200000,10000000]}

package/engine-examples/plinko-jar/math/gen.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Plinko with a jar: a meter (GUIDE §2.2) that fills with the stakes and,
+// when full, pays a bonus on the drop that fills it.
+//
+// The board is the plinko template's, its centre multiplier solved for 95%
+// (rounded down to 0.001×, so each mode lands just under). The jar is one
+// meter shared by all nine modes: it is full after 200 × its reference stake
+// (the stake of the drop that started it) and then pays 2×, 5×, 10×, 25× or
+// 50× the reference, 8× on average: 8 / 200 = 4% on top of every bet. Every
+// bet is 95% + 4% ≈ 99%, and a player who never fills the jar has a 95% game.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { binomial, writePack } from '../math-kit/pack.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 : 'plinko-jar');
+const BASE = 9500n;
+const EDGES = {
+    8: { low: [5.5, 2.1, 1.1, 1], medium: [13, 3, 1.3, 0.7], high: [29, 4, 1.5, 0.3] },
+    12: { low: [10, 3, 1.6, 1.4, 1.1, 1], medium: [33, 11, 4, 2, 1.1, 0.6], high: [170, 24, 8.1, 2, 0.7, 0.2] },
+    16: { low: [16, 9, 2, 1.4, 1.4, 1.2, 1.1, 1], medium: [110, 41, 10, 5, 3, 1.5, 1, 0.5], high: [1000, 120, 22, 8, 3.5, 1.5, 0.2, 0.2] },
+};
+// The jar's award: [multiple of the reference, weight]; E = 8×.
+const JAR = [[2, 50], [5, 20], [10, 20], [25, 4], [50, 6]];
+const FILL = 200;
+
+const modes = [], board = {};
+for (const [n, risks] of Object.entries(EDGES)) for (const [risk, edge] of Object.entries(risks)) {
+    const rows = Number(n), c = rows / 2;
+    const bp = edge.map((x) => BigInt(Math.round(x * 10000)));
+    const pays = [...bp, 0n, ...[...bp].reverse()];
+    const total = 1n << BigInt(rows);
+    const rest = pays.reduce((s, m, k) => s + binomial(rows, k) * m, 0n);
+    const centre = ((BASE * total - rest) / binomial(rows, c) / 10n) * 10n;
+    if (centre <= 0n) throw new Error(`${n}-${risk}: the edges alone pay over 95%`);
+    pays[c] = centre;
+    board[`${n}-${risk}`] = pays.map(Number);
+    modes.push({
+        id: `${n}-${risk}`, label: `${n} rows · ${risk}`, meter: 'jar', bets: [{ id: 'drop', label: 'Drop' }],
+        rows: pays.map((m, k) => ({ weight: binomial(rows, k), data: { k }, pay: { drop: Number(m) } })),
+    });
+}
+const meters = [{ id: 'jar', label: 'Jar', fill: FILL, rows: JAR.map(([x, w]) => ({ weight: BigInt(w), data: { x }, pay: x * 10000 })) }];
+writePack(DIR, { game: GAME, rtpBp: 9900, modes, meters });
+writeFileSync(join(DIR, '..', 'bundle', 'model.json'), JSON.stringify(board) + '\n');

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

@@ -0,0 +1 @@
+{"format":"house-engine-math/1","game":"plinko-jar","rtpBp":9900,"modes":[{"id":"8-low","label":"8 rows · low","kind":"table","table":"plinko-jar-8-low.tsv","meter":"jar","bets":[{"id":"drop","label":"Drop","tiers":[{"outcomes":[[0,0]],"multBp":3570},{"outcomes":[[1,2]],"multBp":10000},{"outcomes":[[3,4]],"multBp":11000},{"outcomes":[[5,6]],"multBp":21000},{"outcomes":[[7,8]],"multBp":55000}]}]},{"id":"8-medium","label":"8 rows · medium","kind":"table","table":"plinko-jar-8-medium.tsv","meter":"jar","bets":[{"id":"drop","label":"Drop","tiers":[{"outcomes":[[0,0]],"multBp":2570},{"outcomes":[[1,2]],"multBp":7000},{"outcomes":[[3,4]],"multBp":13000},{"outcomes":[[5,6]],"multBp":30000},{"outcomes":[[7,8]],"multBp":130000}]}]},{"id":"8-high","label":"8 rows · high","kind":"table","table":"plinko-jar-8-high.tsv","meter":"jar","bets":[{"id":"drop","label":"Drop","tiers":[{"outcomes":[[0,0]],"multBp":510},{"outcomes":[[1,2]],"multBp":3000},{"outcomes":[[3,4]],"multBp":15000},{"outcomes":[[5,6]],"multBp":40000},{"outcomes":[[7,8]],"multBp":290000}]}]},{"id":"12-low","label":"12 rows · low","kind":"table","table":"plinko-jar-12-low.tsv","meter":"jar","bets":[{"id":"drop","label":"Drop","tiers":[{"outcomes":[[0,0]],"multBp":3230},{"outcomes":[[1,2]],"multBp":10000},{"outcomes":[[3,4]],"multBp":11000},{"outcomes":[[5,6]],"multBp":14000},{"outcomes":[[7,8]],"multBp":16000},{"outcomes":[[9,10]],"multBp":30000},{"outcomes":[[11,12]],"multBp":100000}]}]},{"id":"12-medium","label":"12 rows · medium","kind":"table","table":"plinko-jar-12-medium.tsv","meter":"jar","bets":[{"id":"drop","label":"Drop","tiers":[{"outcomes":[[0,0]],"multBp":1230},{"outcomes":[[1,2]],"multBp":6000},{"outcomes":[[3,4]],"multBp":11000},{"outcomes":[[5,6]],"multBp":20000},{"outcomes":[[7,8]],"multBp":40000},{"outcomes":[[9,10]],"multBp":110000},{"outcomes":[[11,12]],"multBp":330000}]}]},{"id":"12-high","label":"12 rows · high","kind":"table","table":"plinko-jar-12-high.tsv","meter":"jar","bets":[{"id":"drop","label":"Drop","tiers":[{"outcomes":[[0,0]],"multBp":170},{"outcomes":[[1,2]],"multBp":2000},{"outcomes":[[3,4]],"multBp":7000},{"outcomes":[[5,6]],"multBp":20000},{"outcomes":[[7,8]],"multBp":81000},{"outcomes":[[9,10]],"multBp":240000},{"outcomes":[[11,12]],"multBp":1700000}]}]},{"id":"16-low","label":"16 rows · low","kind":"table","table":"plinko-jar-16-low.tsv","meter":"jar","bets":[{"id":"drop","label":"Drop","tiers":[{"outcomes":[[0,0]],"multBp":2960},{"outcomes":[[1,2]],"multBp":10000},{"outcomes":[[3,4]],"multBp":11000},{"outcomes":[[5,6]],"multBp":12000},{"outcomes":[[7,10]],"multBp":14000},{"outcomes":[[11,12]],"multBp":20000},{"outcomes":[[13,14]],"multBp":90000},{"outcomes":[[15,16]],"multBp":160000}]}]},{"id":"16-medium","label":"16 rows · medium","kind":"table","table":"plinko-jar-16-medium.tsv","meter":"jar","bets":[{"id":"drop","label":"Drop","tiers":[{"outcomes":[[0,0]],"multBp":960},{"outcomes":[[1,2]],"multBp":5000},{"outcomes":[[3,4]],"multBp":10000},{"outcomes":[[5,6]],"multBp":15000},{"outcomes":[[7,8]],"multBp":30000},{"outcomes":[[9,10]],"multBp":50000},{"outcomes":[[11,12]],"multBp":100000},{"outcomes":[[13,14]],"multBp":410000},{"outcomes":[[15,16]],"multBp":1100000}]}]},{"id":"16-high","label":"16 rows · high","kind":"table","table":"plinko-jar-16-high.tsv","meter":"jar","bets":[{"id":"drop","label":"Drop","tiers":[{"outcomes":[[0,3]],"multBp":2000},{"outcomes":[[4,4]],"multBp":6640},{"outcomes":[[5,6]],"multBp":15000},{"outcomes":[[7,8]],"multBp":35000},{"outcomes":[[9,10]],"multBp":80000},{"outcomes":[[11,12]],"multBp":220000},{"outcomes":[[13,14]],"multBp":1200000},{"outcomes":[[15,16]],"multBp":10000000}]}]}],"meters":[{"id":"jar","label":"Jar","fill":200,"table":"plinko-jar-meter-jar.tsv","award":[{"outcomes":[[0,0]],"multBp":20000},{"outcomes":[[1,1]],"multBp":50000},{"outcomes":[[2,2]],"multBp":100000},{"outcomes":[[3,3]],"multBp":250000},{"outcomes":[[4,4]],"multBp":500000}]}]}

package/engine-examples/plinko-jar/math/plinko-jar-12-high.tsv

@@ -0,0 +1,13 @@
+924	{"k":6}
+792	{"k":5}
+792	{"k":7}
+495	{"k":4}
+495	{"k":8}
+220	{"k":3}
+220	{"k":9}
+66	{"k":2}
+66	{"k":10}
+12	{"k":1}
+12	{"k":11}
+1	{"k":0}
+1	{"k":12}

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

@@ -0,0 +1,13 @@
+924	{"k":6}
+792	{"k":5}
+792	{"k":7}
+495	{"k":4}
+495	{"k":8}
+220	{"k":3}
+220	{"k":9}
+66	{"k":2}
+66	{"k":10}
+12	{"k":1}
+12	{"k":11}
+1	{"k":0}
+1	{"k":12}

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

@@ -0,0 +1,13 @@
+924	{"k":6}
+792	{"k":5}
+792	{"k":7}
+495	{"k":4}
+495	{"k":8}
+220	{"k":3}
+220	{"k":9}
+66	{"k":2}
+66	{"k":10}
+12	{"k":1}
+12	{"k":11}
+1	{"k":0}
+1	{"k":12}

package/engine-examples/plinko-jar/math/plinko-jar-16-high.tsv

@@ -0,0 +1,17 @@
+8008	{"k":6}
+11440	{"k":7}
+11440	{"k":9}
+8008	{"k":10}
+12870	{"k":8}
+4368	{"k":5}
+4368	{"k":11}
+1820	{"k":4}
+1820	{"k":12}
+560	{"k":3}
+560	{"k":13}
+120	{"k":2}
+120	{"k":14}
+16	{"k":1}
+16	{"k":15}
+1	{"k":0}
+1	{"k":16}

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

@@ -0,0 +1,17 @@
+12870	{"k":8}
+11440	{"k":7}
+11440	{"k":9}
+8008	{"k":6}
+8008	{"k":10}
+4368	{"k":5}
+4368	{"k":11}
+560	{"k":3}
+1820	{"k":4}
+1820	{"k":12}
+560	{"k":13}
+120	{"k":2}
+120	{"k":14}
+16	{"k":1}
+16	{"k":15}
+1	{"k":0}
+1	{"k":16}

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

@@ -0,0 +1,17 @@
+12870	{"k":8}
+11440	{"k":7}
+11440	{"k":9}
+8008	{"k":6}
+8008	{"k":10}
+4368	{"k":5}
+4368	{"k":11}
+1820	{"k":4}
+1820	{"k":12}
+560	{"k":3}
+560	{"k":13}
+120	{"k":2}
+120	{"k":14}
+16	{"k":1}
+16	{"k":15}
+1	{"k":0}
+1	{"k":16}

package/engine-examples/plinko-jar/math/plinko-jar-8-high.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}