@energy8platform/platform-core 0.28.3 → 0.29.0

package/src/lua/SimulationRunner.ts

@@ -1,190 +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 — mirrors v5
-   * ActionDefinition.DebitAmount: bet × (cost_multiplier || 1) when
-   * debit==='bet', otherwise 0. Returns `bet` as a fallback for unknown
-   * actions so RTP math still progresses (we count those as wagered).
-   */
-  private calculateSpinCost(
-    action: string,
-    bet: number,
-    gameDefinition: GameDefinition,
-    _params?: Record<string, unknown>,
-  ): number {
-    const actionDef = gameDefinition.actions[action];
-    if (!actionDef) return bet;
-    if (actionDef.debit !== 'bet') return 0;
-    const mult = actionDef.cost_multiplier;
-    if (typeof mult === 'number' && mult > 0 && mult !== 1) {
-      return bet * mult;
-    }
-    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

@@ -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;
-}

package/src/simulation/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 '../lua/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/simulation/SimulationWorker.ts

@@ -1,44 +0,0 @@
-/// <reference types="node" />
-import { parentPort, workerData } from 'worker_threads';
-import { SimulationRunner } from '../lua/SimulationRunner';
-import type { SimulationConfig, SimulationResult } from '../lua/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();