@energy8platform/platform-core 0.16.0

package/src/lua/LuaEngineAPI.ts

@@ -0,0 +1,314 @@
+import type { GameDefinition } from './types';
+import fengari from 'fengari';
+
+const { lua, lauxlib } = fengari;
+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
+ */
+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, cachedToLuastring(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, cachedToLuastring(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 = {};
+  }
+}

package/src/lua/SessionManager.ts

@@ -0,0 +1,227 @@
+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;
+  maxWinCap: number | undefined;
+  spinsVarName: string | undefined;
+  persistentVarNames: string[];
+  persistentVars: Record<string, number>;
+  persistentData: Record<string, unknown>;
+}
+
+const MAX_SESSION_SPINS = 200;
+
+/**
+ * Manages session lifecycle matching the platform server behavior:
+ * - createSession: initial spin counted (spinsPlayed=1, totalWin=spinWin)
+ * - updateSession: accumulates win, decrements spins, checks max win cap on session level
+ * - completeSession: returns cumulative totalWin, cleans up session vars
+ * - Safety cap: 200 spins max per session
+ */
+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;
+  }
+
+  /** Get the fixed bet amount from the session (server uses session bet, not request bet) */
+  get sessionBet(): number | undefined {
+    return this.session?.bet;
+  }
+
+  /** Get spinsVarName to restore free_spins_remaining into variables */
+  get spinsVarName(): string | undefined {
+    return this.session?.spinsVarName;
+  }
+
+  get spinsRemaining(): number {
+    return this.session?.spinsRemaining ?? 0;
+  }
+
+  /**
+   * Create a new session from a transition rule.
+   * Server behavior: initial spin is already counted (spinsPlayed=1, totalWin includes spinWin).
+   */
+  createSession(
+    rule: TransitionRule,
+    variables: Record<string, number>,
+    bet: number,
+    spinWin: number,
+    maxWinCap: number | undefined,
+  ): SessionData {
+    let spinsRemaining = -1;
+    let spinsVarName: string | undefined;
+    if (rule.session_config?.total_spins_var) {
+      spinsVarName = rule.session_config.total_spins_var;
+      spinsRemaining = variables[spinsVarName] ?? -1;
+    }
+
+    const persistentVarNames: string[] = rule.session_config?.persistent_vars ?? [];
+    const persistentVars: Record<string, number> = {};
+    for (const varName of persistentVarNames) {
+      persistentVars[varName] = variables[varName] ?? 0;
+    }
+
+    this.session = {
+      spinsRemaining,
+      spinsPlayed: 1, // initial spin counts
+      totalWin: spinWin, // initial spin win included
+      completed: false,
+      maxWinReached: false,
+      bet,
+      maxWinCap,
+      spinsVarName,
+      persistentVarNames,
+      persistentVars,
+      persistentData: {},
+    };
+
+    return this.toSessionData();
+  }
+
+  /**
+   * Update session after a bonus spin.
+   * Server behavior: accumulate win, decrement spins, check retrigger, check max win cap,
+   * safety cap at 200 spins.
+   */
+  updateSession(
+    rule: TransitionRule,
+    variables: Record<string, number>,
+    spinWin: number,
+  ): SessionData {
+    if (!this.session) throw new Error('No active session');
+
+    // Accumulate win and count spin
+    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;
+      }
+    }
+
+    // Safety cap: server limits sessions to 200 spins
+    if (this.session.spinsPlayed >= MAX_SESSION_SPINS) {
+      this.session.spinsRemaining = 0;
+    }
+
+    // Update session persistent vars from current variables
+    for (const varName of this.session.persistentVarNames) {
+      if (varName in variables) {
+        this.session.persistentVars[varName] = variables[varName];
+      }
+    }
+
+    // Check max win cap (on session level, not per spin)
+    if (this.session.maxWinCap !== undefined && this.session.totalWin >= this.session.maxWinCap) {
+      this.session.totalWin = this.session.maxWinCap;
+      this.session.spinsRemaining = 0;
+      this.session.maxWinReached = true;
+    }
+
+    // Auto-complete if spins exhausted or explicit complete
+    if (this.session.spinsRemaining === 0 || rule.complete_session) {
+      this.session.completed = true;
+    }
+
+    return this.toSessionData();
+  }
+
+  /**
+   * Complete the session explicitly.
+   * Returns cumulative totalWin and list of session-scoped var names to clean up.
+   */
+  completeSession(): { totalWin: number; session: SessionData; sessionVarNames: string[] } {
+    if (!this.session) throw new Error('No active session to complete');
+
+    this.session.completed = true;
+    const totalWin = this.session.totalWin;
+    const session = this.toSessionData();
+    const sessionVarNames = [...this.session.persistentVarNames];
+
+    this.session = null;
+
+    return { totalWin, session, sessionVarNames };
+  }
+
+  /** 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 persistent params to inject into next execute() call */
+  getPersistentParams(): Record<string, unknown> {
+    if (!this.session) return {};
+
+    const params: Record<string, unknown> = {};
+
+    // Session persistent vars (float64) → state.variables
+    for (const [key, value] of Object.entries(this.session.persistentVars)) {
+      params[key] = value;
+    }
+
+    // _persist_ complex data → _ps_* in state.params
+    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,
+    };
+  }
+}