@energy8platform/game-engine 0.9.1 → 0.10.0

package/dist/lua.cjs.js

@@ -0,0 +1,1000 @@
+'use strict';
+
+const fengari$1 = require('fengari');
+const { lua: lua$1, lauxlib: lauxlib$1 } = fengari$1;
+const { to_luastring: to_luastring$1, to_jsstring: to_jsstring$1 } = fengari$1;
+/**
+ * Seeded xoshiro128** PRNG for deterministic simulation/replay.
+ * Period: 2^128 - 1
+ */
+function createSeededRng(seed) {
+    let s0 = (seed >>> 0) | 1;
+    let s1 = (seed * 1103515245 + 12345) >>> 0;
+    let s2 = (seed * 6364136223846793005 + 1442695040888963407) >>> 0;
+    let s3 = (seed * 1442695040888963407 + 6364136223846793005) >>> 0;
+    return () => {
+        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.
+ */
+class LuaEngineAPI {
+    rng;
+    logger;
+    gameDefinition;
+    constructor(gameDefinition, rng, logger) {
+        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) {
+        // Create the `engine` table
+        lua$1.lua_newtable(L);
+        this.registerFunction(L, 'random', (LS) => {
+            const min = lauxlib$1.luaL_checkinteger(LS, 1);
+            const max = lauxlib$1.luaL_checkinteger(LS, 2);
+            const result = this.random(Number(min), Number(max));
+            lua$1.lua_pushinteger(LS, result);
+            return 1;
+        });
+        this.registerFunction(L, 'random_float', (LS) => {
+            lua$1.lua_pushnumber(LS, this.randomFloat());
+            return 1;
+        });
+        this.registerFunction(L, 'random_weighted', (LS) => {
+            lauxlib$1.luaL_checktype(LS, 1, lua$1.LUA_TTABLE);
+            const weights = [];
+            const len = lua$1.lua_rawlen(LS, 1);
+            for (let i = 1; i <= len; i++) {
+                lua$1.lua_rawgeti(LS, 1, i);
+                weights.push(lua$1.lua_tonumber(LS, -1));
+                lua$1.lua_pop(LS, 1);
+            }
+            const result = this.randomWeighted(weights);
+            lua$1.lua_pushinteger(LS, result);
+            return 1;
+        });
+        this.registerFunction(L, 'shuffle', (LS) => {
+            lauxlib$1.luaL_checktype(LS, 1, lua$1.LUA_TTABLE);
+            const arr = [];
+            const len = lua$1.lua_rawlen(LS, 1);
+            for (let i = 1; i <= len; i++) {
+                lua$1.lua_rawgeti(LS, 1, i);
+                arr.push(luaToJS(LS, -1));
+                lua$1.lua_pop(LS, 1);
+            }
+            const shuffled = this.shuffle(arr);
+            pushJSArray(LS, shuffled);
+            return 1;
+        });
+        this.registerFunction(L, 'log', (LS) => {
+            const level = to_jsstring$1(lauxlib$1.luaL_checkstring(LS, 1));
+            const msg = to_jsstring$1(lauxlib$1.luaL_checkstring(LS, 2));
+            this.logger(level, msg);
+            return 0;
+        });
+        this.registerFunction(L, 'get_config', (LS) => {
+            const config = this.getConfig();
+            pushJSObject(LS, config);
+            return 1;
+        });
+        // Set the table as global `engine`
+        lua$1.lua_setglobal(L, to_luastring$1('engine'));
+    }
+    // ─── engine.* implementations ─────────────────────────
+    random(min, max) {
+        return Math.floor(this.rng() * (max - min + 1)) + min;
+    }
+    randomFloat() {
+        return this.rng();
+    }
+    randomWeighted(weights) {
+        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(arr) {
+        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() {
+        const def = this.gameDefinition;
+        let betLevels = [];
+        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 ──────────────────────────────────────────
+    registerFunction(L, name, fn) {
+        lua$1.lua_pushcfunction(L, fn);
+        lua$1.lua_setfield(L, -2, to_luastring$1(name));
+    }
+}
+// ─── Lua ↔ JS marshalling ───────────────────────────────
+/** Read a Lua value at the given stack index and return its JS equivalent */
+function luaToJS(L, idx) {
+    const type = lua$1.lua_type(L, idx);
+    switch (type) {
+        case lua$1.LUA_TNIL:
+            return null;
+        case lua$1.LUA_TBOOLEAN:
+            return lua$1.lua_toboolean(L, idx);
+        case lua$1.LUA_TNUMBER:
+            if (lua$1.lua_isinteger(L, idx)) {
+                return Number(lua$1.lua_tointeger(L, idx));
+            }
+            return lua$1.lua_tonumber(L, idx);
+        case lua$1.LUA_TSTRING:
+            return to_jsstring$1(lua$1.lua_tostring(L, idx));
+        case lua$1.LUA_TTABLE:
+            return luaTableToJS(L, idx);
+        default:
+            return null;
+    }
+}
+/** Convert a Lua table to a JS object or array */
+function luaTableToJS(L, idx) {
+    // Normalize index to absolute
+    if (idx < 0)
+        idx = lua$1.lua_gettop(L) + idx + 1;
+    // Check if it's an array (sequential integer keys starting at 1)
+    const len = lua$1.lua_rawlen(L, idx);
+    if (len > 0) {
+        // Verify it's a pure array by checking key 1 exists
+        lua$1.lua_rawgeti(L, idx, 1);
+        const hasFirst = lua$1.lua_type(L, -1) !== lua$1.LUA_TNIL;
+        lua$1.lua_pop(L, 1);
+        if (hasFirst) {
+            // Check if there are also string keys (mixed table)
+            let hasStringKeys = false;
+            lua$1.lua_pushnil(L);
+            while (lua$1.lua_next(L, idx) !== 0) {
+                lua$1.lua_pop(L, 1); // pop value
+                if (lua$1.lua_type(L, -1) === lua$1.LUA_TSTRING) {
+                    hasStringKeys = true;
+                    lua$1.lua_pop(L, 1); // pop key
+                    break;
+                }
+            }
+            if (!hasStringKeys) {
+                // Pure array
+                const arr = [];
+                for (let i = 1; i <= len; i++) {
+                    lua$1.lua_rawgeti(L, idx, i);
+                    arr.push(luaToJS(L, -1));
+                    lua$1.lua_pop(L, 1);
+                }
+                return arr;
+            }
+        }
+    }
+    // Object (or mixed table)
+    const obj = {};
+    lua$1.lua_pushnil(L);
+    while (lua$1.lua_next(L, idx) !== 0) {
+        const keyType = lua$1.lua_type(L, -2);
+        let key;
+        if (keyType === lua$1.LUA_TSTRING) {
+            key = to_jsstring$1(lua$1.lua_tostring(L, -2));
+        }
+        else if (keyType === lua$1.LUA_TNUMBER) {
+            key = String(lua$1.lua_tonumber(L, -2));
+        }
+        else {
+            lua$1.lua_pop(L, 1);
+            continue;
+        }
+        obj[key] = luaToJS(L, -1);
+        lua$1.lua_pop(L, 1);
+    }
+    return obj;
+}
+/** Push a JS value onto the Lua stack */
+function pushJSValue(L, value) {
+    if (value === null || value === undefined) {
+        lua$1.lua_pushnil(L);
+    }
+    else if (typeof value === 'boolean') {
+        lua$1.lua_pushboolean(L, value ? 1 : 0);
+    }
+    else if (typeof value === 'number') {
+        if (Number.isInteger(value)) {
+            lua$1.lua_pushinteger(L, value);
+        }
+        else {
+            lua$1.lua_pushnumber(L, value);
+        }
+    }
+    else if (typeof value === 'string') {
+        lua$1.lua_pushstring(L, to_luastring$1(value));
+    }
+    else if (Array.isArray(value)) {
+        pushJSArray(L, value);
+    }
+    else if (typeof value === 'object') {
+        pushJSObject(L, value);
+    }
+    else {
+        lua$1.lua_pushnil(L);
+    }
+}
+/** Push a JS array as a Lua table (1-based) */
+function pushJSArray(L, arr) {
+    lua$1.lua_createtable(L, arr.length, 0);
+    for (let i = 0; i < arr.length; i++) {
+        pushJSValue(L, arr[i]);
+        lua$1.lua_rawseti(L, -2, i + 1);
+    }
+}
+/** Push a JS object as a Lua table */
+function pushJSObject(L, obj) {
+    const keys = Object.keys(obj);
+    lua$1.lua_createtable(L, 0, keys.length);
+    for (const key of keys) {
+        pushJSValue(L, obj[key]);
+        lua$1.lua_setfield(L, -2, to_luastring$1(key));
+    }
+}
+
+/**
+ * Replicates the platform's action dispatch and transition evaluation.
+ * Routes play requests to the correct action, evaluates transition conditions
+ * against current variables to determine next actions and session operations.
+ */
+class ActionRouter {
+    actions;
+    constructor(gameDefinition) {
+        this.actions = gameDefinition.actions;
+    }
+    /** Look up action by name and validate prerequisites */
+    resolveAction(actionName, hasSession) {
+        const action = this.actions[actionName];
+        if (!action) {
+            throw new Error(`Unknown action: "${actionName}". Available: ${Object.keys(this.actions).join(', ')}`);
+        }
+        if (action.requires_session && !hasSession) {
+            throw new Error(`Action "${actionName}" requires an active session`);
+        }
+        return action;
+    }
+    /** Evaluate transitions in order, return the first matching rule */
+    evaluateTransitions(action, variables) {
+        for (const rule of action.transitions) {
+            if (evaluateCondition(rule.condition, variables)) {
+                return { rule, nextActions: rule.next_actions };
+            }
+        }
+        throw new Error(`No matching transition for action with stage "${action.stage}". ` +
+            `Variables: ${JSON.stringify(variables)}`);
+    }
+}
+// ─── Condition Evaluator ────────────────────────────────
+/**
+ * Evaluates a transition condition expression against variables.
+ *
+ * Supports:
+ * - "always" → true
+ * - Simple comparisons: "var > 0", "var == 1", "var >= 10", "var != 0", "var < 5", "var <= 3"
+ * - Logical connectives: "expr && expr", "expr || expr"
+ *
+ * This covers all patterns used by the platform's govaluate conditions.
+ */
+function evaluateCondition(condition, variables) {
+    const trimmed = condition.trim();
+    if (trimmed === 'always')
+        return true;
+    // Handle || (OR) — lowest precedence
+    if (trimmed.includes('||')) {
+        const parts = splitOnOperator(trimmed, '||');
+        return parts.some(part => evaluateCondition(part, variables));
+    }
+    // Handle && (AND)
+    if (trimmed.includes('&&')) {
+        const parts = splitOnOperator(trimmed, '&&');
+        return parts.every(part => evaluateCondition(part, variables));
+    }
+    // Single comparison: "variable op value"
+    return evaluateComparison(trimmed, variables);
+}
+function splitOnOperator(expr, operator) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (let i = 0; i < expr.length; i++) {
+        if (expr[i] === '(')
+            depth++;
+        else if (expr[i] === ')')
+            depth--;
+        if (depth === 0 && expr.substring(i, i + operator.length) === operator) {
+            parts.push(current);
+            current = '';
+            i += operator.length - 1;
+        }
+        else {
+            current += expr[i];
+        }
+    }
+    parts.push(current);
+    return parts;
+}
+function evaluateComparison(expr, variables) {
+    // Match: variable_name operator value
+    const match = expr.trim().match(/^\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*(>=|<=|!=|==|>|<)\s*(-?\d+(?:\.\d+)?)\s*$/);
+    if (!match) {
+        throw new Error(`Cannot parse condition: "${expr}"`);
+    }
+    const [, varName, op, valueStr] = match;
+    const left = variables[varName] ?? 0;
+    const right = parseFloat(valueStr);
+    switch (op) {
+        case '>': return left > right;
+        case '>=': return left >= right;
+        case '<': return left < right;
+        case '<=': return left <= right;
+        case '==': return left === right;
+        case '!=': return left !== right;
+        default: return false;
+    }
+}
+
+/**
+ * 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.
+ */
+class SessionManager {
+    session = null;
+    get isActive() {
+        return this.session !== null && !this.session.completed;
+    }
+    get current() {
+        if (!this.session)
+            return null;
+        return this.toSessionData();
+    }
+    get sessionTotalWin() {
+        return this.session?.totalWin ?? 0;
+    }
+    /** Create a new session from a transition rule */
+    createSession(rule, variables, bet) {
+        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 = {};
+        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, variables, spinWin) {
+        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() {
+        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() {
+        if (this.session) {
+            this.session.maxWinReached = true;
+            this.session.completed = true;
+        }
+    }
+    /** Store _persist_* data extracted from Lua result */
+    storePersistData(data) {
+        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() {
+        if (!this.session)
+            return {};
+        const params = {};
+        // 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() {
+        this.session = null;
+    }
+    toSessionData() {
+        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,
+        };
+    }
+}
+
+/**
+ * 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_*`
+ */
+class PersistentState {
+    config;
+    vars = {};
+    gameData = {};
+    constructor(config) {
+        this.config = config;
+    }
+    /** Load persistent vars into variables map before execute() */
+    loadIntoVariables(variables) {
+        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) {
+        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) {
+        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() {
+        const params = {};
+        for (const [key, value] of Object.entries(this.gameData)) {
+            params[`_ps_${key}`] = value;
+        }
+        return params;
+    }
+    /** Get exposed vars for client data.persistent_state */
+    getExposedVars() {
+        if (!this.config?.exposed_vars?.length)
+            return undefined;
+        const exposed = {};
+        for (const varName of this.config.exposed_vars) {
+            if (varName in this.vars) {
+                exposed[varName] = this.vars[varName];
+            }
+        }
+        return exposed;
+    }
+    /** Reset all state */
+    reset() {
+        this.vars = {};
+        this.gameData = {};
+    }
+}
+
+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.
+ * ```
+ */
+class LuaEngine {
+    L;
+    api;
+    actionRouter;
+    sessionManager;
+    persistentState;
+    gameDefinition;
+    variables = {};
+    constructor(config) {
+        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() {
+        return this.sessionManager.current;
+    }
+    /** Current persistent state values */
+    get persistentVars() {
+        return { ...this.variables };
+    }
+    /**
+     * Execute a play action — the main entry point.
+     * This is what DevBridge calls on each PLAY_REQUEST.
+     */
+    execute(params) {
+        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 = { ...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 = { ...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 ?? {});
+        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 = {};
+        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() {
+        this.variables = {};
+        this.sessionManager.reset();
+        this.persistentState.reset();
+    }
+    /** Destroy the Lua VM */
+    destroy() {
+        if (this.L) {
+            lua.lua_close(this.L);
+            this.L = null;
+        }
+    }
+    // ─── Private ──────────────────────────────────────────
+    loadScript(source) {
+        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);
+    }
+    callLuaExecute(stage, params, variables) {
+        // 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;
+    }
+    calculateMaxWinCap(bet) {
+        const mw = this.gameDefinition.max_win;
+        if (!mw)
+            return undefined;
+        const caps = [];
+        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;
+    }
+    pickFromDistribution(distribution) {
+        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);
+    }
+}
+
+/**
+ * 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)}%`);
+ * ```
+ */
+class SimulationRunner {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    run() {
+        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) */
+    calculateSpinCost(action, bet, gameDefinition, params) {
+        // 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 */
+function formatSimulationResult(result) {
+    const lines = [
+        '',
+        '--- 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');
+}
+
+exports.ActionRouter = ActionRouter;
+exports.LuaEngine = LuaEngine;
+exports.LuaEngineAPI = LuaEngineAPI;
+exports.PersistentState = PersistentState;
+exports.SessionManager = SessionManager;
+exports.SimulationRunner = SimulationRunner;
+exports.createSeededRng = createSeededRng;
+exports.evaluateCondition = evaluateCondition;
+exports.formatSimulationResult = formatSimulationResult;
+//# sourceMappingURL=lua.cjs.js.map