@open-rgs/simulator 0.2.0

package/README.md

@@ -0,0 +1,114 @@
+# @open-rgs/simulator
+
+Per-mode RTP + hit-rate simulator and report generator for open-rgs
+games. Library, no CLI in v1.
+
+## Install
+
+```bash
+bun add -d @open-rgs/simulator
+```
+
+## Use
+
+Write a `simulate.ts` next to your game's `index.ts`:
+
+```ts
+import { simulate, mdReportSet, mulberry32 } from "@open-rgs/simulator";
+import { loadLuaMath } from "@open-rgs/core";
+import { defineGame } from "@open-rgs/contract";
+
+// Seed the MATH's rng so spins are reproducible.
+const math = await loadLuaMath("./maths/spin.lua", {
+  rng: mulberry32(42),
+});
+
+const manifest = defineGame({
+  id: "hello-spin",
+  declaredRtp: 0.95,
+  defaultMode: "default",
+  modes: { default: { math, stakeMultiplier: 1 } },
+});
+
+const reports = await simulate(manifest, { spinsPerMode: 100_000 });
+console.log(mdReportSet(reports));
+```
+
+Run it: `bun src/simulate.ts > report.md`.
+
+## What you get back
+
+One [`SimulationReport`](src/report.ts) per mode:
+
+```
+# Simulation — hello-spin / default
+
+math hello-spin@0.2.0 (simple)
+
+- Measured RTP: 94.87% (declared 95.00%, Δ -0.13%)
+- Hit rate: 38.74%
+- Spins: 100,000 · Bet: 1u/spin · Time: 412ms
+- Stake multiplier: 1× · Internal: no
+
+## Multiplier distribution
+| stat   | value   |
+|--------|---------|
+| min    | 0.0000  |
+| mean   | 0.9487  |
+| stddev | 4.2814  |
+| p50    | 0.0000  |
+| p90    | 1.5000  |
+| ...    |         |
+
+## Outcome types
+| type    | count    | share   |
+| ------- | -------- | ------- |
+| loss    | 61,260   | 61.26%  |
+| win     | 37,824   | 37.82%  |
+| scatter | 916      | 0.92%   |
+
+## Next-mode routes
+| target     | count | share |
+| ---------- | ----- | ----- |
+| free-spins | 916   | 0.92% |
+```
+
+## Reproducibility note
+
+The simulator's own `seed` option only drives its **complex-round step
+strategy** ("random" / "first"). To make the *math's* spins
+reproducible, seed the math at `loadLuaMath` time:
+
+```ts
+import { mulberry32 } from "@open-rgs/simulator/rng";
+const math = await loadLuaMath("./maths/spin.lua", { rng: mulberry32(42) });
+```
+
+The same `mulberry32` is exported from both `@open-rgs/simulator` and
+its `/rng` subpath, so you can import it into the simulator script *or*
+into a separate math-loading harness without dragging the whole sim in.
+
+## Complex-round strategies
+
+For complex rounds (open / step / close with player actions) the
+simulator picks actions via:
+
+| strategy | behaviour                                            |
+|----------|------------------------------------------------------|
+| `"first"`| Always `awaiting.options[0]`. Default. Deterministic. |
+| `"random"` | Picks uniformly from `awaiting.options` using the simulator's seeded rng. |
+
+Bespoke strategies (e.g., always-gamble, always-take) aren't first-
+class yet — write your own loop using the orchestrator's
+`OrchestratorAPI` if you need them.
+
+## Caveats
+
+- `next_mode` and `carry` are recorded but **not followed**. Each
+  mode is simulated in isolation. Cross-mode session RTP needs a
+  different harness; this one measures per-mode math behaviour.
+- Free-round campaigns aren't simulated either — those are platform-
+  side, and the simulator skips the platform adapter entirely.
+- The whole reel-distribution is held in memory (`number[]` of length
+  `spinsPerMode`) so percentile and stddev can be computed. 100k spins
+  ≈ 800kB. For 10M-spin runs, refactor to streaming quantile sketches.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@open-rgs/simulator",
+  "version": "0.2.0",
+  "description": "Per-mode RTP + hit-rate simulator and report generator for open-rgs games. Library; no CLI in v1.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-rgs/open-rgs.git",
+    "directory": "packages/simulator"
+  },
+  "homepage": "https://github.com/open-rgs/open-rgs",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./rng": "./src/rng.ts"
+  },
+  "bin": {
+    "open-rgs-sim": "./src/cli.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": ["src", "README.md"],
+  "keywords": ["open-rgs", "rgs", "simulator", "rtp", "slot", "math"],
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@open-rgs/contract": "0.3.0",
+    "handlebars": "^4.7.8"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,144 @@
+#!/usr/bin/env bun
+// open-rgs-sim — CLI front-end for @open-rgs/simulator.
+//
+// Usage:
+//   bunx open-rgs-sim <manifest-module> [--spins N] [--seed N] [--out DIR]
+//                                       [--format md|html|json|all]
+//
+// <manifest-module> is a TS / JS file that default-exports either:
+//   • a GameManifest, OR
+//   • an async function returning a GameManifest
+//
+// Examples:
+//   bunx open-rgs-sim ./src/manifest.ts
+//   bunx open-rgs-sim ./src/manifest.ts --spins 250000 --seed 7
+//   bunx open-rgs-sim ./src/manifest.ts --out reports --format html
+
+import { resolve, dirname, join, basename } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import { simulate } from "./simulate.js";
+import { mdReportSet } from "./report.js";
+import { htmlReportSet } from "./html.js";
+import type { GameManifest } from "@open-rgs/contract";
+
+interface CliOpts {
+  manifestPath: string;
+  spins: number;
+  seed: number;
+  outDir: string;
+  format: "md" | "html" | "json" | "all";
+  betUnits: number;
+  includeInternal: boolean;
+  quiet: boolean;
+}
+
+function parseArgs(argv: readonly string[]): CliOpts {
+  const positional: string[] = [];
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq >= 0) flags[a.slice(2, eq)] = a.slice(eq + 1);
+      else { flags[a.slice(2)] = argv[++i] ?? "true"; }
+    } else {
+      positional.push(a);
+    }
+  }
+  if (positional.length === 0) usageAndExit("missing <manifest-module> argument");
+  return {
+    manifestPath: positional[0]!,
+    spins: Number(flags["spins"] ?? "100000"),
+    seed: Number(flags["seed"] ?? "0"),
+    outDir: flags["out"] ?? "./reports",
+    format: ((flags["format"] ?? "all") as CliOpts["format"]),
+    betUnits: Number(flags["bet"] ?? "1"),
+    includeInternal: flags["skip-internal"] === "true" ? false : true,
+    quiet: flags["quiet"] === "true",
+  };
+}
+
+function usageAndExit(msg: string): never {
+  process.stderr.write(`open-rgs-sim: ${msg}\n\n`);
+  process.stderr.write(`Usage: bunx open-rgs-sim <manifest-module> [opts]\n`);
+  process.stderr.write(`Opts:\n`);
+  process.stderr.write(`  --spins N            spins per mode (default 100000)\n`);
+  process.stderr.write(`  --seed N             simulator PRNG seed (default 0)\n`);
+  process.stderr.write(`  --bet N              units per spin pre-stakeMultiplier (default 1)\n`);
+  process.stderr.write(`  --out DIR            output directory (default ./reports)\n`);
+  process.stderr.write(`  --format md|html|json|all   (default all)\n`);
+  process.stderr.write(`  --skip-internal      skip modes flagged { internal: true }\n`);
+  process.stderr.write(`  --quiet              suppress stdout progress lines\n`);
+  process.exit(2);
+}
+
+async function loadManifest(modulePath: string, seed: number): Promise<GameManifest> {
+  const abs = resolve(process.cwd(), modulePath);
+  const mod = await import(abs);
+  // Accept default export, named `manifest`, or named `buildManifest`.
+  // Functions are called with `{ seed }` so they can seed the math's RNG.
+  const candidate = mod.default ?? mod.manifest ?? mod.buildManifest;
+  if (candidate == null) {
+    usageAndExit(`module ${modulePath} does not export default / manifest / buildManifest`);
+  }
+  const resolved = typeof candidate === "function" ? await candidate({ seed }) : candidate;
+  if (!resolved || typeof resolved !== "object" || typeof resolved.id !== "string") {
+    usageAndExit(`module ${modulePath} did not produce a GameManifest`);
+  }
+  return resolved as GameManifest;
+}
+
+async function main(): Promise<void> {
+  const opts = parseArgs(process.argv.slice(2));
+  const manifest = await loadManifest(opts.manifestPath, opts.seed);
+
+  if (!opts.quiet) {
+    process.stderr.write(`open-rgs-sim · ${manifest.id} · ${opts.spins.toLocaleString()} spins/mode · seed ${opts.seed}\n`);
+  }
+
+  const reports = await simulate(manifest, {
+    spinsPerMode: opts.spins,
+    seed: opts.seed,
+    betUnits: opts.betUnits,
+    includeInternal: opts.includeInternal,
+  });
+
+  await mkdir(opts.outDir, { recursive: true });
+  const stem = `${manifest.id}-seed${opts.seed}-spins${opts.spins}`;
+  const wrote: string[] = [];
+
+  if (opts.format === "all" || opts.format === "md") {
+    const p = join(opts.outDir, `${stem}.md`);
+    await writeFile(p, mdReportSet(reports), "utf-8");
+    wrote.push(p);
+  }
+  if (opts.format === "all" || opts.format === "html") {
+    const p = join(opts.outDir, `${stem}.html`);
+    await writeFile(p, htmlReportSet(reports), "utf-8");
+    wrote.push(p);
+  }
+  if (opts.format === "all" || opts.format === "json") {
+    const p = join(opts.outDir, `${stem}.json`);
+    await writeFile(p, JSON.stringify({
+      schema:  "open-rgs/simulator/report@1",
+      game:    reports[0]?.game ?? null,
+      reports,
+    }, null, 2), "utf-8");
+    wrote.push(p);
+  }
+
+  if (!opts.quiet) {
+    for (const p of wrote) process.stderr.write(`→ ${p}\n`);
+    // Always print the one-line narrative(s) to stdout for grep/jq.
+    for (const r of reports) process.stdout.write(`${r.narrative}\n`);
+  }
+}
+
+main().catch(e => {
+  process.stderr.write(`open-rgs-sim: ${e instanceof Error ? e.message : String(e)}\n`);
+  if (e instanceof Error && e.stack) process.stderr.write(e.stack + "\n");
+  process.exit(1);
+});
+
+// Silence "unused" warnings for path helpers — they're imported for runtime use only.
+void dirname; void basename;

package/src/deviation.ts

@@ -0,0 +1,129 @@
+// Target-vs-measured deviation. Each entry in the author's
+// MathExpectations produces one TargetDeviation; the simulator embeds
+// them in the report so consumers (and LLMs) can scan for what's off.
+
+import type { MathExpectations, MathTarget } from "@open-rgs/contract";
+
+export type DeviationStatus = "ok" | "warn" | "fail";
+
+export interface TargetDeviation {
+  /** Dotted key, e.g. "hit_rate", "rate.scatter_trigger",
+   *  "rtp_contribution.scatter", "tag_share.feature". */
+  key: string;
+  target: number;
+  measured: number;
+  /** measured - target. */
+  delta: number;
+  /** Absolute tolerance band (derived if not declared: 5% of |target|). */
+  tolerance: number;
+  status: DeviationStatus;
+}
+
+interface MeasuredSeries {
+  hitRate: number;
+  rates: Record<string, number>;          // per-spin rate of named counter
+  rtpContributions: Record<string, number>; // RTP fraction of named bucket
+  tagShares: Record<string, number>;      // per-spin share of tagged spins
+}
+
+/** Compute one TargetDeviation per declared target in `expected`. Quiet
+ *  when `expected` is undefined — no opinions, no entries. */
+export function computeDeviations(
+  expected: MathExpectations | undefined,
+  measured: MeasuredSeries,
+): TargetDeviation[] {
+  if (!expected) return [];
+  const out: TargetDeviation[] = [];
+
+  if (expected.hitRate) {
+    out.push(make("hit_rate", expected.hitRate, measured.hitRate));
+  }
+  for (const [name, t] of Object.entries(expected.rate ?? {})) {
+    out.push(make(`rate.${name}`, t, measured.rates[name] ?? 0));
+  }
+  for (const [name, t] of Object.entries(expected.rtpContribution ?? {})) {
+    out.push(make(`rtp_contribution.${name}`, t, measured.rtpContributions[name] ?? 0));
+  }
+  for (const [name, t] of Object.entries(expected.tagShare ?? {})) {
+    out.push(make(`tag_share.${name}`, t, measured.tagShares[name] ?? 0));
+  }
+
+  // Stable sort: status (fail → warn → ok), then key.
+  const order: Record<DeviationStatus, number> = { fail: 0, warn: 1, ok: 2 };
+  out.sort((a, b) => order[a.status] - order[b.status] || a.key.localeCompare(b.key));
+  return out;
+}
+
+function make(key: string, t: MathTarget, measured: number): TargetDeviation {
+  const tolerance = t.tolerance ?? Math.max(Math.abs(t.target) * 0.05, 1e-9);
+  const delta = measured - t.target;
+  const adelta = Math.abs(delta);
+  const status: DeviationStatus =
+    adelta <= tolerance      ? "ok" :
+    adelta <= 2 * tolerance  ? "warn" :
+                               "fail";
+  return { key, target: t.target, measured, delta, tolerance, status };
+}
+
+/** Generate a short, machine-readable narrative summarising the report
+ *  for AI consumption. Designed to be quotable and grep-able. */
+export function narrate(
+  game: string,
+  mode: string,
+  rtp: { measured: number; declared: number; delta: number },
+  hitRate: number,
+  deviations: readonly TargetDeviation[],
+  topContributions: ReadonlyArray<{ name: string; rtpShare: number }>,
+): string {
+  const fails = deviations.filter(d => d.status === "fail");
+  const warns = deviations.filter(d => d.status === "warn");
+  const oks   = deviations.filter(d => d.status === "ok");
+  const pct = (n: number) => (n * 100).toFixed(2) + "%";
+  const sgn = (n: number) => (n >= 0 ? "+" : "") + (n * 100).toFixed(2) + "%";
+
+  const parts: string[] = [];
+  parts.push(
+    `${game}/${mode}: RTP ${pct(rtp.measured)} (declared ${pct(rtp.declared)}, Δ ${sgn(rtp.delta)}); hit rate ${pct(hitRate)}.`,
+  );
+
+  if (deviations.length === 0) {
+    parts.push("No author-declared targets to compare.");
+  } else if (fails.length === 0 && warns.length === 0) {
+    parts.push(`All ${oks.length} declared targets within tolerance.`);
+  } else {
+    if (fails.length > 0) {
+      parts.push(
+        `${fails.length} target${fails.length === 1 ? "" : "s"} FAIL: ` +
+        fails.slice(0, 3).map(d => `${d.key}=${num(d.measured)} (target ${num(d.target)}, Δ ${signedNum(d.delta)})`).join("; ") +
+        (fails.length > 3 ? `; +${fails.length - 3} more` : "") + ".",
+      );
+    }
+    if (warns.length > 0) {
+      parts.push(
+        `${warns.length} target${warns.length === 1 ? "" : "s"} WARN: ` +
+        warns.slice(0, 3).map(d => `${d.key}=${num(d.measured)} (target ${num(d.target)})`).join("; ") +
+        (warns.length > 3 ? `; +${warns.length - 3} more` : "") + ".",
+      );
+    }
+    if (oks.length > 0) parts.push(`${oks.length} target${oks.length === 1 ? "" : "s"} ok.`);
+  }
+
+  if (topContributions.length > 0) {
+    parts.push(
+      `Top RTP contributors: ` +
+      topContributions.slice(0, 3).map(c => `${c.name} (${pct(c.rtpShare)})`).join(", ") + ".",
+    );
+  }
+
+  return parts.join(" ");
+}
+
+function num(n: number): string {
+  if (Math.abs(n) < 1e-6) return "0";
+  if (Math.abs(n) < 0.01) return n.toExponential(2);
+  return n.toFixed(4);
+}
+function signedNum(n: number): string {
+  const s = num(Math.abs(n));
+  return (n >= 0 ? "+" : "-") + s;
+}

package/src/html.ts

@@ -0,0 +1,136 @@
+// HTML report via Handlebars. Self-contained single-file output: inline
+// CSS, inline JS, no external assets. Styled to match the open-rgs.dev
+// site (warm-paper light, warm-charcoal dark, Charter serif).
+//
+// Use:
+//   import { htmlReportSet } from "@open-rgs/simulator";
+//   await Bun.write("report.html", htmlReportSet(reports));
+//
+// Custom template? Pass `template: string` (raw .hbs source) in options.
+
+import Handlebars from "handlebars";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { SimulationReport } from "./report.js";
+import type { TargetDeviation, DeviationStatus } from "./deviation.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const defaultTemplateSrc = readFileSync(join(here, "templates", "default.hbs"), "utf-8");
+
+let helpersRegistered = false;
+function ensureHelpers(): void {
+  if (helpersRegistered) return;
+  helpersRegistered = true;
+
+  Handlebars.registerHelper("pct", (n: unknown) => formatPct(toNum(n)));
+  Handlebars.registerHelper("pctSigned", (n: unknown) => {
+    const v = toNum(n);
+    return (v >= 0 ? "+" : "") + (v * 100).toFixed(2) + "%";
+  });
+  Handlebars.registerHelper("fixed", (n: unknown, digits: unknown) => {
+    const d = typeof digits === "number" ? digits : 2;
+    return toNum(n).toFixed(d);
+  });
+  Handlebars.registerHelper("fixedSigned", (n: unknown, digits: unknown) => {
+    const d = typeof digits === "number" ? digits : 2;
+    const v = toNum(n);
+    return (v >= 0 ? "+" : "") + v.toFixed(d);
+  });
+  Handlebars.registerHelper("numLocale", (n: unknown) => toNum(n).toLocaleString());
+  Handlebars.registerHelper("eq", (a: unknown, b: unknown) => a === b);
+  Handlebars.registerHelper("gt", (a: unknown, b: unknown) => toNum(a) > toNum(b));
+  Handlebars.registerHelper("div", (a: unknown, b: unknown) => {
+    const d = toNum(b);
+    return d === 0 ? 0 : toNum(a) / d;
+  });
+
+  // {{#each (entries obj)}} → iterate { key, value } pairs.
+  Handlebars.registerHelper("entries", (obj: unknown) => {
+    if (!obj || typeof obj !== "object") return [];
+    return Object.entries(obj as Record<string, unknown>).map(([key, value]) => ({ key, value }));
+  });
+
+  Handlebars.registerHelper("anyEntries", (obj: unknown) => {
+    if (!obj || typeof obj !== "object") return false;
+    return Object.keys(obj as Record<string, unknown>).length > 0;
+  });
+
+  // Sorted entries for outcomeTypes / nextModeRoutes (record<string, number>): desc by value.
+  Handlebars.registerHelper("sortEntries", (obj: unknown) => {
+    if (!obj || typeof obj !== "object") return [];
+    return Object.entries(obj as Record<string, number>)
+      .map(([key, value]) => ({ key, value }))
+      .sort((a, b) => b.value - a.value);
+  });
+
+  // Counters: desc by .total
+  Handlebars.registerHelper("sortCounters", (obj: unknown) => {
+    if (!obj || typeof obj !== "object") return [];
+    return Object.entries(obj as Record<string, { total: number; perSpin: number }>)
+      .map(([key, value]) => ({ key, value }))
+      .sort((a, b) => b.value.total - a.value.total);
+  });
+
+  // Tag shares: desc by .spins
+  Handlebars.registerHelper("sortTags", (obj: unknown) => {
+    if (!obj || typeof obj !== "object") return [];
+    return Object.entries(obj as Record<string, { spins: number; share: number }>)
+      .map(([key, value]) => ({ key, value }))
+      .sort((a, b) => b.value.spins - a.value.spins);
+  });
+
+  // Contributions: desc by .rtpShare
+  Handlebars.registerHelper("sortContributions", (obj: unknown) => {
+    if (!obj || typeof obj !== "object") return [];
+    return Object.entries(obj as Record<string, { sumMultiplier: number; rtpShare: number }>)
+      .map(([key, value]) => ({ key, value }))
+      .sort((a, b) => b.value.rtpShare - a.value.rtpShare);
+  });
+
+  // Status badge: count by status (ok/warn/fail), sorted fail-first.
+  Handlebars.registerHelper("statusCounts", (deviations: unknown) => {
+    if (!Array.isArray(deviations)) return [];
+    const counts: Record<DeviationStatus, number> = { fail: 0, warn: 0, ok: 0 };
+    for (const d of deviations as TargetDeviation[]) {
+      counts[d.status] = (counts[d.status] ?? 0) + 1;
+    }
+    return (["fail", "warn", "ok"] as DeviationStatus[])
+      .filter(k => counts[k] > 0)
+      .map(k => ({ key: k, value: counts[k] }));
+  });
+}
+
+export interface HtmlReportOptions {
+  /** Override the default template. Pass raw .hbs source. */
+  template?: string;
+  /** Override the "generated at" timestamp. Default = new Date().toISOString(). */
+  generatedAt?: string;
+  /** Override the generator string. Default = "@open-rgs/simulator". */
+  generator?: string;
+}
+
+/** Render all reports as a single self-contained HTML document. */
+export function htmlReportSet(
+  reports: readonly SimulationReport[],
+  opts: HtmlReportOptions = {},
+): string {
+  ensureHelpers();
+  const template = Handlebars.compile(opts.template ?? defaultTemplateSrc, { noEscape: false });
+  return template({
+    reports,
+    game: reports[0]?.game ?? { id: "(empty)", declaredRtp: 0, defaultMode: "(none)" },
+    generatedAt: opts.generatedAt ?? new Date().toISOString(),
+    generator: opts.generator ?? "@open-rgs/simulator",
+  });
+}
+
+function toNum(v: unknown): number {
+  if (typeof v === "number") return v;
+  if (typeof v === "string") return Number(v);
+  return 0;
+}
+
+function formatPct(n: number): string {
+  return (n * 100).toFixed(2) + "%";
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// @open-rgs/simulator public surface.
+
+export { simulate, type SimulateOptions } from "./simulate.js";
+export { mdReport, mdReportSet, type SimulationReport, type DistributionStats } from "./report.js";
+export { htmlReportSet, type HtmlReportOptions } from "./html.js";
+export { computeDeviations, narrate, type TargetDeviation, type DeviationStatus } from "./deviation.js";
+export { mulberry32 } from "./rng.js";