@energy8platform/game-engine 0.9.1 → 0.10.0

package/dist/index.d.ts

@@ -1813,6 +1813,80 @@ declare class LoadingScene extends Scene {
     private transitionToGame;
 }
 
+interface GameDefinition {
+    id: string;
+    type: 'SLOT' | 'TABLE';
+    actions: Record<string, ActionDefinition>;
+    bet_levels?: number[] | BetLevelsConfig;
+    max_win?: MaxWinConfig;
+    buy_bonus?: BuyBonusConfig;
+    ante_bet?: AnteBetConfig;
+    persistent_state?: PersistentStateConfig;
+}
+interface BetLevelsConfig {
+    levels?: number[];
+    min?: number;
+    max?: number;
+}
+interface MaxWinConfig {
+    multiplier?: number;
+    fixed?: number;
+}
+interface BuyBonusConfig {
+    modes: Record<string, BuyBonusMode>;
+}
+interface BuyBonusMode {
+    cost_multiplier: number;
+    scatter_distribution: Record<string, number>;
+}
+interface AnteBetConfig {
+    cost_multiplier: number;
+}
+interface PersistentStateConfig {
+    vars: string[];
+    exposed_vars: string[];
+}
+interface ActionDefinition {
+    stage: string;
+    debit: 'bet' | 'buy_bonus_cost' | 'ante_bet_cost' | 'none';
+    credit?: 'win' | 'none' | 'defer';
+    requires_session?: boolean;
+    buy_bonus_mode?: string;
+    transitions: TransitionRule[];
+    input_schema?: Record<string, unknown>;
+}
+interface TransitionRule {
+    condition: string;
+    creates_session?: boolean;
+    complete_session?: boolean;
+    credit_override?: 'defer';
+    next_actions: string[];
+    session_config?: SessionConfig;
+    add_spins_var?: string;
+}
+interface SessionConfig {
+    total_spins_var: string;
+    persistent_vars?: string[];
+}
+interface LuaEngineConfig {
+    /** Lua script source code */
+    script: string;
+    /** Platform game definition (actions, transitions, bet levels, etc.) */
+    gameDefinition: GameDefinition;
+    /** Seed for deterministic RNG (for simulation/replay) */
+    seed?: number;
+    /** Custom logger function */
+    logger?: (level: string, msg: string) => void;
+}
+interface LuaPlayResult {
+    totalWin: number;
+    data: Record<string, unknown>;
+    nextActions: string[];
+    session: SessionData | null;
+    variables: Record<string, number>;
+    creditDeferred: boolean;
+}
+
 interface DevBridgeConfig {
     /** Mock initial balance */
     balance?: number;
@@ -1830,6 +1904,12 @@ interface DevBridgeConfig {
     networkDelay?: number;
     /** Enable debug logging */
     debug?: boolean;
+    /** Lua script source code. When set, overrides onPlay with LuaEngine. */
+    luaScript?: string;
+    /** Game definition for Lua engine (actions, transitions, etc.) */
+    gameDefinition?: GameDefinition;
+    /** RNG seed for deterministic Lua execution */
+    luaSeed?: number;
 }
 /**
  * Mock host bridge for local development.
@@ -1865,6 +1945,7 @@ declare class DevBridge {
     private _balance;
     private _roundCounter;
     private _bridge;
+    private _luaEngine;
     constructor(config?: DevBridgeConfig);
     /** Current mock balance */
     get balance(): number;
@@ -1876,6 +1957,7 @@ declare class DevBridge {
     setBalance(balance: number): void;
     /** Destroy the dev bridge */
     destroy(): void;
+    private initLuaEngine;
     private handleGameReady;
     private handlePlayRequest;
     private handlePlayAck;
@@ -1885,5 +1967,160 @@ declare class DevBridge {
     private delayedSend;
 }
 
-export { AssetManager, AudioManager, BalanceDisplay, Button, DevBridge, Easing, EventEmitter, FPSOverlay, GameApplication, InputManager, Label, Layout, LoadingScene, Modal, Orientation, Panel, ProgressBar, ScaleMode, Scene, SceneManager, ScrollContainer, SpineHelper, SpriteAnimation, StateMachine, Timeline, Toast, TransitionType, Tween, ViewportManager, WinDisplay };
-export type { AssetBundle, AssetEntry, AssetManifest, AudioConfig, BalanceDisplayConfig, ButtonConfig, ButtonState, DevBridgeConfig, EasingFunction, GameApplicationConfig, GameEngineEvents, IScene, LabelConfig, LayoutAlignment, LayoutAnchor, LayoutConfig, LayoutDirection, LoadingScreenConfig, ModalConfig, PanelConfig, ProgressBarConfig, SceneConstructor, ScrollContainerConfig, ScrollDirection, SpriteAnimationConfig, ToastConfig, ToastType, TransitionConfig, TweenOptions, WinDisplayConfig };
+/**
+ * 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.
+ * ```
+ */
+declare class LuaEngine {
+    private L;
+    private api;
+    private actionRouter;
+    private sessionManager;
+    private persistentState;
+    private gameDefinition;
+    private variables;
+    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(params: PlayParams): LuaPlayResult;
+    /** Reset all state (sessions, persistent vars, variables) */
+    reset(): void;
+    /** Destroy the Lua VM */
+    destroy(): void;
+    private loadScript;
+    private callLuaExecute;
+    private calculateMaxWinCap;
+    private pickFromDistribution;
+}
+
+type RngFunction = () => number;
+/**
+ * Seeded xoshiro128** PRNG for deterministic simulation/replay.
+ * Period: 2^128 - 1
+ */
+declare function createSeededRng(seed: number): RngFunction;
+/**
+ * Implements and registers all platform `engine.*` functions into a Lua state.
+ */
+declare class LuaEngineAPI {
+    private rng;
+    private logger;
+    private gameDefinition;
+    constructor(gameDefinition: GameDefinition, rng?: RngFunction, logger?: (level: string, msg: string) => void);
+    /** Register `engine` global table on the Lua state */
+    register(L: any): void;
+    random(min: number, max: number): number;
+    randomFloat(): number;
+    randomWeighted(weights: number[]): number;
+    shuffle<T>(arr: T[]): T[];
+    getConfig(): Record<string, unknown>;
+    private registerFunction;
+}
+
+interface TransitionMatch {
+    rule: TransitionRule;
+    nextActions: string[];
+}
+/**
+ * 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.
+ */
+declare class ActionRouter {
+    private actions;
+    constructor(gameDefinition: GameDefinition);
+    /** Look up action by name and validate prerequisites */
+    resolveAction(actionName: string, hasSession: boolean): ActionDefinition;
+    /** Evaluate transitions in order, return the first matching rule */
+    evaluateTransitions(action: ActionDefinition, variables: Record<string, number>): TransitionMatch;
+}
+/**
+ * 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.
+ */
+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.
+ */
+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 */
+    updateSession(rule: TransitionRule, variables: Record<string, number>, spinWin: number): SessionData;
+    /** Complete the session, return accumulated totalWin */
+    completeSession(): {
+        totalWin: number;
+        session: SessionData;
+    };
+    /** Mark max win reached — stops the session */
+    markMaxWinReached(): void;
+    /** Store _persist_* data extracted from Lua result */
+    storePersistData(data: Record<string, unknown>): void;
+    /** Get _ps_* params to inject into next execute() call */
+    getPersistentParams(): Record<string, unknown>;
+    /** Reset all session state */
+    reset(): void;
+    private toSessionData;
+}
+
+/**
+ * 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_*`
+ */
+declare class PersistentState {
+    private config;
+    private vars;
+    private gameData;
+    constructor(config?: PersistentStateConfig);
+    /** Load persistent vars into variables map before execute() */
+    loadIntoVariables(variables: Record<string, number>): void;
+    /** Save persistent vars from variables map after execute() */
+    saveFromVariables(variables: Record<string, number>): void;
+    /** Extract _persist_game_* keys from Lua return data, store them */
+    storeGameData(data: Record<string, unknown>): void;
+    /** Get _ps_* params for next execute() call */
+    getGameDataParams(): Record<string, unknown>;
+    /** Get exposed vars for client data.persistent_state */
+    getExposedVars(): Record<string, number> | undefined;
+    /** Reset all state */
+    reset(): void;
+}
+
+export { ActionRouter, AssetManager, AudioManager, BalanceDisplay, Button, DevBridge, Easing, EventEmitter, FPSOverlay, GameApplication, InputManager, Label, Layout, LoadingScene, LuaEngine, LuaEngineAPI, Modal, Orientation, Panel, PersistentState, ProgressBar, ScaleMode, Scene, SceneManager, ScrollContainer, SessionManager, SpineHelper, SpriteAnimation, StateMachine, Timeline, Toast, TransitionType, Tween, ViewportManager, WinDisplay, createSeededRng, evaluateCondition };
+export type { ActionDefinition, AssetBundle, AssetEntry, AssetManifest, AudioConfig, BalanceDisplayConfig, ButtonConfig, ButtonState, DevBridgeConfig, EasingFunction, GameApplicationConfig, GameDefinition, GameEngineEvents, IScene, LabelConfig, LayoutAlignment, LayoutAnchor, LayoutConfig, LayoutDirection, LoadingScreenConfig, LuaEngineConfig, LuaPlayResult, ModalConfig, PanelConfig, ProgressBarConfig, SceneConstructor, ScrollContainerConfig, ScrollDirection, SpriteAnimationConfig, ToastConfig, ToastType, TransitionConfig, TransitionRule, TweenOptions, WinDisplayConfig };