@energy8platform/platform-core 0.16.0

package/dist/index.d.ts

@@ -0,0 +1,439 @@
+import { SessionData, GameConfigData, PlayParams, PlayResultData, BalanceData, CasinoGameSDK, InitData } from '@energy8platform/game-sdk';
+export { AnywhereWinData, BalanceData, GameConfigData, InitData, PaylineData, PlayParams, PlayResultData, SessionData, SymbolData, WinLineData } from '@energy8platform/game-sdk';
+
+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;
+    /** Distribution of forced scatter counts. Optional — if omitted, Lua script handles bonus setup itself. */
+    scatter_distribution?: Record<string, number>;
+    /** Optional description */
+    description?: string;
+}
+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;
+    /** Skip marshalling data fields (matrix, wins, etc.) for faster simulation */
+    simulationMode?: boolean;
+}
+interface LuaPlayResult {
+    totalWin: number;
+    data: Record<string, unknown>;
+    nextActions: string[];
+    session: SessionData | null;
+    variables: Record<string, number>;
+    creditDeferred: boolean;
+}
+interface SimulationConfig {
+    /** Lua script source code */
+    script: string;
+    /** Platform game definition */
+    gameDefinition: GameDefinition;
+    /** Number of iterations to run */
+    iterations: number;
+    /** Bet amount per spin */
+    bet: number;
+    /** RNG seed for deterministic results */
+    seed?: number;
+    /** Which action to simulate (default: 'spin') */
+    action?: string;
+    /** Params for the action (buy_bonus mode, ante_bet, etc.) */
+    params?: Record<string, unknown>;
+    /** Report progress every N iterations (default: 100_000) */
+    progressInterval?: number;
+    /** Progress callback */
+    onProgress?: (completed: number, total: number) => void;
+    /** Number of worker threads for parallel simulation (default: os.cpus().length) */
+    workerCount?: number;
+}
+interface SimulationResult {
+    gameId: string;
+    action: string;
+    iterations: number;
+    durationMs: number;
+    totalRtp: number;
+    baseGameRtp: number;
+    bonusRtp: number;
+    hitFrequency: number;
+    maxWin: number;
+    maxWinHits: number;
+    bonusTriggered: number;
+    bonusSpinsPlayed: number;
+    /** Raw accumulators for aggregation across workers */
+    _raw?: SimulationRawAccumulators;
+}
+interface SimulationRawAccumulators {
+    totalWagered: number;
+    totalWon: number;
+    baseGameWin: number;
+    bonusWin: number;
+    hits: number;
+}
+
+interface DevBridgeConfig {
+    /** Mock initial balance */
+    balance?: number;
+    /** Mock currency */
+    currency?: string;
+    /** Game config */
+    gameConfig?: Partial<GameConfigData>;
+    /** Base URL for assets (default: '/assets/') */
+    assetsUrl?: string;
+    /** Active session to resume (null = no active session) */
+    session?: SessionData | null;
+    /** Custom play result handler — return mock result data */
+    onPlay?: (params: PlayParams) => Partial<PlayResultData>;
+    /** Simulated network delay in ms */
+    networkDelay?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Lua script source code. When set, play requests are routed to the Vite dev server's 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.
+ *
+ * Uses the SDK's `Bridge` class in `devMode` to communicate with
+ * `CasinoGameSDK` via a shared in-memory `MemoryChannel`, removing
+ * the need for postMessage and iframes.
+ *
+ * When `luaScript` is set, play requests are sent to the Vite dev server
+ * which runs LuaEngine in Node.js — no fengari in the browser.
+ *
+ * @example
+ * ```ts
+ * import { DevBridge } from '@energy8platform/platform-core/dev-bridge';
+ *
+ * const devBridge = new DevBridge({
+ *   balance: 5000,
+ *   currency: 'EUR',
+ *   gameConfig: { id: 'my-slot', type: 'slot', betLevels: [0.2, 0.5, 1, 2] },
+ *   onPlay: ({ action, bet }) => ({
+ *     totalWin: Math.random() > 0.5 ? bet * (Math.random() * 20) : 0,
+ *     data: { matrix: [[1,2,3],[4,5,6],[7,8,9]] },
+ *   }),
+ * });
+ * devBridge.start();
+ * ```
+ */
+declare class DevBridge {
+    private _config;
+    private _balance;
+    private _roundCounter;
+    private _bridge;
+    private _useLuaServer;
+    constructor(config?: DevBridgeConfig);
+    /** Current mock balance */
+    get balance(): number;
+    /** Start listening for SDK messages */
+    start(): void;
+    /** Stop listening */
+    stop(): void;
+    /** Set mock balance */
+    setBalance(balance: number): void;
+    /** Destroy the dev bridge */
+    destroy(): void;
+    private handleGameReady;
+    private handlePlayRequest;
+    private executeLuaOnServer;
+    private buildFallbackResult;
+    private handlePlayAck;
+    private handleGetBalance;
+    private handleGetState;
+    private handleOpenDeposit;
+    private delayedSend;
+}
+
+/**
+ * Minimal typed event emitter — internal utility for platform-core.
+ *
+ * Supports `void` event types — events that carry no data can be emitted
+ * without arguments: `emitter.emit('eventName')`.
+ *
+ * Mirrors the EventEmitter shipped from game-engine's core, copied here
+ * so platform-core has no upward dependency on game-engine.
+ */
+declare class EventEmitter<TEvents extends {}> {
+    private listeners;
+    on<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
+    once<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
+    off<K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void): this;
+    emit<K extends keyof TEvents>(...args: TEvents[K] extends void ? [event: K] : [event: K, data: TEvents[K]]): void;
+    removeAllListeners(event?: keyof TEvents): this;
+}
+
+/**
+ * Options for {@link createPlatformSession}.
+ */
+interface PlatformSessionConfig {
+    /**
+     * Optional DevBridge mock-host config. When provided, a DevBridge is started
+     * in-process and the SDK connects to it via in-memory channel — no real
+     * casino backend required. Use this for local development and offline
+     * testing.
+     */
+    dev?: DevBridgeConfig;
+    /**
+     * SDK configuration. Pass an options object, or `false` to skip SDK
+     * initialization entirely (no host communication, used by tests and
+     * head-less simulation).
+     */
+    sdk?: SDKOptions | false;
+}
+interface SDKOptions {
+    parentOrigin?: string;
+    timeout?: number;
+    debug?: boolean;
+    /** Use in-memory channel instead of postMessage (no iframe required) */
+    devMode?: boolean;
+}
+/**
+ * Events forwarded from the underlying SDK by the PlatformSession.
+ */
+interface PlatformSessionEvents {
+    /** Player balance changed (forwarded from CasinoGameSDK) */
+    balanceUpdate: BalanceData;
+    /** SDK or transport error */
+    error: Error;
+}
+/**
+ * Lifecycle wrapper around CasinoGameSDK + (optional) DevBridge.
+ *
+ * Use `createPlatformSession()` to construct one. The session owns the SDK
+ * handshake, optional in-process dev host, and a typed event bus that
+ * forwards SDK events upward.
+ *
+ * Phaser/Three/custom-engine consumers use this directly:
+ *
+ * ```ts
+ * const session = await createPlatformSession({
+ *   dev: { luaScript, gameDefinition, balance: 10000, currency: 'EUR' },
+ * });
+ *
+ * session.on('balanceUpdate', ({ balance }) => updateHud(balance));
+ * const result = await session.play({ action: 'spin', bet: 1 });
+ * ```
+ */
+declare class PlatformSession extends EventEmitter<PlatformSessionEvents> {
+    /** SDK instance, or null when `sdk: false` was passed. */
+    readonly sdk: CasinoGameSDK | null;
+    /** Data returned by the SDK handshake, or null in offline mode. */
+    readonly initData: InitData | null;
+    /** DevBridge mock host, or null when `dev` was not provided. */
+    readonly devBridge: DevBridge | null;
+    constructor(opts: {
+        sdk: CasinoGameSDK | null;
+        initData: InitData | null;
+        devBridge: DevBridge | null;
+    });
+    /** Current player balance from the SDK (0 if no SDK). */
+    get balance(): number;
+    /** Current currency from the SDK ('USD' fallback). */
+    get currency(): string;
+    /**
+     * Send a play request through the SDK and resolve with the host result.
+     * Throws if the session was constructed with `sdk: false`.
+     */
+    play(params: PlayParams): Promise<PlayResultData>;
+    /** Tear down the SDK, DevBridge, and clear listeners. */
+    destroy(): void;
+}
+/**
+ * Build a PlatformSession.
+ *
+ * Steps performed:
+ *   1. If `config.dev` is set → start a DevBridge with those options
+ *   2. Unless `config.sdk === false` → construct CasinoGameSDK and await its handshake
+ *   3. Forward `error` and `balanceUpdate` events from the SDK
+ */
+declare function createPlatformSession(config?: PlatformSessionConfig): Promise<PlatformSession>;
+
+interface AssetEntry {
+    alias: string;
+    src: string | string[];
+    /** Optional loader-specific data (e.g. parser hints) */
+    data?: Record<string, unknown>;
+}
+interface AssetBundle {
+    name: string;
+    assets: AssetEntry[];
+}
+interface AssetManifest {
+    bundles: AssetBundle[];
+}
+interface LoadingScreenConfig {
+    /** Background color (hex number or CSS string) */
+    backgroundColor?: number | string;
+    /** Background gradient (CSS string applied to the CSS preloader) */
+    backgroundGradient?: string;
+    /** Logo texture alias (must be in 'preload' bundle — engine-specific) */
+    logoAsset?: string;
+    /** Logo scale (default: 1) */
+    logoScale?: number;
+    /** Show percentage text below the loader bar */
+    showPercentage?: boolean;
+    /** Custom progress text formatter */
+    progressTextFormatter?: (progress: number) => string;
+    /** Show "Tap to start" after loading (needed for mobile audio unlock) */
+    tapToStart?: boolean;
+    /** "Tap to start" label text */
+    tapToStartText?: string;
+    /** Minimum display time in ms (so the user sees the brand, even if loading is fast) */
+    minDisplayTime?: number;
+    /** CSS preloader custom HTML (shown before the renderer is ready) */
+    cssPreloaderHTML?: string;
+}
+
+/**
+ * Creates a lightweight CSS-only preloader that appears instantly,
+ * BEFORE PixiJS/WebGL is initialized.
+ *
+ * Displays the Energy8 logo SVG with an animated loader bar.
+ */
+declare function createCSSPreloader(container: HTMLElement, config?: LoadingScreenConfig): void;
+/**
+ * Remove the CSS preloader with a smooth fade-out transition.
+ */
+declare function removeCSSPreloader(container: HTMLElement): void;
+
+/**
+ * Shared Energy8 SVG logo with an embedded loader bar.
+ *
+ * The loader bar fill is controlled via a `<clipPath>` whose `<rect>` width
+ * is animatable. Different consumers customise gradient IDs and the clip
+ * element's ID/class to avoid collisions when both CSSPreloader and
+ * LoadingScene appear in the same DOM.
+ */
+/** Max width of the loader bar in SVG units */
+declare const LOADER_BAR_MAX_WIDTH = 174;
+interface LogoSVGOptions {
+    /** Prefix for gradient/clip IDs to avoid collisions (e.g. 'pl' or 'ls') */
+    idPrefix: string;
+    /** Optional CSS class on the root <svg> */
+    svgClass?: string;
+    /** Optional inline style on the root <svg> */
+    svgStyle?: string;
+    /** Optional CSS class on the clip <rect> */
+    clipRectClass?: string;
+    /** Optional id on the clip <rect> (for JS access) */
+    clipRectId?: string;
+    /** Optional id on the percentage <text> */
+    textId?: string;
+    /** Default text content */
+    textContent?: string;
+    /** Optional CSS class on the <text> */
+    textClass?: string;
+}
+/**
+ * Build the Energy8 SVG logo with a loader bar, using unique IDs.
+ *
+ * @param opts - Configuration to avoid element ID collisions
+ * @returns SVG markup string
+ */
+declare function buildLogoSVG(opts: LogoSVGOptions): string;
+
+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;
+}
+interface StageStats {
+    totalWin: number;
+    spinCount: number;
+    hitCount: number;
+    maxWin: number;
+    rtp: number;
+    perSpinRtp: number;
+    hitFrequency: number;
+    avgWin: number;
+}
+interface DistributionBucket {
+    label: string;
+    count: number;
+    pct: number;
+}
+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[];
+}
+
+export { DevBridge, EventEmitter, LOADER_BAR_MAX_WIDTH, PlatformSession, buildLogoSVG, createCSSPreloader, createPlatformSession, removeCSSPreloader };
+export type { ActionDefinition, AnteBetConfig, AssetBundle, AssetEntry, AssetManifest, BetLevelsConfig, BuyBonusConfig, BuyBonusMode, DevBridgeConfig, DistributionBucket, GameDefinition, LoadingScreenConfig, LuaEngineConfig, LuaPlayResult, MaxWinConfig, NativeSimulationConfig, NativeSimulationResult, PersistentStateConfig, PlatformSessionConfig, PlatformSessionEvents, SDKOptions, SessionConfig, SimulationConfig, SimulationRawAccumulators, SimulationResult, StageStats, TransitionRule };