@energy8platform/platform-core 0.16.0

package/src/lua/SimulationRunner.ts

@@ -0,0 +1,192 @@
+import { LuaEngine } from './LuaEngine';
+import type { SimulationConfig, SimulationResult, GameDefinition } from './types';
+
+/**
+ * Runs N iterations of a Lua game script and collects RTP statistics.
+ * Supports regular spins, buy bonus, and ante bet simulation.
+ *
+ * @example
+ * ```ts
+ * const runner = new SimulationRunner({
+ *   script: luaSource,
+ *   gameDefinition,
+ *   iterations: 1_000_000,
+ *   bet: 1.0,
+ *   seed: 42,
+ *   onProgress: (done, total) => console.log(`${done}/${total}`),
+ * });
+ *
+ * const result = runner.run();
+ * console.log(`RTP: ${result.totalRtp.toFixed(2)}%`);
+ * ```
+ */
+export class SimulationRunner {
+  private config: SimulationConfig;
+
+  constructor(config: SimulationConfig) {
+    this.config = config;
+  }
+
+  run(): SimulationResult {
+    const {
+      script,
+      gameDefinition,
+      iterations,
+      bet,
+      seed,
+      action: startAction = 'spin',
+      params,
+      progressInterval = 100_000,
+      onProgress,
+    } = this.config;
+
+    const engine = new LuaEngine({
+      script,
+      gameDefinition,
+      seed,
+      logger: () => {},
+      simulationMode: true,
+    });
+
+    const spinCost = this.calculateSpinCost(startAction, bet, gameDefinition, params);
+
+    let totalWagered = 0;
+    let totalWon = 0;
+    let baseGameWin = 0;
+    let bonusWin = 0;
+    let hits = 0;
+    let maxWinMultiplier = 0;
+    let maxWinHits = 0;
+    let bonusTriggered = 0;
+    let bonusSpinsPlayed = 0;
+
+    const startTime = Date.now();
+
+    try {
+      for (let i = 0; i < iterations; i++) {
+        totalWagered += spinCost;
+        let roundWin = 0;
+        let roundBonusWin = 0;
+
+        // Execute the starting action
+        let result = engine.execute({
+          action: startAction,
+          bet,
+          params,
+        });
+
+        const baseWin = result.totalWin;
+
+        // If a session was created, play through it using nextActions from the engine
+        if (result.session && !result.session.completed) {
+          bonusTriggered++;
+
+          let safetyLimit = 10_000;
+          while (result.session && !result.session.completed && safetyLimit-- > 0) {
+            const nextAction = result.nextActions[0];
+            result = engine.execute({ action: nextAction, bet });
+            bonusSpinsPlayed++;
+          }
+
+          // Session completion returns cumulative totalWin (includes trigger spin).
+          // Use it as the full round win — don't add baseWin separately.
+          roundWin = result.totalWin;
+          roundBonusWin = roundWin - baseWin;
+        } else {
+          // No session — just base game win
+          roundWin = baseWin;
+        }
+
+        baseGameWin += baseWin;
+        bonusWin += roundBonusWin;
+        totalWon += roundWin;
+
+        if (roundWin > 0) hits++;
+
+        const roundMultiplier = roundWin / bet;
+        if (roundMultiplier > maxWinMultiplier) {
+          maxWinMultiplier = roundMultiplier;
+        }
+
+        if (result.variables?.max_win_reached === 1) {
+          maxWinHits++;
+        }
+
+        // Progress reporting
+        if (onProgress && (i + 1) % progressInterval === 0) {
+          onProgress(i + 1, iterations);
+        }
+      }
+    } finally {
+      engine.destroy();
+    }
+
+    const durationMs = Date.now() - startTime;
+
+    return {
+      gameId: gameDefinition.id,
+      action: startAction,
+      iterations,
+      durationMs,
+      totalRtp: totalWagered > 0 ? (totalWon / totalWagered) * 100 : 0,
+      baseGameRtp: totalWagered > 0 ? (baseGameWin / totalWagered) * 100 : 0,
+      bonusRtp: totalWagered > 0 ? (bonusWin / totalWagered) * 100 : 0,
+      hitFrequency: iterations > 0 ? (hits / iterations) * 100 : 0,
+      maxWin: Math.round(maxWinMultiplier * 100) / 100,
+      maxWinHits,
+      bonusTriggered,
+      bonusSpinsPlayed,
+      _raw: { totalWagered, totalWon, baseGameWin, bonusWin, hits },
+    };
+  }
+
+  /** Calculate the real cost of one spin (accounting for buy bonus / ante bet) */
+  private calculateSpinCost(
+    action: string,
+    bet: number,
+    gameDefinition: GameDefinition,
+    params?: Record<string, unknown>,
+  ): number {
+    // Check if this is a buy bonus action
+    const actionDef = gameDefinition.actions[action];
+    if (actionDef?.buy_bonus_mode && gameDefinition.buy_bonus) {
+      const mode = gameDefinition.buy_bonus.modes[actionDef.buy_bonus_mode];
+      if (mode) {
+        return bet * mode.cost_multiplier;
+      }
+    }
+
+    // Check ante bet
+    if (params?.ante_bet && gameDefinition.ante_bet) {
+      return bet * gameDefinition.ante_bet.cost_multiplier;
+    }
+
+    return bet;
+  }
+}
+
+/** Format a SimulationResult for console output */
+export function formatSimulationResult(result: SimulationResult): string {
+  const lines: string[] = [
+    '',
+    '--- Simulation Results ---',
+    `Game: ${result.gameId}`,
+    `Action: ${result.action}`,
+    `Iterations: ${result.iterations.toLocaleString()}`,
+    `Duration: ${(result.durationMs / 1000).toFixed(1)}s`,
+    `Total RTP: ${result.totalRtp.toFixed(2)}%`,
+    `Base Game RTP: ${result.baseGameRtp.toFixed(2)}%`,
+    `Bonus RTP: ${result.bonusRtp.toFixed(2)}%`,
+    `Hit Frequency: ${result.hitFrequency.toFixed(2)}%`,
+    `Max Win: ${result.maxWin.toFixed(2)}x`,
+    `Max Win Hits: ${result.maxWinHits} (rounds capped by max_win)`,
+  ];
+
+  if (result.bonusTriggered > 0) {
+    const frequency = Math.round(result.iterations / result.bonusTriggered);
+    lines.push(`Bonus Triggered: ${result.bonusTriggered.toLocaleString()} (1 in ${frequency} spins)`);
+    lines.push(`Bonus Spins Played: ${result.bonusSpinsPlayed.toLocaleString()}`);
+  }
+
+  return lines.join('\n');
+}

package/src/lua/fengari.d.ts

@@ -0,0 +1,10 @@
+declare module 'fengari' {
+  const fengari: {
+    lua: any;
+    lauxlib: any;
+    lualib: any;
+    to_luastring: (str: string) => Uint8Array;
+    to_jsstring: (str: Uint8Array) => string;
+  };
+  export default fengari;
+}

package/src/lua/index.ts

@@ -0,0 +1,28 @@
+// Browser-safe Lua engine surface. Only depends on `fengari`, no Node built-ins.
+//
+// For the Node-only runners (NativeSimulationRunner backed by a Go binary,
+// ParallelSimulationRunner backed by worker_threads), import from
+// `@energy8platform/platform-core/simulation` instead.
+export { LuaEngine } from './LuaEngine';
+export { LuaEngineAPI, createSeededRng } from './LuaEngineAPI';
+export { ActionRouter, evaluateCondition } from './ActionRouter';
+export { SessionManager } from './SessionManager';
+export { PersistentState } from './PersistentState';
+export { SimulationRunner, formatSimulationResult } from './SimulationRunner';
+export type {
+  GameDefinition,
+  ActionDefinition,
+  TransitionRule,
+  SessionConfig,
+  LuaEngineConfig,
+  LuaPlayResult,
+  MaxWinConfig,
+  BuyBonusConfig,
+  BuyBonusMode,
+  AnteBetConfig,
+  PersistentStateConfig,
+  BetLevelsConfig,
+  SimulationConfig,
+  SimulationResult,
+  SimulationRawAccumulators,
+} from './types';

package/src/lua/types.ts

@@ -0,0 +1,149 @@
+import type { SessionData, PlayParams } from '@energy8platform/game-sdk';
+
+// ─── Game Definition (Platform JSON Config) ─────────────
+
+export interface GameDefinition {
+  id: string;
+  type: 'SLOT' | 'TABLE';
+  actions: Record<string, ActionDefinition>;
+  bet_levels?: number[] | BetLevelsConfig;
+  max_win?: MaxWinConfig;
+  buy_bonus?: BuyBonusConfig;
+  ante_bet?: AnteBetConfig;
+  persistent_state?: PersistentStateConfig;
+}
+
+export interface BetLevelsConfig {
+  levels?: number[];
+  min?: number;
+  max?: number;
+}
+
+export interface MaxWinConfig {
+  multiplier?: number;
+  fixed?: number;
+}
+
+export interface BuyBonusConfig {
+  modes: Record<string, BuyBonusMode>;
+}
+
+export interface BuyBonusMode {
+  cost_multiplier: number;
+  /** Distribution of forced scatter counts. Optional — if omitted, Lua script handles bonus setup itself. */
+  scatter_distribution?: Record<string, number>;
+  /** Optional description */
+  description?: string;
+}
+
+export interface AnteBetConfig {
+  cost_multiplier: number;
+}
+
+export interface PersistentStateConfig {
+  vars: string[];
+  exposed_vars: string[];
+}
+
+// ─── Actions & Transitions ──────────────────────────────
+
+export interface ActionDefinition {
+  stage: string;
+  debit: 'bet' | 'buy_bonus_cost' | 'ante_bet_cost' | 'none';
+  credit?: 'win' | 'none' | 'defer';
+  requires_session?: boolean;
+  buy_bonus_mode?: string;
+  transitions: TransitionRule[];
+  input_schema?: Record<string, unknown>;
+}
+
+export interface TransitionRule {
+  condition: string;
+  creates_session?: boolean;
+  complete_session?: boolean;
+  credit_override?: 'defer';
+  next_actions: string[];
+  session_config?: SessionConfig;
+  add_spins_var?: string;
+}
+
+export interface SessionConfig {
+  total_spins_var: string;
+  persistent_vars?: string[];
+}
+
+// ─── Lua Engine Config & Results ────────────────────────
+
+export interface LuaEngineConfig {
+  /** Lua script source code */
+  script: string;
+  /** Platform game definition (actions, transitions, bet levels, etc.) */
+  gameDefinition: GameDefinition;
+  /** Seed for deterministic RNG (for simulation/replay) */
+  seed?: number;
+  /** Custom logger function */
+  logger?: (level: string, msg: string) => void;
+  /** Skip marshalling data fields (matrix, wins, etc.) for faster simulation */
+  simulationMode?: boolean;
+}
+
+export interface LuaPlayResult {
+  totalWin: number;
+  data: Record<string, unknown>;
+  nextActions: string[];
+  session: SessionData | null;
+  variables: Record<string, number>;
+  creditDeferred: boolean;
+}
+
+// ─── Simulation ─────────────────────────────────────────
+
+export interface SimulationConfig {
+  /** Lua script source code */
+  script: string;
+  /** Platform game definition */
+  gameDefinition: GameDefinition;
+  /** Number of iterations to run */
+  iterations: number;
+  /** Bet amount per spin */
+  bet: number;
+  /** RNG seed for deterministic results */
+  seed?: number;
+  /** Which action to simulate (default: 'spin') */
+  action?: string;
+  /** Params for the action (buy_bonus mode, ante_bet, etc.) */
+  params?: Record<string, unknown>;
+  /** Report progress every N iterations (default: 100_000) */
+  progressInterval?: number;
+  /** Progress callback */
+  onProgress?: (completed: number, total: number) => void;
+  /** Number of worker threads for parallel simulation (default: os.cpus().length) */
+  workerCount?: number;
+}
+
+export interface SimulationResult {
+  gameId: string;
+  action: string;
+  iterations: number;
+  durationMs: number;
+  totalRtp: number;
+  baseGameRtp: number;
+  bonusRtp: number;
+  hitFrequency: number;
+  maxWin: number;
+  maxWinHits: number;
+  bonusTriggered: number;
+  bonusSpinsPlayed: number;
+  /** Raw accumulators for aggregation across workers */
+  _raw?: SimulationRawAccumulators;
+}
+
+export interface SimulationRawAccumulators {
+  totalWagered: number;
+  totalWon: number;
+  baseGameWin: number;
+  bonusWin: number;
+  hits: number;
+}
+
+export type { SessionData, PlayParams };