@energy8platform/game-engine 0.15.2 → 0.16.0

package/src/lua/LuaEngineAPI.ts

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

@@ -1,367 +0,0 @@
-import { spawn } from 'child_process';
-import { writeFile, unlink } from 'fs/promises';
-import { accessSync, constants as fsConstants } from 'fs';
-import { join, dirname } from 'path';
-import { tmpdir } from 'os';
-import { randomBytes } from 'crypto';
-import { execSync } from 'child_process';
-import { fileURLToPath } from 'url';
-import type { GameDefinition, SimulationResult } from './types';
-
-// ─── Types ──────────────────────────────────────────────
-
-export interface NativeSimulationConfig {
-  /** Path to native simulation binary */
-  binaryPath: string;
-  /** Lua script source code */
-  script: string;
-  /** Platform game definition */
-  gameDefinition: GameDefinition;
-  /** Number of iterations */
-  iterations: number;
-  /** Bet amount */
-  bet: number;
-  /** Action to simulate (default: auto-detect by binary) */
-  action?: string;
-  /** Action params (buy_bonus, ante_bet, etc.) */
-  params?: Record<string, unknown>;
-  /** Progress callback */
-  onProgress?: (completed: number, total: number) => void;
-}
-
-export interface StageStats {
-  totalWin: number;
-  spinCount: number;
-  hitCount: number;
-  maxWin: number;
-  rtp: number;
-  perSpinRtp: number;
-  hitFrequency: number;
-  avgWin: number;
-}
-
-export interface DistributionBucket {
-  label: string;
-  count: number;
-  pct: number;
-}
-
-export interface NativeSimulationResult extends SimulationResult {
-  /** Iterations per second */
-  speed?: number;
-  /** Number of parallel workers used */
-  workersUsed?: number;
-  /** Per-stage breakdown */
-  perStage?: Record<string, StageStats>;
-  /** Win distribution histogram */
-  winDistribution?: DistributionBucket[];
-}
-
-// ─── Go JSON output shape (snake_case) ──────────────────
-
-interface GoSimulationOutput {
-  game_id: string;
-  speed: number;
-  total_rtp: number;
-  hit_frequency: number;
-  max_win: number;
-  max_win_hits: number;
-  total_bet: number;
-  total_win: number;
-  iterations: number;
-  workers_used: number;
-  duration_sec: number;
-  bonus_triggered: number;
-  bonus_spins_total: number;
-  per_stage_stats?: Record<string, {
-    total_win: number;
-    spin_count: number;
-    hit_count: number;
-    max_win: number;
-    rtp: number;
-    per_spin_rtp: number;
-    hit_frequency: number;
-    avg_win: number;
-  }>;
-  win_distribution?: Array<{
-    label: string;
-    count: number;
-    pct: number;
-  }>;
-}
-
-// ─── Runner ─────────────────────────────────────────────
-
-export class NativeSimulationRunner {
-  private config: NativeSimulationConfig;
-
-  constructor(config: NativeSimulationConfig) {
-    this.config = config;
-  }
-
-  async run(): Promise<NativeSimulationResult> {
-    const { binaryPath, script, gameDefinition, iterations, bet, action, params } = this.config;
-    const id = randomBytes(8).toString('hex');
-    const tmpDir = tmpdir();
-    const luaPath = join(tmpDir, `sim-${id}.lua`);
-    const configPath = join(tmpDir, `sim-${id}.json`);
-
-    try {
-      // Write temp files
-      await Promise.all([
-        writeFile(luaPath, script, 'utf-8'),
-        writeFile(configPath, JSON.stringify({ ...gameDefinition, script_path: luaPath }), 'utf-8'),
-      ]);
-
-      // Build CLI args
-      const args = [
-        '-config', configPath,
-        '-iterations', String(iterations),
-        '-bet', String(bet),
-        '-format', 'json',
-      ];
-      if (action) {
-        args.push('-action', action);
-      }
-      if (params && Object.keys(params).length > 0) {
-        args.push('-params', JSON.stringify(params));
-      }
-
-      // Execute binary
-      const output = await this.exec(binaryPath, args);
-
-      // Parse JSON output
-      const json: GoSimulationOutput = JSON.parse(output);
-      return mapGoResult(json);
-    } finally {
-      // Cleanup temp files
-      await Promise.allSettled([unlink(luaPath), unlink(configPath)]);
-    }
-  }
-
-  private exec(binary: string, args: string[]): Promise<string> {
-    return new Promise((resolve, reject) => {
-      const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
-
-      let stdout = '';
-      let stderr = '';
-
-      child.stdout.on('data', (chunk: Buffer) => {
-        stdout += chunk.toString();
-      });
-
-      child.stderr.on('data', (chunk: Buffer) => {
-        stderr += chunk.toString();
-      });
-
-      child.on('error', (err) => {
-        reject(new Error(`Failed to execute simulation binary: ${err.message}`));
-      });
-
-      child.on('close', (code) => {
-        if (code !== 0) {
-          reject(new Error(`Simulation binary exited with code ${code}: ${stderr.trim()}`));
-        } else {
-          resolve(stdout);
-        }
-      });
-    });
-  }
-}
-
-// ─── Result mapping ─────────────────────────────────────
-
-function mapGoResult(json: GoSimulationOutput): NativeSimulationResult {
-  const baseStage = json.per_stage_stats?.base_game;
-  const baseGameRtp = baseStage?.rtp ?? 0;
-  const baseGameWin = baseStage?.total_win ?? 0;
-
-  const perStage = json.per_stage_stats
-    ? Object.fromEntries(
-        Object.entries(json.per_stage_stats).map(([key, s]) => [
-          key,
-          {
-            totalWin: s.total_win,
-            spinCount: s.spin_count,
-            hitCount: s.hit_count,
-            maxWin: s.max_win,
-            rtp: s.rtp,
-            perSpinRtp: s.per_spin_rtp,
-            hitFrequency: s.hit_frequency,
-            avgWin: s.avg_win,
-          },
-        ]),
-      )
-    : undefined;
-
-  return {
-    gameId: json.game_id,
-    action: 'spin',
-    iterations: json.iterations,
-    durationMs: Math.round(json.duration_sec * 1000),
-    totalRtp: json.total_rtp,
-    baseGameRtp,
-    bonusRtp: json.total_rtp - baseGameRtp,
-    hitFrequency: json.hit_frequency,
-    maxWin: json.max_win,
-    maxWinHits: json.max_win_hits,
-    bonusTriggered: json.bonus_triggered,
-    bonusSpinsPlayed: json.bonus_spins_total,
-    speed: json.speed,
-    workersUsed: json.workers_used,
-    perStage,
-    winDistribution: json.win_distribution,
-    _raw: {
-      totalWagered: json.total_bet,
-      totalWon: json.total_win,
-      baseGameWin,
-      bonusWin: json.total_win - baseGameWin,
-      hits: json.iterations > 0 ? Math.round((json.hit_frequency * json.iterations) / 100) : 0,
-    },
-  };
-}
-
-// ─── Binary discovery ───────────────────────────────────
-
-/**
- * Search for a native simulation binary in standard locations.
- * Returns the absolute path if found, null otherwise.
- */
-export function findNativeBinary(baseDir?: string): string | null {
-  // 1. Explicit env var
-  const envPath = process.env.SIMULATE_BINARY;
-  if (envPath && isExecutable(envPath)) {
-    return envPath;
-  }
-
-  const platform = process.platform; // darwin, linux, win32
-  const nodeArch = process.arch; // arm64, x64
-  const goArch = nodeArch === 'x64' ? 'amd64' : nodeArch;
-  const goPlatform = platform === 'win32' ? 'windows' : platform;
-  const ext = platform === 'win32' ? '.exe' : '';
-
-  const names = [
-    `simulate-${goPlatform}-${goArch}${ext}`,
-    `simulation-${goPlatform}-${goArch}${ext}`,
-    `simulate${ext}`,
-    `simulation${ext}`,
-  ];
-
-  // Search directories: user's project first, then this package's bin/
-  const searchDirs: string[] = [];
-  if (baseDir) searchDirs.push(baseDir);
-
-  // This package's root (where postinstall downloads the binary)
-  try {
-    const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
-    if (!searchDirs.includes(pkgRoot)) searchDirs.push(pkgRoot);
-  } catch {
-    // fallback for CJS
-    if (typeof __dirname !== 'undefined') {
-      const pkgRoot = join(__dirname, '..');
-      if (!searchDirs.includes(pkgRoot)) searchDirs.push(pkgRoot);
-    }
-  }
-
-  for (const dir of searchDirs) {
-    for (const name of names) {
-      const candidate = join(dir, 'bin', name);
-      if (isExecutable(candidate)) return candidate;
-    }
-  }
-
-  // Check $PATH
-  for (const bin of ['simulate', 'simulation']) {
-    try {
-      const cmd = platform === 'win32' ? `where ${bin}` : `which ${bin}`;
-      const result = execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
-      if (result) return result.split('\n')[0];
-    } catch {
-      // not found
-    }
-  }
-
-  return null;
-}
-
-function isExecutable(path: string): boolean {
-  try {
-    accessSync(path, fsConstants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// ─── Extended formatting ────────────────────────────────
-
-/** Format a NativeSimulationResult with per-stage and distribution data */
-export function formatNativeResult(result: NativeSimulationResult): string {
-  const lines: string[] = [
-    '',
-    '--- Simulation Results ---',
-    `Game: ${result.gameId}`,
-    `Iterations: ${result.iterations.toLocaleString()}`,
-    `Duration: ${(result.durationMs / 1000).toFixed(1)}s`,
-  ];
-
-  if (result.speed) {
-    lines.push(`Speed: ${Math.round(result.speed).toLocaleString()} iterations/sec`);
-  }
-  if (result.workersUsed) {
-    lines.push(`Workers: ${result.workersUsed}`);
-  }
-
-  lines.push(
-    '',
-    '--- Total ---',
-    `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 Cap Hits: ${result.maxWinHits}`,
-  );
-
-  if (result.bonusTriggered > 0) {
-    const frequency = Math.round(result.iterations / result.bonusTriggered);
-    lines.push(
-      '',
-      '--- Bonus Stats ---',
-      `Bonus Triggered: ${result.bonusTriggered.toLocaleString()} (1 in ${frequency} spins)`,
-      `Bonus Spins Total: ${result.bonusSpinsPlayed.toLocaleString()}`,
-    );
-  }
-
-  // Per-stage breakdown
-  if (result.perStage && Object.keys(result.perStage).length > 0) {
-    lines.push('', '--- Per-Stage Breakdown ---');
-    const header = 'Stage                | Spins      | RTP (contrib) | Per-Spin RTP | Hit Freq  | Avg Win   | Max Win';
-    lines.push(header);
-    lines.push('-'.repeat(header.length));
-
-    for (const [stage, stats] of Object.entries(result.perStage)) {
-      lines.push(
-        `${stage.padEnd(20)} | ${String(stats.spinCount).padStart(10)} | ` +
-        `${stats.rtp.toFixed(2).padStart(12)}% | ` +
-        `${stats.perSpinRtp.toFixed(2).padStart(11)}% | ` +
-        `${stats.hitFrequency.toFixed(2).padStart(8)}% | ` +
-        `${stats.avgWin.toFixed(3).padStart(8)}x | ` +
-        `${stats.maxWin.toFixed(2).padStart(8)}x`,
-      );
-    }
-  }
-
-  // Win distribution
-  if (result.winDistribution && result.winDistribution.length > 0) {
-    lines.push('', '--- Win Distribution ---');
-    for (const bucket of result.winDistribution) {
-      const bar = '█'.repeat(Math.round(bucket.pct / 2));
-      lines.push(
-        `${bucket.label.padEnd(10)} ${String(bucket.count).padStart(10)} (${bucket.pct.toFixed(2).padStart(6)}%) ${bar}`,
-      );
-    }
-  }
-
-  return lines.join('\n');
-}