@energy8platform/game-engine 0.10.8 → 0.10.10

package/src/lua/LuaEngine.ts

@@ -1,6 +1,6 @@
 import type { PlayParams, SessionData } from '@energy8platform/game-sdk';
 import type { LuaEngineConfig, LuaPlayResult, GameDefinition } from './types';
-import { LuaEngineAPI, createSeededRng, luaToJS, pushJSValue } from './LuaEngineAPI';
+import { LuaEngineAPI, createSeededRng, luaToJS, pushJSValue, cachedToLuastring } from './LuaEngineAPI';
 import { ActionRouter } from './ActionRouter';
 import { SessionManager } from './SessionManager';
 import { PersistentState } from './PersistentState';
@@ -36,6 +36,11 @@ export class LuaEngine {
   private gameDefinition: GameDefinition;
   private variables: Record<string, number> = {};
   private simulationMode: boolean;
+  /** Reusable state objects to avoid per-iteration allocation */
+  private _stateVars: Record<string, number> = {};
+  private _stateParams: Record<string, unknown> = {};
+  /** Whether the game uses _persist_ keys (detected on first run, cached) */
+  private _hasPersistKeys: boolean | undefined;
 
   constructor(config: LuaEngineConfig) {
     this.gameDefinition = config.gameDefinition;
@@ -103,11 +108,13 @@ export class LuaEngine {
     }
 
     // 3. Build state.variables (matching server's NewGameState + restore)
-    const stateVars: Record<string, number> = {
-      ...DEFAULT_VARIABLES,
-      ...this.variables,
-      bet,
-    };
+    // Reuse pooled object to avoid per-iteration allocation
+    const stateVars = this._stateVars;
+    // Clear previous keys
+    for (const key in stateVars) delete stateVars[key];
+    // Apply defaults, then engine vars, then bet
+    Object.assign(stateVars, DEFAULT_VARIABLES, this.variables);
+    stateVars.bet = bet;
 
     // Load cross-spin persistent state
     this.persistentState.loadIntoVariables(stateVars);
@@ -128,8 +135,10 @@ export class LuaEngine {
       stateVars.free_spins_remaining = this.sessionManager.spinsRemaining;
     }
 
-    // 4. Build state.params
-    const stateParams: Record<string, unknown> = { ...clientParams };
+    // 4. Build state.params (reuse pooled object)
+    const stateParams = this._stateParams;
+    for (const key in stateParams) delete stateParams[key];
+    if (clientParams) Object.assign(stateParams, clientParams);
     stateParams._action = actionName;
 
     // Inject session _ps_* persistent data
@@ -169,10 +178,12 @@ export class LuaEngine {
     const resultVariables = (luaResult.variables ?? {}) as Record<string, number>;
     const spinWin = Math.round(totalWinMultiplier * bet * 100) / 100;
 
-    // Merge result variables into engine variables
+    // Merge ONLY Lua return variables into engine state (not the whole stateVars).
+    // On the server, state.Variables is a temporary object rebuilt each call.
+    // Only the Lua result's `variables` table persists between calls.
+    Object.assign(this.variables, resultVariables);
+    // Also update stateVars for transition evaluation below
     Object.assign(stateVars, resultVariables);
-    this.variables = { ...stateVars };
-    delete this.variables.bet;
 
     // Build client data (everything except special keys)
     const data: Record<string, unknown> = {};
@@ -186,8 +197,8 @@ export class LuaEngine {
     this.sessionManager.storePersistData(data);
     this.persistentState.storeGameData(data);
 
-    // Save cross-spin persistent state
-    this.persistentState.saveFromVariables(this.variables);
+    // Save cross-spin persistent state (from stateVars which has Lua result merged)
+    this.persistentState.saveFromVariables(stateVars);
 
     // Add exposed persistent vars to client data
     const exposedVars = this.persistentState.getExposedVars();
@@ -202,8 +213,8 @@ export class LuaEngine {
       }
     }
 
-    // 8. Evaluate transitions (server: evaluateTransitions)
-    const { rule, nextActions } = this.actionRouter.evaluateTransitions(action, this.variables);
+    // 8. Evaluate transitions (server uses state.Variables which is stateVars)
+    const { rule, nextActions } = this.actionRouter.evaluateTransitions(action, stateVars);
 
     // 9. Determine credit behavior (server: creditNow logic)
     let creditDeferred = action.credit === 'defer' || rule.credit_override === 'defer';
@@ -218,7 +229,7 @@ export class LuaEngine {
 
     if (rule.creates_session && !this.sessionManager.isActive) {
       // CREATE SESSION — initial spin counted (server: createSession includes spinWin)
-      session = this.sessionManager.createSession(rule, this.variables, bet, spinWin, maxWinCap);
+      session = this.sessionManager.createSession(rule, stateVars, bet, spinWin, maxWinCap);
       creditDeferred = true;
       resultTotalWin = spinWin;
 
@@ -228,7 +239,7 @@ export class LuaEngine {
       }
     } else if (this.sessionManager.isActive) {
       // UPDATE SESSION — accumulate win, check completion
-      session = this.sessionManager.updateSession(rule, this.variables, spinWin);
+      session = this.sessionManager.updateSession(rule, stateVars, spinWin);
 
       if (session?.completed) {
         // SESSION COMPLETED — server returns session.TotalWin as result.TotalWin
@@ -262,7 +273,8 @@ export class LuaEngine {
       data,
       nextActions,
       session,
-      variables: { ...this.variables },
+      // In simulation mode, return reference directly (caller only reads, never mutates)
+      variables: this.simulationMode ? this.variables : { ...this.variables },
       creditDeferred,
     };
   }
@@ -290,7 +302,7 @@ export class LuaEngine {
       throw new Error(`Failed to load Lua script: ${err}`);
     }
 
-    lua.lua_getglobal(this.L, to_luastring('execute'));
+    lua.lua_getglobal(this.L, cachedToLuastring('execute'));
     if (lua.lua_type(this.L, -1) !== lua.LUA_TFUNCTION) {
       lua.lua_pop(this.L, 1);
       throw new Error('Lua script must define a global `execute(state)` function');
@@ -304,26 +316,26 @@ export class LuaEngine {
     params: Record<string, unknown>,
     variables: Record<string, number>,
   ): Record<string, unknown> {
-    lua.lua_getglobal(this.L, to_luastring('execute'));
+    lua.lua_getglobal(this.L, cachedToLuastring('execute'));
 
     // Build state table: {stage, action, params, variables}
     lua.lua_createtable(this.L, 0, 4);
 
     // state.stage
-    lua.lua_pushstring(this.L, to_luastring(stage));
-    lua.lua_setfield(this.L, -2, to_luastring('stage'));
+    lua.lua_pushstring(this.L, cachedToLuastring(stage));
+    lua.lua_setfield(this.L, -2, cachedToLuastring('stage'));
 
     // state.action (server sets this at top level)
-    lua.lua_pushstring(this.L, to_luastring(action));
-    lua.lua_setfield(this.L, -2, to_luastring('action'));
+    lua.lua_pushstring(this.L, cachedToLuastring(action));
+    lua.lua_setfield(this.L, -2, cachedToLuastring('action'));
 
     // state.params
     pushJSValue(this.L, params);
-    lua.lua_setfield(this.L, -2, to_luastring('params'));
+    lua.lua_setfield(this.L, -2, cachedToLuastring('params'));
 
     // state.variables
     pushJSValue(this.L, variables);
-    lua.lua_setfield(this.L, -2, to_luastring('variables'));
+    lua.lua_setfield(this.L, -2, cachedToLuastring('variables'));
 
     const status = lua.lua_pcall(this.L, 1, 1, 0);
     if (status !== lua.LUA_OK) {
@@ -336,26 +348,35 @@ export class LuaEngine {
       // Fast path: extract only total_win, variables, _persist_* keys
       const result: Record<string, unknown> = {};
 
-      lua.lua_getfield(this.L, -1, to_luastring('total_win'));
+      lua.lua_getfield(this.L, -1, cachedToLuastring('total_win'));
       result.total_win = lua.lua_type(this.L, -1) === lua.LUA_TNUMBER
         ? lua.lua_tonumber(this.L, -1) : 0;
       lua.lua_pop(this.L, 1);
 
-      lua.lua_getfield(this.L, -1, to_luastring('variables'));
+      lua.lua_getfield(this.L, -1, cachedToLuastring('variables'));
       if (lua.lua_type(this.L, -1) === lua.LUA_TTABLE) {
         result.variables = luaToJS(this.L, -1);
       }
       lua.lua_pop(this.L, 1);
 
-      lua.lua_pushnil(this.L);
-      while (lua.lua_next(this.L, -2) !== 0) {
-        if (lua.lua_type(this.L, -2) === lua.LUA_TSTRING) {
-          const key = to_jsstring(lua.lua_tostring(this.L, -2));
-          if (key.startsWith('_persist_')) {
-            result[key] = luaToJS(this.L, -1);
+      // Scan for _persist_* keys only if the game might use them
+      if (this._hasPersistKeys !== false) {
+        let foundPersist = false;
+        lua.lua_pushnil(this.L);
+        while (lua.lua_next(this.L, -2) !== 0) {
+          if (lua.lua_type(this.L, -2) === lua.LUA_TSTRING) {
+            const key = to_jsstring(lua.lua_tostring(this.L, -2));
+            if (key.startsWith('_persist_')) {
+              result[key] = luaToJS(this.L, -1);
+              foundPersist = true;
+            }
           }
+          lua.lua_pop(this.L, 1);
+        }
+        // After first iteration, cache whether persist keys exist
+        if (this._hasPersistKeys === undefined) {
+          this._hasPersistKeys = foundPersist;
         }
-        lua.lua_pop(this.L, 1);
       }
 
       lua.lua_pop(this.L, 1);

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