@energy8platform/game-engine 0.9.2 → 0.10.1

package/src/lua/SessionManager.ts

@@ -0,0 +1,178 @@
+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;
+  persistentVars: Record<string, number>;
+  persistentData: Record<string, unknown>;
+}
+
+/**
+ * Manages session lifecycle: creation, spin counting, retriggers, and completion.
+ * Handles both slot sessions (fixed spin count) and table game sessions (unlimited).
+ * Also manages _persist_ data roundtrip between Lua calls.
+ */
+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;
+  }
+
+  /** Create a new session from a transition rule */
+  createSession(
+    rule: TransitionRule,
+    variables: Record<string, number>,
+    bet: number,
+  ): SessionData {
+    let spinsRemaining = -1; // unlimited by default
+    if (rule.session_config?.total_spins_var) {
+      const varName = rule.session_config.total_spins_var;
+      spinsRemaining = variables[varName] ?? -1;
+    }
+
+    const persistentVars: Record<string, number> = {};
+    if (rule.session_config?.persistent_vars) {
+      for (const varName of rule.session_config.persistent_vars) {
+        persistentVars[varName] = variables[varName] ?? 0;
+      }
+    }
+
+    this.session = {
+      spinsRemaining,
+      spinsPlayed: 0,
+      totalWin: 0,
+      completed: false,
+      maxWinReached: false,
+      bet,
+      persistentVars,
+      persistentData: {},
+    };
+
+    return this.toSessionData();
+  }
+
+  /** Update session after a spin: decrement counter, accumulate win, handle retrigger */
+  updateSession(
+    rule: TransitionRule,
+    variables: Record<string, number>,
+    spinWin: number,
+  ): SessionData {
+    if (!this.session) throw new Error('No active session');
+
+    // Accumulate win
+    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;
+      }
+    }
+
+    // Update persistent vars
+    if (this.session.persistentVars) {
+      for (const key of Object.keys(this.session.persistentVars)) {
+        if (key in variables) {
+          this.session.persistentVars[key] = variables[key];
+        }
+      }
+    }
+
+    // Auto-complete if spins exhausted
+    if (this.session.spinsRemaining === 0) {
+      this.session.completed = true;
+    }
+
+    return this.toSessionData();
+  }
+
+  /** Complete the session, return accumulated totalWin */
+  completeSession(): { totalWin: number; session: SessionData } {
+    if (!this.session) throw new Error('No active session to complete');
+
+    this.session.completed = true;
+    const totalWin = this.session.totalWin;
+    const session = this.toSessionData();
+
+    return { totalWin, session };
+  }
+
+  /** 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 _ps_* params to inject into next execute() call */
+  getPersistentParams(): Record<string, unknown> {
+    if (!this.session) return {};
+
+    const params: Record<string, unknown> = {};
+
+    // Session persistent vars (float64)
+    for (const [key, value] of Object.entries(this.session.persistentVars)) {
+      params[key] = value;
+    }
+
+    // _persist_ complex data → _ps_*
+    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

@@ -0,0 +1,195 @@
+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: () => {}, // suppress Lua logs during simulation
+    });
+
+    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;
+
+        // Execute the starting action
+        const result = engine.execute({
+          action: startAction,
+          bet,
+          params,
+        });
+
+        const baseWin = result.totalWin;
+        roundWin += baseWin;
+
+        // If a bonus session was created, play through it
+        if (result.session && !result.session.completed) {
+          bonusTriggered++;
+
+          // Find the bonus action from nextActions (different from startAction)
+          const bonusAction = result.nextActions.find(a => a !== startAction)
+            ?? result.nextActions[0];
+
+          // Play bonus spins until session completes
+          let bonusSessionWin = 0;
+          let safetyLimit = 10_000;
+          let lastResult = result;
+
+          while (lastResult.session && !lastResult.session.completed && safetyLimit-- > 0) {
+            lastResult = engine.execute({
+              action: bonusAction,
+              bet,
+            });
+            bonusSessionWin += lastResult.totalWin;
+            bonusSpinsPlayed++;
+          }
+
+          bonusWin += bonusSessionWin;
+          roundWin += bonusSessionWin;
+        }
+
+        baseGameWin += baseWin;
+        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,
+    };
+  }
+
+  /** 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/index.ts

@@ -0,0 +1,22 @@
+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,
+} from './types';

package/src/lua/types.ts

@@ -0,0 +1,132 @@
+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;
+  scatter_distribution: Record<string, number>;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+export type { SessionData, PlayParams };

package/src/vite/index.ts

@@ -88,6 +88,35 @@ await import('${entrySrc}');
   };
 }
 
+// ─── Lua Plugin ─────────────────────────────────────────
+
+/**
+ * Vite plugin that enables importing `.lua` files as raw strings
+ * and triggers a full page reload on `.lua` file changes.
+ */
+function luaPlugin(): Plugin {
+  return {
+    name: 'game-engine:lua',
+    apply: 'serve',
+
+    transform(code: string, id: string) {
+      if (id.endsWith('.lua')) {
+        return {
+          code: `export default ${JSON.stringify(code)};`,
+          map: null,
+        };
+      }
+    },
+
+    handleHotUpdate({ file, server }: { file: string; server: any }) {
+      if (file.endsWith('.lua')) {
+        server.ws.send({ type: 'full-reload' });
+        return [];
+      }
+    },
+  };
+}
+
 // ─── defineGameConfig ────────────────────────────────────
 
 /**
@@ -116,10 +145,19 @@ export function defineGameConfig(config: GameConfig = {}): UserConfig {
   if (config.devBridge) {
     const configPath = config.devBridgeConfig ?? './dev.config';
     plugins.push(devBridgePlugin(configPath));
+    plugins.push(luaPlugin());
   }
 
   const userVite = config.vite ?? {};
 
+  // fengari (Lua 5.3 in JS) is a CJS Node.js package that references `process`
+  // and `require('os')` at module level. Provide shims so it works in the browser.
+  const fengariShims: Record<string, string> = config.devBridge ? {
+    'process.versions.node': 'undefined',
+    'process.env': '({})',
+    'process.platform': '"browser"',
+  } : {};
+
   return {
     base: config.base ?? '/',
 
@@ -128,6 +166,11 @@ export function defineGameConfig(config: GameConfig = {}): UserConfig {
       ...((userVite.plugins as Plugin[]) ?? []),
     ],
 
+    define: {
+      ...fengariShims,
+      ...(userVite as Record<string, any>).define,
+    },
+
     build: {
       target: 'esnext',
       assetsInlineLimit: 8192,