@energy8platform/game-engine 0.15.2 → 0.16.0

package/src/lua/ParallelSimulationRunner.ts

@@ -1,156 +0,0 @@
-/// <reference types="node" />
-import { Worker } from 'worker_threads';
-import { cpus } from 'os';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import type { SimulationConfig, SimulationResult, SimulationRawAccumulators } from './types';
-import type { WorkerMessage, WorkerConfig } from './SimulationWorker';
-
-const SEED_STRIDE = 1 << 20; // 2^20 — gap between worker seeds to avoid overlap
-
-/**
- * Runs simulation across multiple worker threads for parallel speedup.
- * Each worker gets an independent LuaEngine with a partitioned seed range.
- *
- * Results are statistically equivalent to single-threaded mode but not
- * bit-identical (different RNG sequence ordering).
- *
- * @example
- * ```ts
- * const runner = new ParallelSimulationRunner({
- *   script: luaSource,
- *   gameDefinition,
- *   iterations: 1_000_000,
- *   bet: 1.0,
- *   workerCount: 8,
- *   onProgress: (done, total) => console.log(`${done}/${total}`),
- * });
- * const result = await runner.run();
- * ```
- */
-export class ParallelSimulationRunner {
-  private config: SimulationConfig;
-  private workerCount: number;
-
-  constructor(config: SimulationConfig) {
-    this.config = config;
-    const maxWorkers = cpus().length;
-    this.workerCount = Math.max(1, Math.min(
-      config.workerCount ?? maxWorkers,
-      maxWorkers,
-      config.iterations, // no point having more workers than iterations
-    ));
-  }
-
-  async run(): Promise<SimulationResult> {
-    const {
-      iterations,
-      seed,
-      onProgress,
-      workerCount: _,
-      ...restConfig
-    } = this.config;
-
-    const workerCount = this.workerCount;
-
-    // Split iterations evenly, remainder goes to last worker
-    const baseChunk = Math.floor(iterations / workerCount);
-    const remainder = iterations - baseChunk * workerCount;
-
-    const workerPath = join(dirname(fileURLToPath(import.meta.url)), 'SimulationWorker.ts');
-
-    const progressPerWorker = new Array<number>(workerCount).fill(0);
-    const totalIterations = iterations;
-
-    const promises = Array.from({ length: workerCount }, (_, i) => {
-      const workerIterations = baseChunk + (i < remainder ? 1 : 0);
-      const workerSeed = seed !== undefined ? seed + i * SEED_STRIDE : undefined;
-
-      const workerConfig: WorkerConfig = {
-        config: {
-          ...restConfig,
-          iterations: workerIterations,
-          seed: workerSeed,
-          progressInterval: this.config.progressInterval,
-        },
-      };
-
-      return new Promise<SimulationResult>((resolve, reject) => {
-        const worker = new Worker(workerPath, {
-          workerData: workerConfig,
-          // tsx registers itself via --require/--import; pass through to workers
-          execArgv: process.execArgv,
-        });
-
-        worker.on('message', (msg: WorkerMessage) => {
-          if (msg.type === 'progress' && onProgress) {
-            progressPerWorker[i] = msg.progress!.completed;
-            const totalCompleted = progressPerWorker.reduce((a, b) => a + b, 0);
-            onProgress(totalCompleted, totalIterations);
-          } else if (msg.type === 'result') {
-            resolve(msg.result!);
-          } else if (msg.type === 'error') {
-            reject(new Error(`Worker ${i} failed: ${msg.error}`));
-          }
-        });
-
-        worker.on('error', (err: Error) => reject(new Error(`Worker ${i} error: ${err.message}`)));
-        worker.on('exit', (code) => {
-          if (code !== 0) reject(new Error(`Worker ${i} exited with code ${code}`));
-        });
-      });
-    });
-
-    const results = await Promise.all(promises);
-    return aggregateResults(results);
-  }
-}
-
-function aggregateResults(results: SimulationResult[]): SimulationResult {
-  const raw: SimulationRawAccumulators = {
-    totalWagered: 0,
-    totalWon: 0,
-    baseGameWin: 0,
-    bonusWin: 0,
-    hits: 0,
-  };
-
-  let iterations = 0;
-  let maxWin = 0;
-  let maxWinHits = 0;
-  let bonusTriggered = 0;
-  let bonusSpinsPlayed = 0;
-  let maxDurationMs = 0;
-
-  for (const r of results) {
-    const rr = r._raw!;
-    raw.totalWagered += rr.totalWagered;
-    raw.totalWon += rr.totalWon;
-    raw.baseGameWin += rr.baseGameWin;
-    raw.bonusWin += rr.bonusWin;
-    raw.hits += rr.hits;
-
-    iterations += r.iterations;
-    if (r.maxWin > maxWin) maxWin = r.maxWin;
-    maxWinHits += r.maxWinHits;
-    bonusTriggered += r.bonusTriggered;
-    bonusSpinsPlayed += r.bonusSpinsPlayed;
-    if (r.durationMs > maxDurationMs) maxDurationMs = r.durationMs;
-  }
-
-  return {
-    gameId: results[0].gameId,
-    action: results[0].action,
-    iterations,
-    durationMs: maxDurationMs,
-    totalRtp: raw.totalWagered > 0 ? (raw.totalWon / raw.totalWagered) * 100 : 0,
-    baseGameRtp: raw.totalWagered > 0 ? (raw.baseGameWin / raw.totalWagered) * 100 : 0,
-    bonusRtp: raw.totalWagered > 0 ? (raw.bonusWin / raw.totalWagered) * 100 : 0,
-    hitFrequency: iterations > 0 ? (raw.hits / iterations) * 100 : 0,
-    maxWin,
-    maxWinHits,
-    bonusTriggered,
-    bonusSpinsPlayed,
-    _raw: raw,
-  };
-}

package/src/lua/PersistentState.ts

@@ -1,80 +0,0 @@
-import type { PersistentStateConfig } from './types';
-
-/**
- * Manages cross-spin persistent state — variables that survive between base game spins.
- * Separate from session-scoped persistence (handled by SessionManager).
- *
- * Handles two mechanisms:
- * 1. Numeric vars declared in `persistent_state.vars` — stored in state.variables
- * 2. Complex data with `_persist_game_*` prefix — stored separately, injected as `_ps_*`
- */
-export class PersistentState {
-  private config: PersistentStateConfig | undefined;
-  private vars: Record<string, number> = {};
-  private gameData: Record<string, unknown> = {};
-
-  constructor(config?: PersistentStateConfig) {
-    this.config = config;
-  }
-
-  /** Load persistent vars into variables map before execute() */
-  loadIntoVariables(variables: Record<string, number>): void {
-    if (!this.config) return;
-
-    for (const varName of this.config.vars) {
-      if (varName in this.vars) {
-        variables[varName] = this.vars[varName];
-      }
-    }
-  }
-
-  /** Save persistent vars from variables map after execute() */
-  saveFromVariables(variables: Record<string, number>): void {
-    if (!this.config) return;
-
-    for (const varName of this.config.vars) {
-      if (varName in variables) {
-        this.vars[varName] = variables[varName];
-      }
-    }
-  }
-
-  /** Extract _persist_game_* keys from Lua return data, store them */
-  storeGameData(data: Record<string, unknown>): void {
-    for (const key of Object.keys(data)) {
-      if (key.startsWith('_persist_game_')) {
-        const cleanKey = key.slice('_persist_game_'.length);
-        this.gameData[cleanKey] = data[key];
-        delete data[key]; // remove from client data
-      }
-    }
-  }
-
-  /** Get _ps_* params for next execute() call */
-  getGameDataParams(): Record<string, unknown> {
-    const params: Record<string, unknown> = {};
-    for (const [key, value] of Object.entries(this.gameData)) {
-      params[`_ps_${key}`] = value;
-    }
-    return params;
-  }
-
-  /** Get exposed vars for client data.persistent_state */
-  getExposedVars(): Record<string, number> | undefined {
-    if (!this.config?.exposed_vars?.length) return undefined;
-
-    const exposed: Record<string, number> = {};
-    for (const varName of this.config.exposed_vars) {
-      if (varName in this.vars) {
-        exposed[varName] = this.vars[varName];
-      }
-    }
-    return exposed;
-  }
-
-  /** Reset all state */
-  reset(): void {
-    this.vars = {};
-    this.gameData = {};
-  }
-}

package/src/lua/SessionManager.ts

@@ -1,227 +0,0 @@
-import type { SessionData } from '@energy8platform/game-sdk';
-import type { TransitionRule } from './types';
-
-interface SessionState {
-  spinsRemaining: number;
-  spinsPlayed: number;
-  totalWin: number;
-  completed: boolean;
-  maxWinReached: boolean;
-  bet: number;
-  maxWinCap: number | undefined;
-  spinsVarName: string | undefined;
-  persistentVarNames: string[];
-  persistentVars: Record<string, number>;
-  persistentData: Record<string, unknown>;
-}
-
-const MAX_SESSION_SPINS = 200;
-
-/**
- * Manages session lifecycle matching the platform server behavior:
- * - createSession: initial spin counted (spinsPlayed=1, totalWin=spinWin)
- * - updateSession: accumulates win, decrements spins, checks max win cap on session level
- * - completeSession: returns cumulative totalWin, cleans up session vars
- * - Safety cap: 200 spins max per session
- */
-export class SessionManager {
-  private session: SessionState | null = null;
-
-  get isActive(): boolean {
-    return this.session !== null && !this.session.completed;
-  }
-
-  get current(): SessionData | null {
-    if (!this.session) return null;
-    return this.toSessionData();
-  }
-
-  get sessionTotalWin(): number {
-    return this.session?.totalWin ?? 0;
-  }
-
-  /** Get the fixed bet amount from the session (server uses session bet, not request bet) */
-  get sessionBet(): number | undefined {
-    return this.session?.bet;
-  }
-
-  /** Get spinsVarName to restore free_spins_remaining into variables */
-  get spinsVarName(): string | undefined {
-    return this.session?.spinsVarName;
-  }
-
-  get spinsRemaining(): number {
-    return this.session?.spinsRemaining ?? 0;
-  }
-
-  /**
-   * Create a new session from a transition rule.
-   * Server behavior: initial spin is already counted (spinsPlayed=1, totalWin includes spinWin).
-   */
-  createSession(
-    rule: TransitionRule,
-    variables: Record<string, number>,
-    bet: number,
-    spinWin: number,
-    maxWinCap: number | undefined,
-  ): SessionData {
-    let spinsRemaining = -1;
-    let spinsVarName: string | undefined;
-    if (rule.session_config?.total_spins_var) {
-      spinsVarName = rule.session_config.total_spins_var;
-      spinsRemaining = variables[spinsVarName] ?? -1;
-    }
-
-    const persistentVarNames: string[] = rule.session_config?.persistent_vars ?? [];
-    const persistentVars: Record<string, number> = {};
-    for (const varName of persistentVarNames) {
-      persistentVars[varName] = variables[varName] ?? 0;
-    }
-
-    this.session = {
-      spinsRemaining,
-      spinsPlayed: 1, // initial spin counts
-      totalWin: spinWin, // initial spin win included
-      completed: false,
-      maxWinReached: false,
-      bet,
-      maxWinCap,
-      spinsVarName,
-      persistentVarNames,
-      persistentVars,
-      persistentData: {},
-    };
-
-    return this.toSessionData();
-  }
-
-  /**
-   * Update session after a bonus spin.
-   * Server behavior: accumulate win, decrement spins, check retrigger, check max win cap,
-   * safety cap at 200 spins.
-   */
-  updateSession(
-    rule: TransitionRule,
-    variables: Record<string, number>,
-    spinWin: number,
-  ): SessionData {
-    if (!this.session) throw new Error('No active session');
-
-    // Accumulate win and count spin
-    this.session.totalWin += spinWin;
-    this.session.spinsPlayed++;
-
-    // Decrement spins (only for non-unlimited sessions)
-    if (this.session.spinsRemaining > 0) {
-      this.session.spinsRemaining--;
-    }
-
-    // Handle retrigger (add_spins_var)
-    if (rule.add_spins_var) {
-      const extraSpins = variables[rule.add_spins_var] ?? 0;
-      if (extraSpins > 0 && this.session.spinsRemaining >= 0) {
-        this.session.spinsRemaining += extraSpins;
-      }
-    }
-
-    // Safety cap: server limits sessions to 200 spins
-    if (this.session.spinsPlayed >= MAX_SESSION_SPINS) {
-      this.session.spinsRemaining = 0;
-    }
-
-    // Update session persistent vars from current variables
-    for (const varName of this.session.persistentVarNames) {
-      if (varName in variables) {
-        this.session.persistentVars[varName] = variables[varName];
-      }
-    }
-
-    // Check max win cap (on session level, not per spin)
-    if (this.session.maxWinCap !== undefined && this.session.totalWin >= this.session.maxWinCap) {
-      this.session.totalWin = this.session.maxWinCap;
-      this.session.spinsRemaining = 0;
-      this.session.maxWinReached = true;
-    }
-
-    // Auto-complete if spins exhausted or explicit complete
-    if (this.session.spinsRemaining === 0 || rule.complete_session) {
-      this.session.completed = true;
-    }
-
-    return this.toSessionData();
-  }
-
-  /**
-   * Complete the session explicitly.
-   * Returns cumulative totalWin and list of session-scoped var names to clean up.
-   */
-  completeSession(): { totalWin: number; session: SessionData; sessionVarNames: string[] } {
-    if (!this.session) throw new Error('No active session to complete');
-
-    this.session.completed = true;
-    const totalWin = this.session.totalWin;
-    const session = this.toSessionData();
-    const sessionVarNames = [...this.session.persistentVarNames];
-
-    this.session = null;
-
-    return { totalWin, session, sessionVarNames };
-  }
-
-  /** Mark max win reached — stops the session */
-  markMaxWinReached(): void {
-    if (this.session) {
-      this.session.maxWinReached = true;
-      this.session.completed = true;
-    }
-  }
-
-  /** Store _persist_* data extracted from Lua result */
-  storePersistData(data: Record<string, unknown>): void {
-    if (!this.session) return;
-
-    for (const key of Object.keys(data)) {
-      if (key.startsWith('_persist_')) {
-        const cleanKey = key.slice('_persist_'.length);
-        this.session.persistentData[cleanKey] = data[key];
-      }
-    }
-  }
-
-  /** Get persistent params to inject into next execute() call */
-  getPersistentParams(): Record<string, unknown> {
-    if (!this.session) return {};
-
-    const params: Record<string, unknown> = {};
-
-    // Session persistent vars (float64) → state.variables
-    for (const [key, value] of Object.entries(this.session.persistentVars)) {
-      params[key] = value;
-    }
-
-    // _persist_ complex data → _ps_* in state.params
-    for (const [key, value] of Object.entries(this.session.persistentData)) {
-      params[`_ps_${key}`] = value;
-    }
-
-    return params;
-  }
-
-  /** Reset all session state */
-  reset(): void {
-    this.session = null;
-  }
-
-  private toSessionData(): SessionData {
-    if (!this.session) throw new Error('No session');
-
-    return {
-      spinsRemaining: this.session.spinsRemaining,
-      spinsPlayed: this.session.spinsPlayed,
-      totalWin: Math.round(this.session.totalWin * 100) / 100,
-      completed: this.session.completed,
-      maxWinReached: this.session.maxWinReached,
-      betAmount: this.session.bet,
-    };
-  }
-}

package/src/lua/SimulationRunner.ts

@@ -1,192 +0,0 @@
-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/SimulationWorker.ts

@@ -1,44 +0,0 @@
-/// <reference types="node" />
-import { parentPort, workerData } from 'worker_threads';
-import { SimulationRunner } from './SimulationRunner';
-import type { SimulationConfig, SimulationResult } from './types';
-
-export interface WorkerMessage {
-  type: 'progress' | 'result' | 'error';
-  progress?: { completed: number; total: number };
-  result?: SimulationResult;
-  error?: string;
-}
-
-export interface WorkerConfig {
-  config: Omit<SimulationConfig, 'onProgress' | 'workerCount'>;
-}
-
-function run() {
-  const { config } = workerData as WorkerConfig;
-
-  const runner = new SimulationRunner({
-    ...config,
-    onProgress: (completed, total) => {
-      parentPort!.postMessage({
-        type: 'progress',
-        progress: { completed, total },
-      } satisfies WorkerMessage);
-    },
-  });
-
-  try {
-    const result = runner.run();
-    parentPort!.postMessage({
-      type: 'result',
-      result,
-    } satisfies WorkerMessage);
-  } catch (e: any) {
-    parentPort!.postMessage({
-      type: 'error',
-      error: e.message ?? String(e),
-    } satisfies WorkerMessage);
-  }
-}
-
-run();

package/src/lua/fengari.d.ts

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