@energy8platform/game-engine 0.10.7 → 0.10.8

package/dist/lua.d.ts

@@ -113,19 +113,9 @@ interface SimulationResult {
 /**
  * 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.
- * ```
+ * Implements the full lifecycle matching `casino_platform/internal/usecase/game_usecase.go`:
+ * action routing → state assembly → Lua execute() → result extraction →
+ * transition evaluation → session management.
  */
 declare class LuaEngine {
     private L;
@@ -137,18 +127,13 @@ declare class LuaEngine {
     private variables;
     private simulationMode;
     constructor(config: LuaEngineConfig);
-    /** Current session data (if any) */
     get session(): SessionData | null;
-    /** Current persistent state values */
     get persistentVars(): Record<string, number>;
     /**
-     * Execute a play action — the main entry point.
-     * This is what DevBridge calls on each PLAY_REQUEST.
+     * Execute a play action — replicates server's Play() function.
      */
     execute(params: PlayParams): LuaPlayResult;
-    /** Reset all state (sessions, persistent vars, variables) */
     reset(): void;
-    /** Destroy the Lua VM */
     destroy(): void;
     private loadScript;
     private callLuaExecute;
@@ -210,20 +195,37 @@ declare class ActionRouter {
 declare function evaluateCondition(condition: string, variables: Record<string, number>): boolean;
 
 /**
- * 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.
+ * 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
  */
 declare class SessionManager {
     private session;
     get isActive(): boolean;
     get current(): SessionData | null;
     get sessionTotalWin(): number;
-    /** Create a new session from a transition rule */
-    createSession(rule: TransitionRule, variables: Record<string, number>, bet: number): SessionData;
-    /** Update session after a spin: decrement counter, accumulate win, handle retrigger */
+    /** Get the fixed bet amount from the session (server uses session bet, not request bet) */
+    get sessionBet(): number | undefined;
+    /** Get spinsVarName to restore free_spins_remaining into variables */
+    get spinsVarName(): string | undefined;
+    get spinsRemaining(): number;
+    /**
+     * 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;
+    /**
+     * 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;
-    /** Complete the session, return accumulated totalWin and list of session-scoped vars to clean up */
+    /**
+     * Complete the session explicitly.
+     * Returns cumulative totalWin and list of session-scoped var names to clean up.
+     */
     completeSession(): {
         totalWin: number;
         session: SessionData;
@@ -233,7 +235,7 @@ declare class SessionManager {
     markMaxWinReached(): void;
     /** Store _persist_* data extracted from Lua result */
     storePersistData(data: Record<string, unknown>): void;
-    /** Get _ps_* params to inject into next execute() call */
+    /** Get persistent params to inject into next execute() call */
     getPersistentParams(): Record<string, unknown>;
     /** Reset all session state */
     reset(): void;

package/dist/lua.esm.js

@@ -369,10 +369,13 @@ function evaluateComparison(expr, variables) {
     }
 }
 
+const MAX_SESSION_SPINS = 200;
 /**
- * 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.
+ * 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
  */
 class SessionManager {
     session = null;
@@ -387,36 +390,57 @@ class SessionManager {
     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
+    /** Get the fixed bet amount from the session (server uses session bet, not request bet) */
+    get sessionBet() {
+        return this.session?.bet;
+    }
+    /** Get spinsVarName to restore free_spins_remaining into variables */
+    get spinsVarName() {
+        return this.session?.spinsVarName;
+    }
+    get spinsRemaining() {
+        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, variables, bet, spinWin, maxWinCap) {
+        let spinsRemaining = -1;
+        let spinsVarName;
         if (rule.session_config?.total_spins_var) {
-            const varName = rule.session_config.total_spins_var;
-            spinsRemaining = variables[varName] ?? -1;
+            spinsVarName = rule.session_config.total_spins_var;
+            spinsRemaining = variables[spinsVarName] ?? -1;
         }
+        const persistentVarNames = rule.session_config?.persistent_vars ?? [];
         const persistentVars = {};
-        if (rule.session_config?.persistent_vars) {
-            for (const varName of rule.session_config.persistent_vars) {
-                persistentVars[varName] = variables[varName] ?? 0;
-            }
+        for (const varName of persistentVarNames) {
+            persistentVars[varName] = variables[varName] ?? 0;
         }
         this.session = {
             spinsRemaining,
-            spinsPlayed: 0,
-            totalWin: 0,
+            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 spin: decrement counter, accumulate win, handle retrigger */
+    /**
+     * 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, variables, spinWin) {
         if (!this.session)
             throw new Error('No active session');
-        // Accumulate win
+        // Accumulate win and count spin
         this.session.totalWin += spinWin;
         this.session.spinsPlayed++;
         // Decrement spins (only for non-unlimited sessions)
@@ -430,29 +454,39 @@ class SessionManager {
                 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];
-                }
+        // 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];
             }
         }
-        // Auto-complete if spins exhausted
-        if (this.session.spinsRemaining === 0) {
+        // 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, return accumulated totalWin and list of session-scoped vars to clean up */
+    /**
+     * Complete the session explicitly.
+     * Returns cumulative totalWin and list of session-scoped var names to clean up.
+     */
     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();
-        const sessionVarNames = Object.keys(this.session.persistentVars);
-        // Clear session state so it doesn't leak into the next round
+        const sessionVarNames = [...this.session.persistentVarNames];
         this.session = null;
         return { totalWin, session, sessionVarNames };
     }
@@ -474,16 +508,16 @@ class SessionManager {
             }
         }
     }
-    /** Get _ps_* params to inject into next execute() call */
+    /** Get persistent params to inject into next execute() call */
     getPersistentParams() {
         if (!this.session)
             return {};
         const params = {};
-        // Session persistent vars (float64)
+        // Session persistent vars (float64) → state.variables
         for (const [key, value] of Object.entries(this.session.persistentVars)) {
             params[key] = value;
         }
-        // _persist_ complex data → _ps_*
+        // _persist_ complex data → _ps_* in state.params
         for (const [key, value] of Object.entries(this.session.persistentData)) {
             params[`_ps_${key}`] = value;
         }
@@ -581,22 +615,20 @@ class PersistentState {
 
 const { lua, lauxlib, lualib } = fengari;
 const { to_luastring, to_jsstring } = fengari;
+/** Default engine variables matching the server's NewGameState() */
+const DEFAULT_VARIABLES = {
+    multiplier: 1,
+    total_multiplier: 1,
+    global_multiplier: 1,
+    last_win_amount: 0,
+    free_spins_awarded: 0,
+};
 /**
  * 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.
- * ```
+ * Implements the full lifecycle matching `casino_platform/internal/usecase/game_usecase.go`:
+ * action routing → state assembly → Lua execute() → result extraction →
+ * transition evaluation → session management.
  */
 class LuaEngine {
     L;
@@ -610,20 +642,16 @@ class LuaEngine {
     constructor(config) {
         this.gameDefinition = config.gameDefinition;
         this.simulationMode = config.simulationMode ?? false;
-        // 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);
-        // Polyfill Lua 5.1/5.2 functions removed in 5.3.
-        // Platform server may use gopher-lua (5.1) — these ensure compatibility.
+        // Polyfill Lua 5.1/5.2 functions removed in 5.3
         lauxlib.luaL_dostring(this.L, to_luastring(`
       math.pow = function(a, b) return a ^ b end
       math.atan2 = math.atan2 or function(y, x) return math.atan(y, x) end
@@ -641,32 +669,36 @@ class LuaEngine {
       loadstring = loadstring or load
       table.getn = table.getn or function(t) return #t end
     `));
-        // 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 a play action — replicates server's Play() function.
      */
     execute(params) {
-        const { action: actionName, bet, params: clientParams } = params;
-        // 1. Resolve the action definition
+        const { action: actionName, params: clientParams } = params;
+        // 1. Resolve action
         const action = this.actionRouter.resolveAction(actionName, this.sessionManager.isActive);
-        // 2. Build state.variables
-        const stateVars = { ...this.variables, bet };
+        // 2. Determine bet — server uses session bet for session actions
+        let bet = params.bet;
+        if (this.sessionManager.isActive && this.sessionManager.sessionBet !== undefined) {
+            bet = this.sessionManager.sessionBet;
+        }
+        // 3. Build state.variables (matching server's NewGameState + restore)
+        const stateVars = {
+            ...DEFAULT_VARIABLES,
+            ...this.variables,
+            bet,
+        };
         // Load cross-spin persistent state
         this.persistentState.loadIntoVariables(stateVars);
-        // Load session persistent vars
+        // Load session persistent vars + restore spinsRemaining
         if (this.sessionManager.isActive) {
             const sessionParams = this.sessionManager.getPersistentParams();
             for (const [k, v] of Object.entries(sessionParams)) {
@@ -674,8 +706,14 @@ class LuaEngine {
                     stateVars[k] = v;
                 }
             }
+            // Restore spinsRemaining into the variable the script reads
+            if (this.sessionManager.spinsVarName) {
+                stateVars[this.sessionManager.spinsVarName] = this.sessionManager.spinsRemaining;
+            }
+            // Also set free_spins_remaining for convenience
+            stateVars.free_spins_remaining = this.sessionManager.spinsRemaining;
         }
-        // 3. Build state.params
+        // 4. Build state.params
         const stateParams = { ...clientParams };
         stateParams._action = actionName;
         // Inject session _ps_* persistent data
@@ -703,16 +741,16 @@ class LuaEngine {
         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
+        // 5. Execute Lua (server: executor.Execute(stage, state))
+        const luaResult = this.callLuaExecute(action.stage, actionName, stateParams, stateVars);
+        // 6. Process result (server: ApplyLuaResult)
         const totalWinMultiplier = typeof luaResult.total_win === 'number' ? luaResult.total_win : 0;
         const resultVariables = (luaResult.variables ?? {});
-        const totalWin = Math.round(totalWinMultiplier * bet * 100) / 100;
+        const spinWin = 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
+        delete this.variables.bet;
         // Build client data (everything except special keys)
         const data = {};
         for (const [key, value] of Object.entries(luaResult)) {
@@ -720,17 +758,6 @@ class LuaEngine {
                 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);
@@ -747,36 +774,56 @@ class LuaEngine {
                 delete data[key];
             }
         }
-        // 8. Evaluate transitions
+        // 8. Evaluate transitions (server: evaluateTransitions)
         const { rule, nextActions } = this.actionRouter.evaluateTransitions(action, this.variables);
+        // 9. Determine credit behavior (server: creditNow logic)
         let creditDeferred = action.credit === 'defer' || rule.credit_override === 'defer';
+        // 10. Session lifecycle (server: create/update/complete session)
         let session = this.sessionManager.current;
-        // Handle session creation
+        let resultTotalWin = spinWin;
+        let sessionCompleted = false;
+        // Calculate max win cap for session
+        const maxWinCap = this.calculateMaxWinCap(bet);
         if (rule.creates_session && !this.sessionManager.isActive) {
-            session = this.sessionManager.createSession(rule, this.variables, bet);
+            // CREATE SESSION — initial spin counted (server: createSession includes spinWin)
+            session = this.sessionManager.createSession(rule, this.variables, bet, spinWin, maxWinCap);
             creditDeferred = true;
-            // Clear the trigger variable (e.g. free_spins_awarded) — it was consumed
-            // to set session spinsRemaining. On the server this is one-shot.
+            resultTotalWin = spinWin;
+            // Clear the trigger variable — it was consumed to set spinsRemaining
             if (rule.session_config?.total_spins_var) {
                 delete this.variables[rule.session_config.total_spins_var];
             }
         }
-        // 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) {
+            // UPDATE SESSION — accumulate win, check completion
+            session = this.sessionManager.updateSession(rule, this.variables, spinWin);
+            if (session?.completed) {
+                // SESSION COMPLETED — server returns session.TotalWin as result.TotalWin
                 const completed = this.sessionManager.completeSession();
                 session = completed.session;
+                resultTotalWin = completed.totalWin;
+                sessionCompleted = true;
                 creditDeferred = false;
-                // Clean up session-scoped variables so they don't leak into next round
+                // Clean up session-scoped variables
                 for (const varName of completed.sessionVarNames) {
                     delete this.variables[varName];
                 }
             }
+            else {
+                // Mid-session: totalWin = spinWin, credit deferred
+                resultTotalWin = spinWin;
+                creditDeferred = true;
+            }
+        }
+        // No session: resultTotalWin = spinWin (already set)
+        // Apply max win cap for non-session spins
+        if (!this.sessionManager.isActive && !sessionCompleted && maxWinCap !== undefined && resultTotalWin > maxWinCap) {
+            resultTotalWin = maxWinCap;
+            this.variables.max_win_reached = 1;
+            data.max_win_reached = true;
         }
         return {
-            totalWin: cappedWin,
+            totalWin: Math.round(resultTotalWin * 100) / 100,
             data,
             nextActions,
             session,
@@ -784,13 +831,11 @@ class LuaEngine {
             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);
@@ -805,7 +850,6 @@ class LuaEngine {
             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);
@@ -813,21 +857,22 @@ class LuaEngine {
         }
         lua.lua_pop(this.L, 1);
     }
-    callLuaExecute(stage, params, variables) {
-        // Push the execute function
+    callLuaExecute(stage, action, params, variables) {
         lua.lua_getglobal(this.L, to_luastring('execute'));
-        // Build and push the state table
-        lua.lua_createtable(this.L, 0, 3);
+        // Build state table: {stage, action, params, variables}
+        lua.lua_createtable(this.L, 0, 4);
         // state.stage
         lua.lua_pushstring(this.L, to_luastring(stage));
         lua.lua_setfield(this.L, -2, to_luastring('stage'));
+        // state.action (server sets this at top level)
+        lua.lua_pushstring(this.L, to_luastring(action));
+        lua.lua_setfield(this.L, -2, to_luastring('action'));
         // 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));
@@ -835,21 +880,17 @@ class LuaEngine {
             throw new Error(`Lua execute() failed: ${err}`);
         }
         if (this.simulationMode) {
-            // Fast path: extract only total_win and variables without full table marshal
+            // Fast path: extract only total_win, variables, _persist_* keys
             const result = {};
-            // result.total_win
             lua.lua_getfield(this.L, -1, to_luastring('total_win'));
             result.total_win = lua.lua_type(this.L, -1) === lua.LUA_TNUMBER
-                ? lua.lua_tonumber(this.L, -1)
-                : 0;
+                ? lua.lua_tonumber(this.L, -1) : 0;
             lua.lua_pop(this.L, 1);
-            // result.variables
             lua.lua_getfield(this.L, -1, to_luastring('variables'));
             if (lua.lua_type(this.L, -1) === lua.LUA_TTABLE) {
                 result.variables = luaToJS(this.L, -1);
             }
             lua.lua_pop(this.L, 1);
-            // result._persist_* keys (needed for session state)
             lua.lua_pushnil(this.L);
             while (lua.lua_next(this.L, -2) !== 0) {
                 if (lua.lua_type(this.L, -2) === lua.LUA_TSTRING) {
@@ -860,10 +901,10 @@ class LuaEngine {
                 }
                 lua.lua_pop(this.L, 1);
             }
-            lua.lua_pop(this.L, 1); // pop result table
+            lua.lua_pop(this.L, 1);
             return result;
         }
-        // Full path: marshal entire result table to JS
+        // Full path
         const result = luaToJS(this.L, -1);
         lua.lua_pop(this.L, 1);
         if (!result || typeof result !== 'object' || Array.isArray(result)) {