hbengine 0.2.3 → 0.4.0

package/engine-math/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-mcp/server.mjs

@@ -4,7 +4,8 @@
  * (Claude Code, Cursor, …) builds, verifies and ships a studio game without
  * leaving its editor. Stdio JSON-RPC, the Model Context Protocol 2024-11-05
  * subset every client speaks: initialize, tools/list, tools/call. No
- * dependencies: each tool runs hbengine and returns what it printed.
+ * dependencies: each tool runs hbengine and returns what it printed. Uploads
+ * use hbengine's direct-to-storage session flow through that same CLI path.
  *
  *   { "mcpServers": { "house-engine": { "command": "node", "args": ["…/engine-mcp/server.mjs"],
  *       "env": { "HBENGINE_KEY": "hbk_…" } } } }
@@ -16,9 +17,9 @@
  * run, handle and serve.
  */
 import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import { createInterface } from 'node:readline';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { TEMPLATES } from '../engine-cli/templates.mjs';
 
 
@@ -34,8 +35,8 @@ const VERSION = (() => {
     }
     return 'dev';
 })();
-const HBENGINE = new URL('../engine-cli/hbengine.mjs', import.meta.url).pathname;
-const GUIDE = new URL('../engine-sdk/GUIDE.md', import.meta.url).pathname;
+const HBENGINE = fileURLToPath(new URL('../engine-cli/hbengine.mjs', import.meta.url));
+const GUIDE = fileURLToPath(new URL('../engine-sdk/GUIDE.md', import.meta.url));
 const DIR = { type: 'string', description: 'the project directory (math/, bundle/, hbengine.json)' };
 // The most a reply to the reviewer may say (the studio platform refuses more).
 export const REPLY_MAX = 4000;
@@ -49,11 +50,11 @@ export const TOOLS = [
     { name: 'engine_init', description: 'Start a game from a template: math/, bundle/, hbengine.json in a new directory.', inputSchema: { type: 'object', properties: { dir: { type: 'string', description: 'new directory' }, template: { type: 'string', enum: Object.keys(TEMPLATES) }, slug: { type: 'string', description: 'the game slug, a-z 0-9 -, 2–24 chars' } }, required: ['dir', 'slug'] } },
     { name: 'engine_verify', description: 'Verify the math pack with the engine’s own verifier: exact RTP, hit rate and max multiplier per bet, the mathHash; or the errors.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
     { name: 'engine_lint', description: 'Scan the bundle as the upload will: budgets, assets.json, forbidden code, outside URLs, engine use.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
-    { name: 'engine_test', description: 'Offline: the upload\'s checks (boot, idle, fit at desktop and phone sizes and fullscreen, a bet through the game\'s own UI, currency, errors, network) in Chrome against engine-dev, the engine on this machine. Needs Chrome and playwright-core. About two minutes.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
-    { name: 'engine_pack', description: 'Verify and lint, then write dist/<slug>-<date>.tgz (math, bundle, store page, tile) and its sha256: the file to hand to Housebets.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
-    { name: 'engine_upload', description: 'Ship a version: verify + lint, upload to the portal, which registers it with the sandbox and plays the conformance run on desktop and phone (bet, currency, outage, fit, errors, network). Returns the report and, on success, the link to play it inside the site. Takes about two minutes.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_test', description: 'Offline: the upload\'s checks (boot, idle, fit at desktop and phone sizes and fullscreen, a bet through the game\'s own UI, currency, errors, network) in Chrome against engine-dev, the engine on this machine. Needs Chrome and playwright-core. About two minutes; with timeTravel, also the fake-clock matrix the upload plays (the clock moved days and years, other zones and languages, a 30-minute jump after a round, 300 fast rounds): about ten.', inputSchema: { type: 'object', properties: { dir: DIR, timeTravel: { type: 'boolean', description: 'Also play the time-travel matrix, as the upload does.' } }, required: ['dir'] } },
+    { name: 'engine_pack', description: 'Verify and lint, then write dist/<slug>-<date>.tgz (math and bundle; the store page goes apart) and its sha256: the file to hand to Housebets.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_upload', description: 'Ship a version: verify + lint, upload directly to storage through the portal session, which registers it with the sandbox and plays the conformance run on desktop and phone (bet, currency, outage, fit, errors, network), then the time-travel matrix (other dates, zones and languages, 300 fast rounds). Returns the report and, on success, the link to play it inside the site. Takes several minutes: about two for desktop and phone, and up to nine more for the matrix; engine_status shows the state of a run still going.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
     { name: 'engine_status', description: 'Every version of the game and its state (uploaded, verified, sandbox, failed), its review (in review, approved, returned) and which is live, and the game\'s state on the studio platform.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
-    { name: 'engine_store', description: 'Send the store page from store.json in the project (title, category, description, features, tags, languages, rules per language; tile.png or tile.webp, 3:4, if present). Answers what review still needs. On a live game the tile stays the reviewed one until Housebets reset it; the page is saved all the same. Needs HBENGINE_KEY.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
+    { name: 'engine_store', description: 'Send the store page from store.json in the project (title, category, description, features, tags, languages, rules per language). Answers what review still needs. Housebets makes the tile from the game’s art when a version goes live. Needs HBENGINE_KEY.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
     { name: 'engine_submit', description: 'Submit the newest version that passed every check for review by Housebets. Needs the studio agreement (accepted by an owner in the dashboard), a complete store page and HBENGINE_KEY. Housebets emails the verdict; once approved, engine_live puts it live.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
     { name: 'engine_live', description: 'Put the newest approved version live, as an owner pressing Make live on the game\'s page: the round server and the front end switch to it within seconds. Only after Housebets approved it (engine_status shows "approved"; the studio gets an email). Going live is an owner\'s: the key must be one an owner of the studio made. The first time, players find the game on Housebets once Housebets switches its catalogue page on. Needs HBENGINE_KEY.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
     { name: 'engine_preflight', description: 'Before engine_submit: the review checklist items a machine can check on the newest version (the RTP and max win the rules quote against the verified maths, rules in every store language, the store page, fit on phone and desktop, recovery from errors, load, the network and the scan), each pass / fail with the reason, and the exact facts the rules must quote. Fix every failure first; a reviewer would send it back. Needs HBENGINE_KEY.', inputSchema: { type: 'object', properties: { dir: DIR }, required: ['dir'] } },
@@ -64,6 +65,11 @@ export const TOOLS = [
     { name: 'engine_tickets', description: 'The studio\'s support tickets and Housebets\' answers: each open one with its whole conversation. Answer one with engine_feedback and its ticket id. Needs HBENGINE_KEY.', inputSchema: { type: 'object', properties: {} } },
 ];
 
+// What an agent is told when it connects: where to start.
+const INSTRUCTIONS = 'House Engine tools. Building a game: read engine_guide first. '
+    + 'Games may keep progress per player: engine.progress saves cosmetic progress (skins, collections, settings) on the server for every device and version (guide §3.1), '
+    + 'and a meter is progress that pays — a jar or potion that fills with the stakes and pays a bonus when full, kept and verified by the engine (guide §2.2; template plinko-jar).';
+
 export function run(tool, a) {
     if (tool === 'engine_templates') return { text: Object.entries(TEMPLATES).map(([t, about]) => `${t}: ${about}`).join('\n'), status: 0 };
     if (tool === 'engine_connect') {
@@ -83,8 +89,9 @@ export function run(tool, a) {
     }
     const args = tool === 'engine_init' ? ['init', a.dir, '--template', a.template || 'coin', '--slug', a.slug]
         : tool === 'engine_reply' ? ['reply', a.dir, '--thread', String(a.thread), '--message', String(a.message || ''), ...(a.fixed ? ['--fixed'] : [])]
+        : tool === 'engine_test' && a.timeTravel ? ['test', a.dir, '--time-travel']
         : [tool.slice('engine_'.length), a.dir];
-    const r = spawnSync('node', [HBENGINE, ...args], { encoding: 'utf8', timeout: 10 * 60 * 1000 });
+    const r = spawnSync('node', [HBENGINE, ...args], { encoding: 'utf8', timeout: (tool === 'engine_test' && a.timeTravel ? 20 : 10) * 60 * 1000 });
     // hbengine did not run at all (not found, killed at the timeout): say so, not "nullnull".
     if (r.error) return { text: `hbengine did not run: ${r.error.message}`, status: 1 };
     return { text: ((r.stdout || '') + (r.stderr || '')).trim() || (r.status === 0 ? 'ok' : `exit ${r.status ?? 1}`), status: r.status ?? 1 };
@@ -110,13 +117,22 @@ function support(tool, a) {
 
 const error = (text) => ({ content: [{ type: 'text', text }], isError: true });
 
+/** A server's request handler: its tools, what runs them, its name and its first words to an agent. */
+export function handler({ tools, run: runTool, name, instructions }) {
+    return (msg) => answer(msg, tools, runTool, name, instructions);
+}
+
 /** One request's result (null for a notification, or for a line that is not a request), the same whatever the transport. */
 export function handle(msg) {
+    return answer(msg, TOOLS, run, 'house-engine', INSTRUCTIONS);
+}
+
+function answer(msg, TOOLS, run, name, INSTRUCTIONS) {
     if (!msg || typeof msg !== 'object') return null;
     const { id, method } = msg;
     // `params` may be missing, null or a scalar from a loose client: an empty one, never a crash.
     const params = msg.params && typeof msg.params === 'object' ? msg.params : {};
-    if (method === 'initialize') return { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'house-engine', version: VERSION } };
+    if (method === 'initialize') return { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name, version: VERSION }, instructions: INSTRUCTIONS };
     if (method === 'tools/list') return { tools: TOOLS };
     if (method === 'tools/call') {
         const tool = TOOLS.find((t) => t.name === params.name);
@@ -134,13 +150,13 @@ export function handle(msg) {
 
 /** Serves JSON-RPC over a pair of streams (stdio by default). No line can end the server: a
  * request it cannot handle is answered with a JSON-RPC error, anything else is dropped. */
-export function serve({ input = process.stdin, output = process.stdout } = {}) {
+export function serve({ input = process.stdin, output = process.stdout, handle: reply = handle } = {}) {
     const send = (body) => output.write(JSON.stringify({ jsonrpc: '2.0', ...body }) + '\n');
     createInterface({ input }).on('line', (line) => {
         let msg;
         try { msg = JSON.parse(line); } catch { return; }
         try {
-            const result = handle(msg);
+            const result = reply(msg);
             if (result !== null) send({ id: msg.id, result });
         } catch (e) {
             if (msg && typeof msg === 'object' && msg.id !== undefined) send({ id: msg.id, error: { code: -32603, message: e && e.message ? e.message : String(e) } });
@@ -148,4 +164,4 @@ export function serve({ input = process.stdin, output = process.stdout } = {}) {
     });
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) serve();
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) serve();