@energy8platform/game-engine 0.10.9 → 0.10.10

package/src/lua/LuaEngineAPI.ts

@@ -6,6 +6,18 @@ const { to_luastring, to_jsstring } = fengari;
 
 export type RngFunction = () => number;
 
+/** Cache for to_luastring() results — avoids re-encoding the same keys every iteration */
+const luaStringCache = new Map<string, Uint8Array>();
+
+export function cachedToLuastring(s: string): Uint8Array {
+  let cached = luaStringCache.get(s);
+  if (!cached) {
+    cached = to_luastring(s);
+    luaStringCache.set(s, cached);
+  }
+  return cached;
+}
+
 /**
  * Seeded xoshiro128** PRNG for deterministic simulation/replay.
  * Period: 2^128 - 1
@@ -272,7 +284,7 @@ export function pushJSValue(L: any, value: unknown): void {
       lua.lua_pushnumber(L, value);
     }
   } else if (typeof value === 'string') {
-    lua.lua_pushstring(L, to_luastring(value));
+    lua.lua_pushstring(L, cachedToLuastring(value));
   } else if (Array.isArray(value)) {
     pushJSArray(L, value);
   } else if (typeof value === 'object') {
@@ -297,6 +309,6 @@ function pushJSObject(L: any, obj: Record<string, unknown>): void {
   lua.lua_createtable(L, 0, keys.length);
   for (const key of keys) {
     pushJSValue(L, obj[key]);
-    lua.lua_setfield(L, -2, to_luastring(key));
+    lua.lua_setfield(L, -2, cachedToLuastring(key));
   }
 }

package/src/lua/ParallelSimulationRunner.ts

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

@@ -132,6 +132,7 @@ export class SimulationRunner {
       maxWinHits,
       bonusTriggered,
       bonusSpinsPlayed,
+      _raw: { totalWagered, totalWon, baseGameWin, bonusWin, hits },
     };
   }
 

package/src/lua/SimulationWorker.ts

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

@@ -4,6 +4,7 @@ export { ActionRouter, evaluateCondition } from './ActionRouter';
 export { SessionManager } from './SessionManager';
 export { PersistentState } from './PersistentState';
 export { SimulationRunner, formatSimulationResult } from './SimulationRunner';
+export { ParallelSimulationRunner } from './ParallelSimulationRunner';
 export type {
   GameDefinition,
   ActionDefinition,
@@ -19,4 +20,5 @@ export type {
   BetLevelsConfig,
   SimulationConfig,
   SimulationResult,
+  SimulationRawAccumulators,
 } from './types';

package/src/lua/types.ts

@@ -114,6 +114,8 @@ export interface SimulationConfig {
   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 {
@@ -129,6 +131,16 @@ export interface SimulationResult {
   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 };