@energy8platform/game-engine 0.9.2 → 0.10.0

package/src/lua/LuaEngine.ts

@@ -0,0 +1,322 @@
+import type { PlayParams, SessionData } from '@energy8platform/game-sdk';
+import type { LuaEngineConfig, LuaPlayResult, GameDefinition } from './types';
+import { LuaEngineAPI, createSeededRng, luaToJS, pushJSValue } from './LuaEngineAPI';
+import { ActionRouter } from './ActionRouter';
+import { SessionManager } from './SessionManager';
+import { PersistentState } from './PersistentState';
+
+// fengari — Lua 5.3 in pure JavaScript
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+declare const require: (module: string) => any;
+const fengari = require('fengari');
+const { lua, lauxlib, lualib } = fengari;
+const { to_luastring, to_jsstring } = fengari;
+
+/**
+ * Runs Lua game scripts locally, replicating the platform's server-side execution.
+ *
+ * Implements the full lifecycle: action routing → state assembly → Lua execute() →
+ * result extraction → transition evaluation → session management.
+ *
+ * @example
+ * ```ts
+ * const engine = new LuaEngine({
+ *   script: luaSource,
+ *   gameDefinition: { id: 'my-slot', type: 'SLOT', actions: { ... } },
+ * });
+ *
+ * const result = engine.execute({ action: 'spin', bet: 1.0 });
+ * // result.data.matrix, result.totalWin, result.nextActions, etc.
+ * ```
+ */
+export class LuaEngine {
+  private L: any;
+  private api: LuaEngineAPI;
+  private actionRouter: ActionRouter;
+  private sessionManager: SessionManager;
+  private persistentState: PersistentState;
+  private gameDefinition: GameDefinition;
+  private variables: Record<string, number> = {};
+
+  constructor(config: LuaEngineConfig) {
+    this.gameDefinition = config.gameDefinition;
+
+    // Set up RNG
+    const rng = config.seed !== undefined
+      ? createSeededRng(config.seed)
+      : undefined;
+
+    // Initialize sub-managers
+    this.api = new LuaEngineAPI(config.gameDefinition, rng, config.logger);
+    this.actionRouter = new ActionRouter(config.gameDefinition);
+    this.sessionManager = new SessionManager();
+    this.persistentState = new PersistentState(config.gameDefinition.persistent_state);
+
+    // Create Lua state and load standard libraries
+    this.L = lauxlib.luaL_newstate();
+    lualib.luaL_openlibs(this.L);
+
+    // Register engine.* API
+    this.api.register(this.L);
+
+    // Load and compile the script
+    this.loadScript(config.script);
+  }
+
+  /** Current session data (if any) */
+  get session(): SessionData | null {
+    return this.sessionManager.current;
+  }
+
+  /** Current persistent state values */
+  get persistentVars(): Record<string, number> {
+    return { ...this.variables };
+  }
+
+  /**
+   * Execute a play action — the main entry point.
+   * This is what DevBridge calls on each PLAY_REQUEST.
+   */
+  execute(params: PlayParams): LuaPlayResult {
+    const { action: actionName, bet, params: clientParams } = params;
+
+    // 1. Resolve the action definition
+    const action = this.actionRouter.resolveAction(
+      actionName,
+      this.sessionManager.isActive,
+    );
+
+    // 2. Build state.variables
+    const stateVars: Record<string, number> = { ...this.variables, bet };
+
+    // Load cross-spin persistent state
+    this.persistentState.loadIntoVariables(stateVars);
+
+    // Load session persistent vars
+    if (this.sessionManager.isActive) {
+      const sessionParams = this.sessionManager.getPersistentParams();
+      for (const [k, v] of Object.entries(sessionParams)) {
+        if (typeof v === 'number') {
+          stateVars[k] = v;
+        }
+      }
+    }
+
+    // 3. Build state.params
+    const stateParams: Record<string, unknown> = { ...clientParams };
+    stateParams._action = actionName;
+
+    // Inject session _ps_* persistent data
+    if (this.sessionManager.isActive) {
+      const sessionParams = this.sessionManager.getPersistentParams();
+      for (const [k, v] of Object.entries(sessionParams)) {
+        if (typeof v !== 'number') {
+          stateParams[k] = v;
+        }
+      }
+    }
+
+    // Inject cross-spin _ps_* game data
+    const gameDataParams = this.persistentState.getGameDataParams();
+    Object.assign(stateParams, gameDataParams);
+
+    // Handle buy bonus
+    if (action.buy_bonus_mode && this.gameDefinition.buy_bonus) {
+      const mode = this.gameDefinition.buy_bonus.modes[action.buy_bonus_mode];
+      if (mode) {
+        stateParams.buy_bonus = true;
+        stateParams.buy_bonus_mode = action.buy_bonus_mode;
+        stateParams.forced_scatter_count = this.pickFromDistribution(mode.scatter_distribution);
+      }
+    }
+
+    // Handle ante bet
+    if (clientParams?.ante_bet && this.gameDefinition.ante_bet) {
+      stateParams.ante_bet = true;
+    }
+
+    // 4. Build the state table and call Lua execute()
+    const luaResult = this.callLuaExecute(action.stage, stateParams, stateVars);
+
+    // 5. Extract special fields from Lua result
+    const totalWinMultiplier = typeof luaResult.total_win === 'number' ? luaResult.total_win : 0;
+    const resultVariables = (luaResult.variables ?? {}) as Record<string, number>;
+    const totalWin = Math.round(totalWinMultiplier * bet * 100) / 100;
+
+    // Merge result variables into engine variables
+    Object.assign(stateVars, resultVariables);
+    this.variables = { ...stateVars };
+    delete this.variables.bet; // bet is per-spin, not persistent
+
+    // Build client data (everything except special keys)
+    const data: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(luaResult)) {
+      if (key !== 'total_win' && key !== 'variables') {
+        data[key] = value;
+      }
+    }
+
+    // 6. Apply max win cap
+    let cappedWin = totalWin;
+    if (this.gameDefinition.max_win) {
+      const cap = this.calculateMaxWinCap(bet);
+      if (cap !== undefined && totalWin > cap) {
+        cappedWin = cap;
+        this.variables.max_win_reached = 1;
+        data.max_win_reached = true;
+        this.sessionManager.markMaxWinReached();
+      }
+    }
+
+    // 7. Handle _persist_* and _persist_game_* keys
+    this.sessionManager.storePersistData(data);
+    this.persistentState.storeGameData(data);
+
+    // Save cross-spin persistent state
+    this.persistentState.saveFromVariables(this.variables);
+
+    // Add exposed persistent vars to client data
+    const exposedVars = this.persistentState.getExposedVars();
+    if (exposedVars) {
+      data.persistent_state = exposedVars;
+    }
+
+    // Remove _persist_* keys from client data
+    for (const key of Object.keys(data)) {
+      if (key.startsWith('_persist_')) {
+        delete data[key];
+      }
+    }
+
+    // 8. Evaluate transitions
+    const { rule, nextActions } = this.actionRouter.evaluateTransitions(action, this.variables);
+    let creditDeferred = action.credit === 'defer' || rule.credit_override === 'defer';
+    let session = this.sessionManager.current;
+
+    // Handle session creation
+    if (rule.creates_session && !this.sessionManager.isActive) {
+      session = this.sessionManager.createSession(rule, this.variables, bet);
+      creditDeferred = true;
+    }
+    // Handle session update
+    else if (this.sessionManager.isActive) {
+      session = this.sessionManager.updateSession(rule, this.variables, cappedWin);
+
+      // Handle session completion
+      if (rule.complete_session || session?.completed) {
+        const completed = this.sessionManager.completeSession();
+        session = completed.session;
+        creditDeferred = false;
+      }
+    }
+
+    return {
+      totalWin: cappedWin,
+      data,
+      nextActions,
+      session,
+      variables: { ...this.variables },
+      creditDeferred,
+    };
+  }
+
+  /** Reset all state (sessions, persistent vars, variables) */
+  reset(): void {
+    this.variables = {};
+    this.sessionManager.reset();
+    this.persistentState.reset();
+  }
+
+  /** Destroy the Lua VM */
+  destroy(): void {
+    if (this.L) {
+      lua.lua_close(this.L);
+      this.L = null;
+    }
+  }
+
+  // ─── Private ──────────────────────────────────────────
+
+  private loadScript(source: string): void {
+    const status = lauxlib.luaL_dostring(this.L, to_luastring(source));
+    if (status !== lua.LUA_OK) {
+      const err = to_jsstring(lua.lua_tostring(this.L, -1));
+      lua.lua_pop(this.L, 1);
+      throw new Error(`Failed to load Lua script: ${err}`);
+    }
+
+    // Verify that execute() function exists
+    lua.lua_getglobal(this.L, to_luastring('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');
+    }
+    lua.lua_pop(this.L, 1);
+  }
+
+  private callLuaExecute(
+    stage: string,
+    params: Record<string, unknown>,
+    variables: Record<string, number>,
+  ): Record<string, unknown> {
+    // Push the execute function
+    lua.lua_getglobal(this.L, to_luastring('execute'));
+
+    // Build and push the state table
+    lua.lua_createtable(this.L, 0, 3);
+
+    // state.stage
+    lua.lua_pushstring(this.L, to_luastring(stage));
+    lua.lua_setfield(this.L, -2, to_luastring('stage'));
+
+    // state.params
+    pushJSValue(this.L, params);
+    lua.lua_setfield(this.L, -2, to_luastring('params'));
+
+    // state.variables
+    pushJSValue(this.L, variables);
+    lua.lua_setfield(this.L, -2, to_luastring('variables'));
+
+    // Call execute(state) → 1 result
+    const status = lua.lua_pcall(this.L, 1, 1, 0);
+    if (status !== lua.LUA_OK) {
+      const err = to_jsstring(lua.lua_tostring(this.L, -1));
+      lua.lua_pop(this.L, 1);
+      throw new Error(`Lua execute() failed: ${err}`);
+    }
+
+    // Marshal result table to JS
+    const result = luaToJS(this.L, -1);
+    lua.lua_pop(this.L, 1);
+
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+      throw new Error('Lua execute() must return a table');
+    }
+
+    return result as Record<string, unknown>;
+  }
+
+  private calculateMaxWinCap(bet: number): number | undefined {
+    const mw = this.gameDefinition.max_win;
+    if (!mw) return undefined;
+
+    const caps: number[] = [];
+    if (mw.multiplier !== undefined) caps.push(bet * mw.multiplier);
+    if (mw.fixed !== undefined) caps.push(mw.fixed);
+
+    return caps.length > 0 ? Math.min(...caps) : undefined;
+  }
+
+  private pickFromDistribution(distribution: Record<string, number>): number {
+    const entries = Object.entries(distribution);
+    const totalWeight = entries.reduce((sum, [, w]) => sum + w, 0);
+    let roll = this.api.randomFloat() * totalWeight;
+
+    for (const [value, weight] of entries) {
+      roll -= weight;
+      if (roll < 0) return parseInt(value, 10);
+    }
+
+    return parseInt(entries[entries.length - 1][0], 10);
+  }
+}

package/src/lua/LuaEngineAPI.ts

@@ -0,0 +1,305 @@
+import type { GameDefinition } from './types';
+
+// fengari is a CJS module — use dynamic import workaround for ESM compatibility
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+declare const require: (module: string) => any;
+const fengari = require('fengari');
+const { lua, lauxlib } = fengari;
+const { to_luastring, to_jsstring } = fengari;
+
+export type RngFunction = () => number;
+
+/**
+ * Seeded xoshiro128** PRNG for deterministic simulation/replay.
+ * Period: 2^128 - 1
+ */
+export function createSeededRng(seed: number): RngFunction {
+  let s0 = (seed >>> 0) | 1;
+  let s1 = (seed * 1103515245 + 12345) >>> 0;
+  let s2 = (seed * 6364136223846793005 + 1442695040888963407) >>> 0;
+  let s3 = (seed * 1442695040888963407 + 6364136223846793005) >>> 0;
+
+  return (): number => {
+    const result = (((s1 * 5) << 7) * 9) >>> 0;
+    const t = s1 << 9;
+
+    s2 ^= s0;
+    s3 ^= s1;
+    s1 ^= s2;
+    s0 ^= s3;
+    s2 ^= t;
+    s3 = ((s3 << 11) | (s3 >>> 21)) >>> 0;
+
+    return result / 4294967296;
+  };
+}
+
+/**
+ * Implements and registers all platform `engine.*` functions into a Lua state.
+ */
+export class LuaEngineAPI {
+  private rng: RngFunction;
+  private logger: (level: string, msg: string) => void;
+  private gameDefinition: GameDefinition;
+
+  constructor(
+    gameDefinition: GameDefinition,
+    rng?: RngFunction,
+    logger?: (level: string, msg: string) => void,
+  ) {
+    this.gameDefinition = gameDefinition;
+    this.rng = rng ?? Math.random;
+    this.logger = logger ?? ((level, msg) => {
+      const fn = level === 'error' ? console.error
+        : level === 'warn' ? console.warn
+        : level === 'debug' ? console.debug
+        : console.log;
+      fn(`[Lua:${level}] ${msg}`);
+    });
+  }
+
+  /** Register `engine` global table on the Lua state */
+  register(L: any): void {
+    // Create the `engine` table
+    lua.lua_newtable(L);
+
+    this.registerFunction(L, 'random', (LS: any) => {
+      const min = lauxlib.luaL_checkinteger(LS, 1);
+      const max = lauxlib.luaL_checkinteger(LS, 2);
+      const result = this.random(Number(min), Number(max));
+      lua.lua_pushinteger(LS, result);
+      return 1;
+    });
+
+    this.registerFunction(L, 'random_float', (LS: any) => {
+      lua.lua_pushnumber(LS, this.randomFloat());
+      return 1;
+    });
+
+    this.registerFunction(L, 'random_weighted', (LS: any) => {
+      lauxlib.luaL_checktype(LS, 1, lua.LUA_TTABLE);
+      const weights: number[] = [];
+      const len = lua.lua_rawlen(LS, 1);
+      for (let i = 1; i <= len; i++) {
+        lua.lua_rawgeti(LS, 1, i);
+        weights.push(lua.lua_tonumber(LS, -1));
+        lua.lua_pop(LS, 1);
+      }
+      const result = this.randomWeighted(weights);
+      lua.lua_pushinteger(LS, result);
+      return 1;
+    });
+
+    this.registerFunction(L, 'shuffle', (LS: any) => {
+      lauxlib.luaL_checktype(LS, 1, lua.LUA_TTABLE);
+      const arr: unknown[] = [];
+      const len = lua.lua_rawlen(LS, 1);
+      for (let i = 1; i <= len; i++) {
+        lua.lua_rawgeti(LS, 1, i);
+        arr.push(luaToJS(LS, -1));
+        lua.lua_pop(LS, 1);
+      }
+      const shuffled = this.shuffle(arr);
+      pushJSArray(LS, shuffled);
+      return 1;
+    });
+
+    this.registerFunction(L, 'log', (LS: any) => {
+      const level = to_jsstring(lauxlib.luaL_checkstring(LS, 1));
+      const msg = to_jsstring(lauxlib.luaL_checkstring(LS, 2));
+      this.logger(level, msg);
+      return 0;
+    });
+
+    this.registerFunction(L, 'get_config', (LS: any) => {
+      const config = this.getConfig();
+      pushJSObject(LS, config);
+      return 1;
+    });
+
+    // Set the table as global `engine`
+    lua.lua_setglobal(L, to_luastring('engine'));
+  }
+
+  // ─── engine.* implementations ─────────────────────────
+
+  random(min: number, max: number): number {
+    return Math.floor(this.rng() * (max - min + 1)) + min;
+  }
+
+  randomFloat(): number {
+    return this.rng();
+  }
+
+  randomWeighted(weights: number[]): number {
+    const totalWeight = weights.reduce((a, b) => a + b, 0);
+    let roll = this.rng() * totalWeight;
+    for (let i = 0; i < weights.length; i++) {
+      roll -= weights[i];
+      if (roll < 0) return i + 1; // 1-based index
+    }
+    return weights.length; // fallback to last
+  }
+
+  shuffle<T>(arr: T[]): T[] {
+    const copy = [...arr];
+    for (let i = copy.length - 1; i > 0; i--) {
+      const j = Math.floor(this.rng() * (i + 1));
+      [copy[i], copy[j]] = [copy[j], copy[i]];
+    }
+    return copy;
+  }
+
+  getConfig(): Record<string, unknown> {
+    const def = this.gameDefinition;
+    let betLevels: number[] = [];
+    if (Array.isArray(def.bet_levels)) {
+      betLevels = def.bet_levels;
+    } else if (def.bet_levels && 'levels' in def.bet_levels && def.bet_levels.levels) {
+      betLevels = def.bet_levels.levels;
+    }
+    return {
+      id: def.id,
+      type: def.type,
+      bet_levels: betLevels,
+    };
+  }
+
+  // ─── Helpers ──────────────────────────────────────────
+
+  private registerFunction(L: any, name: string, fn: (L: any) => number): void {
+    lua.lua_pushcfunction(L, fn);
+    lua.lua_setfield(L, -2, to_luastring(name));
+  }
+}
+
+// ─── Lua ↔ JS marshalling ───────────────────────────────
+
+/** Read a Lua value at the given stack index and return its JS equivalent */
+export function luaToJS(L: any, idx: number): unknown {
+  const type = lua.lua_type(L, idx);
+
+  switch (type) {
+    case lua.LUA_TNIL:
+      return null;
+
+    case lua.LUA_TBOOLEAN:
+      return lua.lua_toboolean(L, idx);
+
+    case lua.LUA_TNUMBER:
+      if (lua.lua_isinteger(L, idx)) {
+        return Number(lua.lua_tointeger(L, idx));
+      }
+      return lua.lua_tonumber(L, idx);
+
+    case lua.LUA_TSTRING:
+      return to_jsstring(lua.lua_tostring(L, idx));
+
+    case lua.LUA_TTABLE:
+      return luaTableToJS(L, idx);
+
+    default:
+      return null;
+  }
+}
+
+/** Convert a Lua table to a JS object or array */
+function luaTableToJS(L: any, idx: number): Record<string, unknown> | unknown[] {
+  // Normalize index to absolute
+  if (idx < 0) idx = lua.lua_gettop(L) + idx + 1;
+
+  // Check if it's an array (sequential integer keys starting at 1)
+  const len = lua.lua_rawlen(L, idx);
+  if (len > 0) {
+    // Verify it's a pure array by checking key 1 exists
+    lua.lua_rawgeti(L, idx, 1);
+    const hasFirst = lua.lua_type(L, -1) !== lua.LUA_TNIL;
+    lua.lua_pop(L, 1);
+
+    if (hasFirst) {
+      // Check if there are also string keys (mixed table)
+      let hasStringKeys = false;
+      lua.lua_pushnil(L);
+      while (lua.lua_next(L, idx) !== 0) {
+        lua.lua_pop(L, 1); // pop value
+        if (lua.lua_type(L, -1) === lua.LUA_TSTRING) {
+          hasStringKeys = true;
+          lua.lua_pop(L, 1); // pop key
+          break;
+        }
+      }
+
+      if (!hasStringKeys) {
+        // Pure array
+        const arr: unknown[] = [];
+        for (let i = 1; i <= len; i++) {
+          lua.lua_rawgeti(L, idx, i);
+          arr.push(luaToJS(L, -1));
+          lua.lua_pop(L, 1);
+        }
+        return arr;
+      }
+    }
+  }
+
+  // Object (or mixed table)
+  const obj: Record<string, unknown> = {};
+  lua.lua_pushnil(L);
+  while (lua.lua_next(L, idx) !== 0) {
+    const keyType = lua.lua_type(L, -2);
+    let key: string;
+    if (keyType === lua.LUA_TSTRING) {
+      key = to_jsstring(lua.lua_tostring(L, -2));
+    } else if (keyType === lua.LUA_TNUMBER) {
+      key = String(lua.lua_tonumber(L, -2));
+    } else {
+      lua.lua_pop(L, 1);
+      continue;
+    }
+    obj[key] = luaToJS(L, -1);
+    lua.lua_pop(L, 1);
+  }
+  return obj;
+}
+
+/** Push a JS value onto the Lua stack */
+export function pushJSValue(L: any, value: unknown): void {
+  if (value === null || value === undefined) {
+    lua.lua_pushnil(L);
+  } else if (typeof value === 'boolean') {
+    lua.lua_pushboolean(L, value ? 1 : 0);
+  } else if (typeof value === 'number') {
+    if (Number.isInteger(value)) {
+      lua.lua_pushinteger(L, value);
+    } else {
+      lua.lua_pushnumber(L, value);
+    }
+  } else if (typeof value === 'string') {
+    lua.lua_pushstring(L, to_luastring(value));
+  } else if (Array.isArray(value)) {
+    pushJSArray(L, value);
+  } else if (typeof value === 'object') {
+    pushJSObject(L, value as Record<string, unknown>);
+  } else {
+    lua.lua_pushnil(L);
+  }
+}
+
+/** Push a JS array as a Lua table (1-based) */
+function pushJSArray(L: any, arr: unknown[]): void {
+  lua.lua_createtable(L, arr.length, 0);
+  for (let i = 0; i < arr.length; i++) {
+    pushJSValue(L, arr[i]);
+    lua.lua_rawseti(L, -2, i + 1);
+  }
+}
+
+/** Push a JS object as a Lua table */
+function pushJSObject(L: any, obj: Record<string, unknown>): void {
+  const keys = Object.keys(obj);
+  lua.lua_createtable(L, 0, keys.length);
+  for (const key of keys) {
+    pushJSValue(L, obj[key]);
+    lua.lua_setfield(L, -2, to_luastring(key));
+  }
+}

package/src/lua/PersistentState.ts

@@ -0,0 +1,80 @@
+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 = {};
+  }
+}