slot-server 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2160 @@
+/**
+ * Symbol mapping: symbol ID → texture key.
+ * The client uses this to load the correct images.
+ */
+type SymbolMap = Record<number, string>;
+/**
+ * A single payline pattern.
+ * Each element is { reel: number; row: number } (0-indexed).
+ */
+type PaylinePattern = {
+    reel: number;
+    row: number;
+}[];
+/**
+ * Paytable data: symbol ID → multiplier by count (e.g., "x3": 50).
+ * Keys should be like "x3", "x4", "x5" (or "x2" etc.)
+ */
+type PaytableData = Record<number, Record<string, number>>;
+/**
+ * Reel strip: an array of symbol IDs (ordered bottom-to-top or top-to-bottom,
+ * but the client will interpret it consistently).
+ */
+type ReelStrip = number[];
+/**
+ * Symbol behavior types for special features.
+ */
+type SymbolBehavior = 'normal' | 'wild' | 'scatter' | 'bonus' | 'multiplier' | 'expanding' | 'sticky' | 'shifting' | 'split';
+/**
+ * Configuration for a symbol's properties.
+ */
+interface ISymbolConfig {
+    id: number;
+    textureKey: string;
+    behavior: SymbolBehavior;
+    /** For wilds: which symbols it can substitute for (undefined = all) */
+    substitutesFor?: number[];
+    /** For multipliers: multiplier value */
+    multiplierValue?: number;
+    /** For scatters: minimum count for trigger */
+    scatterMinCount?: number;
+    /** For scatters/bonus: bonus triggered */
+    triggersBonus?: boolean;
+    /** For expanding: does it expand */
+    expands?: boolean;
+    /** For sticky: how many spins it stays */
+    stickySpins?: number;
+    /** Pay priority (higher = evaluated first) */
+    payPriority?: number;
+}
+/**
+ * Ways-to-win configuration (for "243 ways" or similar mechanics).
+ */
+interface IWaysConfig {
+    enabled: boolean;
+    /** Number of ways (e.g., 243, 1024, 4096) */
+    waysCount: number;
+    /** Minimum matching symbols from left (default: 3) */
+    minMatches: number;
+    /** Use adjacent pays (left-to-right only or both directions) */
+    direction: 'leftToRight' | 'bothDirections';
+}
+/**
+ * Jackpot tier configuration.
+ */
+interface IJackpotTier {
+    id: string;
+    name: string;
+    seedAmount: number;
+    currentAmount: number;
+    triggerProbability: number;
+    contributionRate: number;
+    minBetRequired?: number;
+}
+/**
+ * Jackpot configuration.
+ */
+interface IJackpotConfig {
+    enabled: boolean;
+    tiers: IJackpotTier[];
+    /** Type: standalone, local (casino-wide), or wide-area */
+    type: 'standalone' | 'local' | 'wideArea';
+}
+/**
+ * Free spins configuration.
+ */
+interface IFreeSpinsConfig {
+    /** Scatter symbol ID that triggers free spins */
+    scatterSymbolId: number;
+    /** Minimum scatters needed */
+    minTriggers: number;
+    /** Free spins awarded per scatter count */
+    spinsByCount: Record<number, number>;
+    /** Multiplier applied during free spins */
+    multiplier?: number;
+    /** Can free spins be retriggered? */
+    retriggerable: boolean;
+    /** Additional spins on retrigger */
+    retriggerSpins: Record<number, number>;
+    /** Special expanding symbols during free spins */
+    expandingSymbols?: number[];
+    /** Sticky wilds during free spins */
+    stickyWilds?: boolean;
+}
+/**
+ * Gamble feature configuration.
+ */
+interface IGambleConfig {
+    enabled: boolean;
+    /** Maximum amount that can be gambled */
+    maxGambleAmount?: number;
+    /** Maximum consecutive gambles */
+    maxConsecutiveGambles: number;
+    /** Types of gamble games available */
+    gameTypes: ('card' | 'ladder' | 'wheel')[];
+    /** Auto-collect at win amount */
+    autoCollectAt?: number;
+}
+/**
+ * Buy bonus feature configuration.
+ */
+interface IBuyBonusConfig {
+    enabled: boolean;
+    /** Cost multiplier (e.g., 100x bet) */
+    costMultiplier: number;
+    /** Minimum bet required */
+    minBetRequired?: number;
+    /** Maximum purchases per session */
+    maxPurchasesPerSession?: number;
+    /** Cooldown between purchases (ms) */
+    cooldownMs?: number;
+}
+/**
+ * Tournament mode configuration.
+ */
+interface ITournamentConfig {
+    enabled: boolean;
+    tournamentId: string;
+    startTime: number;
+    endTime: number;
+    entryFee?: number;
+    prizePool: number;
+    scoringMethod: 'totalWin' | 'biggestWin' | 'totalSpins';
+    leaderboard: ITournamentPlayer[];
+}
+interface ITournamentPlayer {
+    playerId: string;
+    playerName: string;
+    score: number;
+    rank: number;
+}
+/**
+ * Responsible gaming limits.
+ */
+interface IResponsibleGamingLimits {
+    /** Session time limit in minutes */
+    sessionTimeLimit?: number;
+    /** Loss limit per session */
+    lossLimit?: number;
+    /** Win goal (notify when reached) */
+    winGoal?: number;
+    /** Maximum bet allowed */
+    maxBetLimit?: number;
+    /** Reality check interval in minutes */
+    realityCheckInterval?: number;
+    /** Self-exclusion end date (ISO timestamp) */
+    selfExclusionUntil?: string;
+}
+/**
+ * Currency configuration.
+ */
+interface ICurrencyConfig {
+    code: string;
+    symbol: string;
+    decimalSeparator: string;
+    thousandSeparator: string;
+    minDecimalPlaces: number;
+    /** Exchange rate to base currency (for multi-currency) */
+    exchangeRate?: number;
+}
+/**
+ * Game configuration for the client engine.
+ */
+interface IGameConfigData {
+    /** Game identifier (e.g., "lucky7") */
+    gameId: string;
+    /** Game version */
+    version?: string;
+    /** Number of reels (default 5) */
+    reelCount: number;
+    /** Number of visible rows (default 3) */
+    rowCount: number;
+    /** Symbol configurations */
+    symbols?: ISymbolConfig[];
+    /** Legacy symbol map (ID → texture key) for backward compatibility */
+    symbolMap: SymbolMap;
+    /** Paytable data */
+    paytableData: PaytableData;
+    /** Reel strips (one array per reel) */
+    reelStrips: ReelStrip[];
+    /** Line patterns (paylines) */
+    linePatterns: PaylinePattern[];
+    /** Ways-to-win configuration */
+    waysConfig?: IWaysConfig;
+    /** Jackpot configuration */
+    jackpotConfig?: IJackpotConfig;
+    /** Free spins configuration */
+    freeSpinsConfig?: IFreeSpinsConfig;
+    /** Gamble feature configuration */
+    gambleConfig?: IGambleConfig;
+    /** Buy bonus configuration */
+    buyBonusConfig?: IBuyBonusConfig;
+    /** Currency settings */
+    currency: ICurrencyConfig;
+    /** Feature flags (autoplay, fastspin, etc.) */
+    features: {
+        autoplay: boolean;
+        fastSpin: boolean;
+        realityCheck: boolean;
+        fullscreen: boolean;
+        turboSpin?: boolean;
+        quickStop?: boolean;
+    };
+    /** Default bet (in base currency units) */
+    defaultBet: number;
+    /** Minimum bet */
+    minBet: number;
+    /** Maximum bet */
+    maxBet: number;
+    /** Bet step (increment) */
+    betStep: number;
+    /** Available bet amounts (if using preset bets instead of steps) */
+    betPresets?: number[];
+    /** Number of selectable paylines (if variable) */
+    selectableLines?: number[];
+    /** Default number of lines */
+    defaultLines: number;
+    /** RTP percentage (e.g., 96.5) */
+    rtp: number;
+    /** Volatility level */
+    volatility: 'low' | 'medium' | 'high' | 'veryHigh';
+    /** Hit frequency percentage (e.g., 25.5) */
+    hitFrequency?: number;
+    /** Max win multiplier (e.g., 5000x) */
+    maxWinMultiplier?: number;
+    /** Responsible gaming limits */
+    responsibleGaming?: IResponsibleGamingLimits;
+    /** Tournament mode */
+    tournament?: ITournamentConfig;
+    /** Game rules text (localized keys) */
+    rulesText?: Record<string, string>;
+    /** Help screens (localized keys) */
+    helpScreens?: Array<{
+        title: string;
+        content: string;
+        image?: string;
+    }>;
+}
+/**
+ * Response structure for an INIT message (sent from server to client).
+ */
+interface IInitResponse {
+    /** Player balance */
+    balance: number;
+    /** Current bet */
+    bet: number;
+    /** Game configuration (includes all static data) */
+    config: IGameConfigData;
+    /** Bonus offers (if any) */
+    bonusOffers?: any;
+    /** Additional game state */
+    state?: any;
+}
+/**
+ * Request structure for a SPIN message (client → server).
+ */
+interface ISpinRequestData {
+    action: 'spin' | 'autospin' | 'fastspin';
+    stakePerLine: number;
+    selectedLines: number;
+    totalStake: number;
+    /** Game mode — CHANGED: Formatted to camelCase to match the frontend expectations */
+    gameMode: 0 | 1;
+}
+/**
+ * Request for buying a bonus feature.
+ */
+interface IBuyBonusRequest {
+    action: 'buyBonus';
+    totalStake: number;
+    gameMode: 0 | 1;
+}
+/**
+ * Request for gamble feature.
+ */
+interface IGambleRequest {
+    action: 'gamble';
+    gambleType: 'card' | 'ladder' | 'wheel';
+    currentWin: number;
+    choice?: number | string;
+}
+/**
+ * Gamble response.
+ */
+interface IGambleResponse {
+    result: 'win' | 'lose' | 'push';
+    winAmount: number;
+    canGambleAgain: boolean;
+    consecutiveGambles: number;
+}
+/**
+ * Jackpot contribution notification.
+ */
+interface IJackpotContribution {
+    tierId: string;
+    contributedAmount: number;
+    newJackpotAmount: number;
+}
+/**
+ * Jackpot win notification.
+ */
+interface IJackpotWin {
+    tierId: string;
+    tierName: string;
+    winAmount: number;
+    timestamp: number;
+}
+/**
+ * Tournament spin request.
+ */
+interface ITournamentSpinRequest {
+    action: 'tournamentSpin';
+    tournamentId: string;
+    entryFee?: number;
+}
+/**
+ * Tournament state response.
+ */
+interface ITournamentState {
+    tournamentId: string;
+    playerName: string;
+    playerRank: number;
+    playerScore: number;
+    timeRemaining: number;
+    leaderboard: ITournamentPlayer[];
+}
+/**
+ * A single winning line.
+ */
+interface IWinLine {
+    lineIndex: number;
+    symbolId: number;
+    multiplier: number;
+    winAmount: number;
+    positions: {
+        reel: number;
+        row: number;
+    }[];
+    /** For ways-to-win: which way this represents */
+    wayIndex?: number;
+    /** For expanding symbols: was this an expanded position */
+    expanded?: boolean;
+}
+/**
+ * Extended win details for complex features.
+ */
+interface IWinDetails {
+    /** Base game wins */
+    baseWins: IWinLine[];
+    /** Scatter pays (anywhere pays) */
+    scatterPays: Array<{
+        symbolId: number;
+        count: number;
+        winAmount: number;
+    }>;
+    /** Wild substitutions made */
+    wildSubstitutions: Array<{
+        reel: number;
+        row: number;
+        originalSymbol: number;
+        wildSymbol: number;
+    }>;
+    /** Multipliers applied */
+    multipliersApplied: Array<{
+        source: string;
+        value: number;
+    }>;
+    /** Cascading/tumbling wins in sequence */
+    cascadeSequence?: Array<{
+        step: number;
+        wins: IWinLine[];
+        totalWin: number;
+    }>;
+}
+/**
+ * Response structure for a SPIN message (server → client).
+ */
+interface ISpinResponseData {
+    /** 2D array of symbol IDs [reel][row] (visible positions) */
+    result: number[][];
+    /** Total win amount */
+    totalWin: number;
+    /** Stake per line used */
+    stakePerLine: number;
+    /** Total stake used */
+    totalStake: number;
+    /** Game mode (0 = main, 1 = bonus) */
+    gameMode: 0 | 1;
+    /** Free spins remaining (if any) */
+    freeSpinsRemaining?: number;
+    /** Bonus triggered? */
+    bonusTriggered?: boolean;
+    /** Bonus data (if triggered) */
+    bonusData?: any;
+    /** Winning lines (optional) */
+    winLines?: IWinLine[];
+    /** Detailed win breakdown */
+    winDetails?: IWinDetails;
+    /** New balance after the spin */
+    balanceAfter: number;
+    /** Jackpot contributions */
+    jackpotContributions?: IJackpotContribution[];
+    /** Jackpot won (if any) */
+    jackpotWin?: IJackpotWin;
+    /** Error message (if any) */
+    error?: string;
+    /** Spin ID for audit trail */
+    spinId?: string;
+    /** Server timestamp */
+    timestamp?: number;
+    /** RNG seed for verification (if using provably fair) */
+    rngSeed?: string;
+    /** Whether this is a cascading/tumbling spin */
+    isCascade?: boolean;
+    /** Cascade level (0 = initial spin, 1+ = subsequent cascades) */
+    cascadeLevel?: number;
+}
+/**
+ * Response for a BONUS message (server → client).
+ */
+interface IBonusResponse {
+    /** Bonus ID (if applicable) */
+    bonusId?: string;
+    /** Action (e.g., "accept", "decline", "pick", "end") */
+    action?: string;
+    /** Bonus state */
+    state?: 'ACTIVE' | 'ENDED' | 'COMPLETE' | 'OFFERED';
+    /** Data specific to the bonus type */
+    data?: any;
+}
+/**
+ * Free spin bonus state.
+ */
+interface IFreeSpinBonus {
+    type: 'freespin';
+    spinsRemaining: number;
+    multiplier: number;
+    totalWin: number;
+    bet: number;
+}
+/**
+ * Pick bonus state.
+ */
+interface IPickBonus {
+    type: 'pick';
+    items: {
+        id: string;
+        label: string;
+        value: number;
+    }[];
+    pickedIds: string[];
+    totalWin: number;
+}
+/**
+ * Extended bonus types for professional features.
+ */
+interface IWheelBonus {
+    type: 'wheel';
+    segments: Array<{
+        id: string;
+        value: number;
+        probability: number;
+        label?: string;
+    }>;
+    currentRotation?: number;
+    resultSegment?: string;
+    totalWin: number;
+}
+interface ICascadeBonus {
+    type: 'cascade';
+    currentLevel: number;
+    maxLevels: number;
+    multiplierPerLevel: number;
+    currentMultiplier: number;
+    totalWin: number;
+}
+interface IRespinsBonus {
+    type: 'respins';
+    spinsRemaining: number;
+    lockedPositions: Array<{
+        reel: number;
+        row: number;
+        symbolId: number;
+    }>;
+    targetSymbol?: number;
+    totalWin: number;
+}
+interface IHoldAndSpinBonus {
+    type: 'holdAndSpin';
+    initialSpins: number;
+    spinsRemaining: number;
+    grid: (number | null)[][];
+    specialSymbols: Array<{
+        reel: number;
+        row: number;
+        type: string;
+        value: number;
+    }>;
+    totalWin: number;
+    isComplete: boolean;
+}
+/**
+ * Union of all bonus states.
+ */
+type IBonusState = IFreeSpinBonus | IPickBonus | IWheelBonus | ICascadeBonus | IRespinsBonus | IHoldAndSpinBonus;
+/**
+ * History entry (for HISTORY response).
+ */
+interface IHistoryEntry {
+    time: number;
+    bet: number;
+    win: number;
+    balance: number;
+    result: number[][];
+    gameMode: 0 | 1;
+}
+/**
+ * History response.
+ */
+interface IHistoryResponse {
+    entries: IHistoryEntry[];
+    total: number;
+}
+/**
+ * Full player state tracked by the server.
+ */
+interface IPlayerState {
+    balance: number;
+    bet: number;
+    gameMode: 0 | 1;
+    freeSpinsRemaining: number;
+    bonusActive: boolean;
+    bonusState?: IBonusState;
+    lastSpinResult?: ISpinResponseData;
+    history: IHistoryEntry[];
+    /** Responsible gaming session tracking */
+    sessionStartTime?: number;
+    sessionLoss?: number;
+    sessionWin?: number;
+    consecutiveGambles?: number;
+    /** Tournament state */
+    tournamentScore?: number;
+    tournamentRank?: number;
+}
+/**
+ * Debug mode configuration for testing and development.
+ */
+interface IDebugConfig {
+    /** Enable debug mode */
+    enabled: boolean;
+    /** Log all spin results with detailed breakdown */
+    logSpins: boolean;
+    /** Log RNG seeds for reproducibility */
+    logRngSeeds: boolean;
+    /** Force specific outcomes for testing */
+    forcedOutcomes?: IForcedOutcome[];
+    /** Skip balance checks (for testing) */
+    skipBalanceChecks: boolean;
+    /** Verbose logging level */
+    verboseLevel: 'none' | 'errors' | 'warnings' | 'info' | 'debug';
+    /** Output format for logs */
+    outputFormat: 'console' | 'json' | 'file';
+    /** File path for log output (if file format) */
+    logFilePath?: string;
+}
+/**
+ * Forced outcome for testing specific scenarios.
+ */
+interface IForcedOutcome {
+    /** Condition to trigger forced outcome */
+    condition: {
+        type: 'spinNumber' | 'randomSeed' | 'betAmount' | 'playerId';
+        value: number | string;
+    };
+    /** Result to force */
+    result: {
+        symbols?: number[][];
+        winAmount?: number;
+        bonusTriggered?: boolean;
+        jackpotWon?: string;
+    };
+}
+/**
+ * Debug log entry.
+ */
+interface IDebugLogEntry {
+    timestamp: number;
+    level: 'error' | 'warning' | 'info' | 'debug';
+    category: string;
+    message: string;
+    data?: any;
+}
+/**
+ * Debug session state.
+ */
+interface IDebugState {
+    enabled: boolean;
+    spinCount: number;
+    lastRngSeed: string;
+    forcedOutcomesApplied: number;
+    errors: IDebugLogEntry[];
+    warnings: IDebugLogEntry[];
+    infoLogs: IDebugLogEntry[];
+}
+/**
+ * Spin audit record for regulatory compliance.
+ */
+interface IAuditRecord {
+    spinId: string;
+    playerId: string;
+    gameId: string;
+    timestamp: number;
+    stake: number;
+    win: number;
+    balanceBefore: number;
+    balanceAfter: number;
+    rngSeed: string;
+    result: number[][];
+    gameMode: 0 | 1;
+    bonusTriggered: boolean;
+    jackpotContributions: IJackpotContribution[];
+    jackpotWins: IJackpotWin[];
+    ipAddress?: string;
+    sessionId: string;
+    /** Extended audit fields */
+    deviceInfo?: string;
+    location?: string;
+    operatorId?: string;
+    platform?: 'web' | 'mobile' | 'desktop';
+}
+/**
+ * Player activity summary for reporting.
+ */
+interface IPlayerActivitySummary {
+    playerId: string;
+    periodStart: number;
+    periodEnd: number;
+    totalSpins: number;
+    totalStaked: number;
+    totalWon: number;
+    netResult: number;
+    biggestWin: number;
+    bonusTriggers: number;
+    jackpotWins: number;
+    sessionCount: number;
+    averageSessionDuration: number;
+}
+/**
+ * Generic WebSocket message wrapper.
+ */
+interface IWebSocketMessage<T = any> {
+    type: string;
+    data: T;
+    messageId: string;
+    timestamp: number;
+}
+/**
+ * Server acknowledgment message.
+ */
+interface IServerAck {
+    messageId: string;
+    status: 'success' | 'error';
+    errorCode?: string;
+    errorMessage?: string;
+}
+/**
+ * Deep partial type for optional updates.
+ */
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+/**
+ * Nullable type helper.
+ */
+type Nullable<T> = T | null;
+/**
+ * Result type for operations that can fail.
+ */
+type Result<T, E = Error> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: E;
+};
+/**
+ * Configuration for cascading/tumbling reel mechanics.
+ */
+interface ICascadeConfig {
+    /** Enable cascading feature */
+    enabled: boolean;
+    /** Maximum number of cascades allowed in sequence */
+    maxCascades?: number;
+    /** Initial multiplier at start of cascade sequence */
+    initialMultiplier?: number;
+    /** Multiplier increment per cascade */
+    multiplierIncrement?: number;
+    /** Symbol pool for filling empty positions */
+    symbolPool?: ISymbol[];
+    /** Stop cascades if no win increase occurs */
+    stopOnNoWinIncrease?: boolean;
+    /** Trigger special feature on cascade count */
+    triggerOnCascadeCount?: number;
+    /** Trigger special feature on multiplier threshold */
+    triggerOnMultiplier?: number;
+    /** Trigger special feature on consecutive wins */
+    triggerOnConsecutiveWins?: number;
+}
+/**
+ * Single step in a cascade sequence.
+ */
+interface ICascadeStep {
+    /** Cascade number in sequence (1-based) */
+    cascadeNumber: number;
+    /** Positions where symbols were removed */
+    removedPositions: Array<{
+        reel: number;
+        row: number;
+        symbol: ISymbol;
+    }>;
+    /** Symbols that dropped due to gravity */
+    droppedSymbols: Array<{
+        symbol: ISymbol;
+        fromRow: number;
+        toRow: number;
+        reel: number;
+    }>;
+    /** New symbols added at top */
+    newSymbols: Array<{
+        symbol: ISymbol;
+        position: {
+            reel: number;
+            row: number;
+        };
+    }>;
+    /** Grid state after this cascade */
+    resultingGrid: ISymbol[][];
+    /** Wins evaluated in this step */
+    winsInStep: IWinEvaluation[];
+    /** Current multiplier */
+    multiplier: number;
+}
+/**
+ * Result of a full cascade sequence.
+ */
+interface ICascadeResult {
+    /** Whether cascades occurred */
+    success: boolean;
+    /** Total number of cascades */
+    totalCascades: number;
+    /** All steps in the cascade sequence */
+    steps: ICascadeStep[];
+    /** Final grid state */
+    finalGrid: ISymbol[][];
+    /** Final multiplier value */
+    finalMultiplier: number;
+    /** Total wins from all cascade steps */
+    totalWinsFromCascades: number;
+}
+/**
+ * Trigger conditions for wild expansion.
+ */
+type WildExpandTrigger = 'any_wild' | 'multiple_wilds' | 'specific_positions' | 'random';
+/**
+ * Configuration for expanding wild mechanics.
+ */
+interface IExpandingWildConfig {
+    /** Enable expanding wilds */
+    enabled: boolean;
+    /** Trigger condition for expansion */
+    triggerCondition: WildExpandTrigger;
+    /** Minimum wilds needed for 'multiple_wilds' trigger */
+    minWildsForExpand?: number;
+    /** Specific positions required for 'specific_positions' trigger */
+    specificPositions?: number[];
+    /** Probability for 'random' trigger (0-1) */
+    expansionProbability?: number;
+    /** Number of rows to expand to (default: entire reel) */
+    expandToRows?: number;
+    /** Multiplier applied by expanded wild */
+    wildMultiplier?: number;
+    /** How multipliers stack: 'multiply', 'add', or 'highest' */
+    multiplierStacking?: 'multiply' | 'add' | 'highest';
+}
+/**
+ * Result of expanding wild processing.
+ */
+interface IExpandingWildResult {
+    /** Whether expansion occurred */
+    success: boolean;
+    /** Reel indices that expanded */
+    expandedReels: number[];
+    /** All positions that became wild */
+    expandedPositions: Array<{
+        reel: number;
+        row: number;
+    }>;
+    /** Modified grid with expanded wilds */
+    modifiedGrid: ISymbol[][];
+    /** Total positions expanded */
+    totalExpanded: number;
+    /** Applied multiplier value */
+    appliedMultiplier: number;
+}
+/**
+ * Configuration for sticky wild mechanics.
+ */
+interface IStickyWildConfig {
+    /** Enable sticky wilds */
+    enabled: boolean;
+    /** Number of spins sticky wilds persist */
+    persistSpins: number;
+    /** Maximum number of sticky wilds allowed */
+    maxStickyWilds?: number;
+}
+/**
+ * Result of sticky wild processing.
+ */
+interface IStickyWildResult {
+    /** Whether sticky wild state changed */
+    success: boolean;
+    /** Currently active sticky wilds */
+    activeStickyWilds: Array<{
+        reel: number;
+        row: number;
+        remainingSpins: number;
+    }>;
+    /** Sticky wilds that expired */
+    removedStickyWilds: Array<{
+        reel: number;
+        row: number;
+    }>;
+    /** Modified grid */
+    modifiedGrid: ISymbol[][];
+    /** Total active sticky wilds */
+    totalActive: number;
+    /** Total removed sticky wilds */
+    totalRemoved: number;
+    /** Whether more sticky wilds can be added */
+    canAddMore: boolean;
+}
+/**
+ * Type of scatter trigger.
+ */
+type ScatterTriggerType = 'BONUS_TRIGGER' | 'REEL_COMBINATION_TRIGGER' | 'CLUSTER_TRIGGER' | 'COLLECTION_COMPLETE' | 'COLLECTION_EXPIRY_TRIGGER' | 'PROGRESSIVE_TRIGGER';
+/**
+ * Feature types triggered by scatters.
+ */
+type ScatterFeatureType = 'FREE_SPINS' | 'ENHANCED_BONUS' | 'CLUSTER_BONUS' | 'COLLECTION_BONUS' | 'MINI_BONUS';
+/**
+ * Individual scatter trigger event.
+ */
+interface IScatterTrigger {
+    /** Type of trigger */
+    type: ScatterTriggerType;
+    /** Whether trigger activated */
+    triggered: boolean;
+    /** Number of scatters involved */
+    scatterCount: number;
+    /** Feature type awarded */
+    featureType: ScatterFeatureType;
+    /** Free spins awarded (if applicable) */
+    awardedSpins?: number;
+    /** Cluster positions (for cluster triggers) */
+    clusterPositions?: Array<{
+        reel: number;
+        row: number;
+    }>;
+    /** Collected value (for collection triggers) */
+    collectedValue?: number;
+}
+/**
+ * Multiplier zone configuration for scatters.
+ */
+interface IScatterMultiplierZone {
+    reelStart: number;
+    reelEnd: number;
+    rowStart: number;
+    rowEnd: number;
+    multiplier: number;
+}
+/**
+ * Configuration for advanced scatter mechanics.
+ */
+interface IScatterConfig {
+    /** Enable scatter features */
+    enabled: boolean;
+    /** Minimum scatters for bonus trigger */
+    minScattersForTrigger?: number;
+    /** Feature type triggered */
+    triggeredFeature?: ScatterFeatureType;
+    /** Spin award table by scatter count */
+    spinAwardTable?: Record<number, number>;
+    /** Enable immediate scatter pays */
+    enableScatterPays?: boolean;
+    /** Pay table for scatter counts */
+    scatterPayTable?: Record<number, number>;
+    /** Scatter pay multiplier */
+    scatterMultiplier?: number;
+    /** Require scatters on specific reels */
+    requireSpecificReels?: boolean;
+    /** Required reel indices */
+    requiredReels?: number[];
+    /** Enable cluster-based triggers */
+    enableClusterTriggers?: boolean;
+    /** Minimum cluster size for trigger */
+    clusterSizeForTrigger?: number;
+    /** Enable progressive scatter accumulation */
+    enableProgressiveTrigger?: boolean;
+    /** Base threshold for progressive trigger */
+    baseProgressiveThreshold?: number;
+    /** Bonus spins for progressive trigger */
+    progressiveBonusSpins?: number;
+    /** Multiplier for progressive bonus */
+    progressiveMultiplier?: number;
+    /** Reset progressive on trigger */
+    progressiveResetOnTrigger?: boolean;
+    /** Enable scatter collection system */
+    enableCollection?: boolean;
+    /** Target scatter count for collection */
+    collectionTarget?: number;
+    /** Bonus spins on collection complete */
+    collectionBonusSpins?: number;
+    /** Auto-trigger when collection spins expire */
+    autoTriggerOnExpiry?: boolean;
+    /** Enable scatter transformation */
+    enableTransformation?: boolean;
+    /** Transformation type: 'to_wild' or 'to_multiplier' */
+    transformationType?: 'to_wild' | 'to_multiplier';
+    /** Multiplier for transformed wilds */
+    transformedWildMultiplier?: number;
+    /** Enable multiplier zones */
+    enableMultiplierZones?: boolean;
+    /** Multiplier zone definitions */
+    multiplierZones?: IScatterMultiplierZone[];
+    /** Zone multiplier stacking: 'multiply' or 'add' */
+    zoneMultiplierStacking?: 'multiply' | 'add';
+}
+/**
+ * Result of scatter evaluation.
+ */
+interface IScatterResult {
+    /** Whether scatters present */
+    success: boolean;
+    /** Total scatter count */
+    scatterCount: number;
+    /** Total scatter value */
+    scatterValue: number;
+    /** Scatter positions on grid */
+    positions: Array<{
+        reel: number;
+        row: number;
+        symbol: ISymbol;
+    }>;
+    /** Triggers activated */
+    triggers: IScatterTrigger[];
+    /** Immediate scatter payout */
+    scatterPays: number;
+    /** Scatters collected (for collection system) */
+    collectedScatters: number;
+}
+/**
+ * Extended symbol interface with additional properties.
+ */
+interface ISymbol {
+    id: string | number;
+    value?: number;
+    isWild: boolean;
+    isScatter: boolean;
+    /** Weight for random generation */
+    weight?: number;
+    /** For wilds: multiplier value */
+    wildMultiplier?: number;
+    /** For expanding wilds: original symbol ID */
+    expandedFrom?: string | number;
+    /** For sticky wilds: is sticky */
+    isSticky?: boolean;
+    /** For sticky wilds: remaining spins */
+    remainingSpins?: number;
+    /** For sticky wilds: unique identifier */
+    stickyId?: string;
+}
+/**
+ * Win evaluation result.
+ */
+interface IWinEvaluation {
+    /** Symbol ID that won */
+    symbolId: number;
+    /** Win amount */
+    amount: number;
+    /** Positions in the win */
+    positions: Array<{
+        reel: number;
+        row: number;
+    }>;
+    /** Line index (for line wins) */
+    lineIndex?: number;
+    /** Way index (for ways wins) */
+    wayIndex?: number;
+    /** Multiplier applied */
+    multiplier?: number;
+}
+/**
+ * Game state with grid representation.
+ */
+interface IGameState {
+    /** Grid of symbols [reel][row] */
+    grid: ISymbol[][];
+    /** Current bet */
+    bet: number;
+    /** Game mode */
+    gameMode: number;
+    /** Free spins remaining */
+    freeSpinsRemaining?: number;
+    /** Active bonus state */
+    bonusState?: any;
+}
+/**
+ * Money symbol interface for respins features.
+ */
+interface IMoneySymbol extends ISymbol {
+    /** Is this a money/value symbol */
+    isMoneySymbol?: boolean;
+    /** Cash value of the symbol */
+    value?: number;
+    /** Is this a reset symbol (resets respin counter) */
+    isResetSymbol?: boolean;
+    /** Is this a jackpot symbol */
+    isJackpotSymbol?: boolean;
+    /** Jackpot type if applicable */
+    jackpotType?: 'mini' | 'minor' | 'major' | 'grand';
+}
+/**
+ * Trigger type for respins feature.
+ */
+type RespinsTriggerType = 'symbol_count' | 'specific_positions';
+/**
+ * Position requirement for specific_positions trigger.
+ */
+interface IRespinsTriggerPosition {
+    row: number;
+    col: number;
+    symbolId?: string | number;
+}
+/**
+ * Weight configuration for symbol generation in respins.
+ */
+interface IRespinsSymbolWeight {
+    symbolId: string | number;
+    probability: number;
+    baseValue?: number;
+    isMoneySymbol?: boolean;
+    isResetSymbol?: boolean;
+    isJackpotSymbol?: boolean;
+    jackpotType?: 'mini' | 'minor' | 'major' | 'grand';
+}
+/**
+ * Full screen bonus configuration.
+ */
+interface IRespinsFullScreenBonus {
+    multiplier: number;
+    additionalAward?: number;
+}
+/**
+ * Configuration for respins/hold & win mechanics.
+ */
+interface IRespinsConfig {
+    /** Enable respins feature */
+    enabled: boolean;
+    /** Initial number of respins awarded */
+    initialRespins?: number;
+    /** Trigger type */
+    triggerType: RespinsTriggerType;
+    /** Minimum special symbols needed for trigger */
+    minTriggerSymbols?: number;
+    /** Specific positions required for trigger */
+    triggerPositions?: IRespinsTriggerPosition[];
+    /** Symbol weights for respin rounds */
+    symbolWeights?: IRespinsSymbolWeight[];
+    /** End feature if no new special symbols land */
+    endOnNoSpecial?: boolean;
+    /** Full screen bonus configuration */
+    fullScreenBonus?: IRespinsFullScreenBonus;
+    /** Grid size for respins (if different from base game) */
+    gridRows?: number;
+    gridCols?: number;
+}
+/**
+ * Single step in a respins sequence.
+ */
+interface IRespinsStep {
+    /** Respins remaining after this step */
+    respinsRemaining: number;
+    /** All locked positions */
+    lockedPositions: Array<{
+        row: number;
+        col: number;
+    }>;
+    /** New symbols that landed */
+    newSymbols: Array<{
+        row: number;
+        col: number;
+        symbolId: string | number;
+    }>;
+    /** Value added in this step */
+    valuesAdded: number;
+    /** Jackpots awarded in this step */
+    jackpotsAwarded: string[];
+    /** Reason for this step */
+    reason: 'initial_trigger' | 'respins' | 'jackpot_collected' | 'full_screen_bonus' | 'no_new_symbols';
+}
+/**
+ * Result of respins feature execution.
+ */
+interface IRespinsResult {
+    /** Whether feature was triggered */
+    triggered: boolean;
+    /** All steps in the respins sequence */
+    steps: IRespinsStep[];
+    /** Final total value collected */
+    finalValue: number;
+    /** All jackpots collected */
+    jackpotsCollected: string[];
+    /** Final locked positions */
+    lockedPositions: Array<{
+        row: number;
+        col: number;
+    }>;
+    /** Total respins used */
+    totalRespinsUsed: number;
+}
+type TransactionType = 'bet' | 'payout' | 'deposit' | 'withdrawal' | 'bonus_payout' | 'jackpot_win' | 'cascade_win' | 'scatter_win' | 'fee' | 'refund' | 'transfer';
+interface IWalletBalance {
+    userId: string;
+    amount: string;
+    version: number;
+    currency?: string;
+    updatedAt: Date;
+}
+interface ITransaction {
+    id: string;
+    userId: string;
+    type: TransactionType;
+    amount: string;
+    balanceBefore: string;
+    balanceAfter: string;
+    referenceId: string;
+    metadata?: Record<string, any>;
+    createdAt: Date;
+}
+interface IWalletConfig {
+    currency?: string;
+    precision?: number;
+    allowNegative?: boolean;
+    minBalance?: number;
+    maxBalance?: number;
+}
+interface ITransactionResult {
+    success: boolean;
+    balance?: string;
+    transactionId?: string;
+    error?: string;
+    code?: string;
+    message?: string;
+}
+/**
+ * Storage Interface - Implement this to connect to your DB (Postgres, Mongo, etc.)
+ */
+interface IWalletStorage {
+    getBalance(userId: string): Promise<IWalletBalance | null>;
+    updateBalance(userId: string, amount: string, version: number): Promise<IWalletBalance | null>;
+    recordTransaction(transaction: ITransaction): Promise<void>;
+    getTransactionHistory(userId: string, limit?: number): Promise<ITransaction[]>;
+}
+
+declare class ConfigBuilder {
+    private config;
+    setGameId(id: string): this;
+    setReelCount(count: number): this;
+    setRowCount(count: number): this;
+    setSymbolMap(map: SymbolMap): this;
+    setPaytableData(data: PaytableData): this;
+    setReelStrips(strips: ReelStrip[]): this;
+    setLinePatterns(patterns: PaylinePattern[]): this;
+    setCurrency(code: string, symbol: string, decimalSeparator?: string, thousandSeparator?: string, minDecimalPlaces?: number): this;
+    setFeatures(features: IGameConfigData['features']): this;
+    setBetRange(min: number, max: number, step: number, defaultBet?: number): this;
+    build(): IGameConfigData;
+}
+
+interface IBalanceProvider {
+    getBalance(playerId: string): number;
+    setBalance(playerId: string, amount: number): void;
+}
+declare class GameSession {
+    private config;
+    private playerId;
+    private balanceProvider;
+    private state;
+    private spinEvaluator;
+    private bonusManager;
+    private historyManager;
+    private rng;
+    constructor(config: IGameConfigData, playerId: string, balanceProvider: IBalanceProvider, seed?: number);
+    /**
+     * Get the current full player state.
+     */
+    getState(): IPlayerState;
+    /**
+     * Build the INIT response for the client.
+     */
+    getInitResponse(): IInitResponse;
+    /**
+     * Set the player's bet.
+     */
+    setBet(bet: number): void;
+    /**
+     * Process a spin request.
+     */
+    spin(request: ISpinRequestData): ISpinResponseData;
+    /**
+     * Get history.
+     */
+    getHistory(limit?: number): IHistoryResponse;
+    /**
+     * Process a bonus action (e.g., pick).
+     */
+    bonusAction(action: string, payload?: any): IBonusResponse;
+    /**
+     * Helper to create an error response.
+     */
+    private createErrorResponse;
+}
+
+/**
+ * Deterministic or non-deterministic RNG wrapper.
+ * For production, you can use a cryptographically secure generator.
+ */
+declare class Random {
+    private seed?;
+    constructor(seed?: number);
+    next(): number;
+    nextInt(min: number, max: number): number;
+    pick<T>(arr: T[]): T;
+    shuffle<T>(arr: T[]): T[];
+}
+
+declare class SpinEvaluator {
+    private config;
+    private rng;
+    constructor(config: IGameConfigData, rng: Random);
+    /**
+     * Generate a random spin result (visible symbols for each reel).
+     * Returns a 2D array: [reelIndex][rowIndex]
+     */
+    generateResult(): number[][];
+    /**
+     * Evaluate the result against all paylines and the paytable.
+     * Returns win lines and total win amount.
+     */
+    evaluateResult(result: number[][], stakePerLine: number): {
+        winLines: IWinLine[];
+        totalWin: number;
+    };
+    /**
+     * Full spin processing: generate result, evaluate, build response.
+     */
+    spin(request: ISpinRequestData): Omit<ISpinResponseData, 'balanceAfter'>;
+}
+
+declare class BonusManager {
+    private rng;
+    private bonusState;
+    constructor(rng: Random);
+    /**
+     * Check if a spin result should trigger a bonus.
+     * This is a simple example: trigger on 3+ scatter symbols (e.g., symbol ID 9).
+     */
+    checkTrigger(result: number[][]): {
+        triggered: boolean;
+        data?: any;
+    };
+    /**
+     * Start a free spin bonus.
+     */
+    startFreeSpins(spins: number, multiplier: number, bet: number): IFreeSpinBonus;
+    /**
+     * Start a pick bonus (e.g., pick items for prizes).
+     */
+    startPickBonus(items: {
+        id: string;
+        label: string;
+        value: number;
+    }[]): IPickBonus;
+    /**
+     * Process a pick action.
+     */
+    pickItem(itemId: string): {
+        win: number;
+        remaining: IPickBonus['items'];
+    };
+    /**
+     * Process a free spin: deduct one spin, return the spin result.
+     * The spin result is generated by the SpinEvaluator, but we need to apply the multiplier.
+     */
+    processFreeSpin(spinResult: Omit<ISpinResponseData, 'balanceAfter'>): Omit<ISpinResponseData, 'balanceAfter'> & {
+        spinsRemaining: number;
+    };
+    /**
+     * Check if a bonus is active.
+     */
+    isActive(): boolean;
+    /**
+     * Get the current bonus state.
+     */
+    getState(): IBonusState | null;
+    /**
+     * End the current bonus.
+     */
+    endBonus(): void;
+}
+
+declare class HistoryManager {
+    private history;
+    private maxEntries;
+    constructor(maxEntries?: number);
+    /**
+     * Add a spin result to history.
+     */
+    addEntry(result: number[][], bet: number, win: number, balance: number, gameMode: 0 | 1): void;
+    /**
+     * Get all history entries.
+     */
+    getEntries(): IHistoryEntry[];
+    /**
+     * Get the last N entries.
+     */
+    getLast(n: number): IHistoryEntry[];
+    /**
+     * Clear history.
+     */
+    clear(): void;
+}
+
+/**
+ * Manages progressive jackpot systems.
+ * Handles contributions, tier tracking, and jackpot triggers.
+ */
+declare class JackpotManager {
+    private config;
+    private rng;
+    private tiers;
+    constructor(config: IJackpotConfig, rng: Random);
+    /**
+     * Calculate jackpot contribution from a bet.
+     * Returns contributions for each tier.
+     */
+    calculateContribution(totalStake: number): IJackpotContribution[];
+    /**
+     * Check if a jackpot was triggered.
+     * Uses probability-based triggering.
+     */
+    checkTrigger(): IJackpotWin | null;
+    /**
+     * Get current jackpot amounts for all tiers.
+     */
+    getCurrentAmounts(): Record<string, number>;
+    /**
+     * Get a specific tier's current amount.
+     */
+    getTierAmount(tierId: string): number | undefined;
+    /**
+     * Update a tier's current amount (for external sync).
+     */
+    updateTierAmount(tierId: string, amount: number): void;
+    /**
+     * Check if a bet is eligible for jackpot (based on minBetRequired).
+     */
+    isBetEligible(totalStake: number): boolean;
+    /**
+     * Get configuration for a specific tier.
+     */
+    getTierConfig(tierId: string): IJackpotTier | undefined;
+    /**
+     * Get all tier configurations.
+     */
+    getAllTiers(): IJackpotTier[];
+    /**
+     * Reset all tiers to seed amounts.
+     */
+    resetAll(): void;
+}
+
+/**
+ * Evaluator for "ways to win" mechanics (e.g., 243 ways, 1024 ways).
+ * Instead of fixed paylines, wins are awarded for matching symbols
+ * on adjacent reels starting from the leftmost reel.
+ */
+declare class WaysEvaluator {
+    private config;
+    private paytableData;
+    private reelCount;
+    private rowCount;
+    constructor(config: IWaysConfig, paytableData: PaytableData, reelCount: number, rowCount: number);
+    /**
+     * Evaluate a spin result for ways-to-win.
+     * Returns win lines and total win amount.
+     */
+    evaluate(result: number[][], stakePerLine: number): {
+        winLines: IWinLine[];
+        totalWin: number;
+        ways: number;
+    };
+    /**
+     * Get the maximum possible ways for this configuration.
+     */
+    getMaxWays(): number;
+    /**
+     * Check if ways-to-win is enabled.
+     */
+    isEnabled(): boolean;
+}
+
+/**
+ * Manages gamble mini-games (card guess, ladder, wheel).
+ * Allows players to risk their winnings for a chance to multiply.
+ */
+declare class GambleManager {
+    private config;
+    private rng;
+    private consecutiveGambles;
+    private currentGambleWin;
+    constructor(config: IGambleConfig, rng: Random);
+    /**
+     * Check if gamble feature is enabled and available.
+     */
+    canGamble(currentWin: number): boolean;
+    /**
+     * Process a gamble request.
+     */
+    processGamble(request: IGambleRequest): IGambleResponse;
+    /**
+     * Card game: guess if card is red or black (50/50 chance).
+     */
+    private playCardGame;
+    /**
+     * Ladder game: 60% chance to win, 40% to lose.
+     */
+    private playLadderGame;
+    /**
+     * Wheel game: multiple outcomes based on wheel segments.
+     */
+    private playWheelGame;
+    /**
+     * Get current consecutive gamble count.
+     */
+    getConsecutiveGambles(): number;
+    /**
+     * Reset gamble state (e.g., after collecting winnings).
+     */
+    reset(): void;
+    /**
+     * Get the current gamble win amount.
+     */
+    getCurrentGambleWin(): number;
+    /**
+     * Get gamble configuration.
+     */
+    getConfig(): IGambleConfig;
+}
+
+/**
+ * Manages "buy bonus" feature.
+ * Allows players to purchase direct entry to bonus rounds.
+ */
+declare class BuyBonusManager {
+    private config;
+    private purchasesThisSession;
+    private lastPurchaseTime;
+    constructor(config: IBuyBonusConfig);
+    /**
+     * Check if buying bonus is enabled and available.
+     */
+    canBuyBonus(currentBet: number): {
+        canBuy: boolean;
+        reason?: string;
+        cost?: number;
+    };
+    /**
+     * Calculate the cost to buy bonus.
+     */
+    calculateCost(currentBet: number): number;
+    /**
+     * Record a bonus purchase.
+     */
+    recordPurchase(): void;
+    /**
+     * Get the number of purchases made this session.
+     */
+    getPurchasesThisSession(): number;
+    /**
+     * Reset session tracking.
+     */
+    resetSession(): void;
+    /**
+     * Get configuration.
+     */
+    getConfig(): IBuyBonusConfig;
+    /**
+     * Create a spin response that triggers bonus (for buy bonus feature).
+     * This marks the spin as having triggered the bonus.
+     */
+    createBonusTriggerSpin(baseSpinResult: Omit<ISpinResponseData, 'balanceAfter'>, bonusData: any): Omit<ISpinResponseData, 'balanceAfter'>;
+}
+
+/**
+ * CascadingReelsManager - Handles tumbling/cascading reel mechanics
+ *
+ * Features:
+ * - Symbol removal after wins
+ * - Gravity-based symbol drops
+ * - New symbol generation at top
+ * - Chain reaction evaluation
+ * - Progressive multiplier support
+ * - Cascade termination conditions
+ */
+declare class CascadingReelsManager {
+    private config;
+    constructor(config: ICascadeConfig);
+    /**
+     * Execute a full cascade sequence until no more wins occur
+     */
+    executeCascade(gameState: IGameState, initialWins: IWinEvaluation[]): ICascadeResult;
+    /**
+     * Remove symbols that are part of winning combinations
+     */
+    private removeWinningSymbols;
+    /**
+     * Apply gravity to make symbols fall down into empty positions
+     */
+    private applyGravity;
+    /**
+     * Fill empty positions at the top with new random symbols
+     */
+    private fillEmptyPositions;
+    /**
+     * Generate a symbol based on weighted probabilities
+     */
+    private generateWeightedSymbol;
+    /**
+     * Evaluate wins on the current grid state
+     * This is a simplified version - in production you'd integrate with your WinEvaluator
+     */
+    private evaluateWins;
+    /**
+     * Check if a cascade sequence should trigger special features
+     */
+    checkCascadeTriggers(cascadeResult: ICascadeResult): {
+        triggers: string[];
+        data?: any;
+    };
+}
+
+/**
+ * ExpandingWildsManager - Handles expanding and sticky wild mechanics
+ *
+ * Features:
+ * - Wild expansion to cover entire reel
+ * - Sticky wilds that persist for multiple spins
+ * - Wild multiplier application
+ * - Interaction with win evaluation
+ * - Visual position tracking for animations
+ */
+declare class ExpandingWildsManager {
+    private expandConfig;
+    private stickyConfig;
+    constructor(expandConfig: IExpandingWildConfig, stickyConfig?: IStickyWildConfig);
+    /**
+     * Process expanding wilds on the current grid
+     */
+    processExpandingWilds(gameState: IGameState): IExpandingWildResult;
+    /**
+     * Determine if a reel should expand based on configuration
+     */
+    private shouldReelExpand;
+    /**
+     * Check if wilds exist in specific configured positions
+     */
+    private hasWildInSpecificPositions;
+    /**
+     * Apply sticky wilds logic for persistent wilds across spins
+     */
+    processStickyWilds(gameState: IGameState, existingStickyWilds: Array<{
+        reel: number;
+        row: number;
+        remainingSpins: number;
+    }>): IStickyWildResult;
+    /**
+     * Add new sticky wilds to the grid
+     */
+    addStickyWilds(gameState: IGameState, positions: Array<{
+        reel: number;
+        row: number;
+    }>, persistSpins?: number): IStickyWildResult;
+    /**
+     * Calculate multiplier effect from wilds in a win line
+     */
+    calculateWildMultiplier(winPositions: Array<{
+        reel: number;
+        row: number;
+    }>, grid: ISymbol[][]): number;
+    /**
+     * Check for special wild interactions (e.g., expanding wild meeting sticky wild)
+     */
+    checkWildInteractions(grid: ISymbol[][]): {
+        interactions: string[];
+        data?: any;
+    };
+}
+
+/**
+ * ScatterEnhancementsManager - Advanced scatter symbol mechanics
+ *
+ * Features:
+ * - Configurable scatter trigger conditions
+ * - Scatter collection systems
+ * - Progressive scatter triggers
+ * - Scatter multiplier zones
+ * - Scatter transformation mechanics
+ * - Dynamic scatter behavior
+ */
+declare class ScatterEnhancementsManager {
+    private config;
+    constructor(config: IScatterConfig);
+    /**
+     * Evaluate scatter symbols on the current grid
+     */
+    evaluateScatters(gameState: IGameState): IScatterResult;
+    /**
+     * Check if scatter conditions trigger bonus features
+     */
+    private checkTriggerConditions;
+    /**
+     * Calculate number of spins awarded based on scatter count
+     */
+    private calculateAwardedSpins;
+    /**
+     * Calculate immediate scatter payouts
+     */
+    private calculateScatterPays;
+    /**
+     * Find clusters of adjacent scatter symbols
+     */
+    private findScatterClusters;
+    /**
+     * Flood fill algorithm to find connected scatter positions
+     */
+    private floodFillCluster;
+    /**
+     * Manage scatter collection system (collect scatters over multiple spins)
+     */
+    manageScatterCollection(currentScatters: IScatterResult, collectedData: {
+        count: number;
+        values: number[];
+        spinsRemaining: number;
+    }): {
+        updated: typeof collectedData;
+        collectionTrigger?: IScatterTrigger;
+    };
+    /**
+     * Apply scatter transformation mechanics (e.g., scatters becoming wilds)
+     */
+    transformScatters(gameState: IGameState, scatterPositions: Array<{
+        reel: number;
+        row: number;
+    }>): {
+        modifiedGrid: ISymbol[][];
+        transformed: Array<{
+            reel: number;
+            row: number;
+        }>;
+    };
+    /**
+     * Check for scatter in multiplier zones (special grid areas)
+     */
+    checkMultiplierZones(scatterPositions: Array<{
+        reel: number;
+        row: number;
+    }>): {
+        totalMultiplier: number;
+        zoneHits: Array<{
+            reel: number;
+            row: number;
+            multiplier: number;
+        }>;
+    };
+    /**
+     * Implement progressive scatter trigger (accumulates across game session)
+     */
+    updateProgressiveScatter(currentCount: number, progressiveState: {
+        accumulated: number;
+        threshold: number;
+        level: number;
+    }): {
+        updated: typeof progressiveState;
+        triggered: boolean;
+        reward?: any;
+    };
+}
+
+/**
+ * RespinsManager - Handles Hold & Win / Respins mechanics
+ *
+ * Features:
+ * - Locking symbols for respin rounds
+ * - Money symbol collection and value summation
+ * - Reset symbols that grant additional respins
+ * - Jackpot symbols (Mini, Minor, Major, Grand)
+ * - Progressive feature triggers
+ * - Configurable grid sizes and respin counts
+ */
+declare class RespinsManager {
+    private config;
+    constructor(config: IRespinsConfig);
+    /**
+     * Check if respin feature should be triggered
+     */
+    checkTrigger(gameState: IGameState): boolean;
+    /**
+     * Count special symbols (money, reset, jackpot) on the grid
+     */
+    private countSpecialSymbols;
+    /**
+     * Check if special symbols are in required positions
+     */
+    private checkSpecificPositions;
+    /**
+     * Check if a symbol is a special respin symbol
+     */
+    private isSpecialSymbol;
+    /**
+     * Execute the respins feature
+     */
+    execute(gameState: IGameState): IRespinsResult;
+    /**
+     * Generate a special symbol for respins (weighted random)
+     * In production, this should use a certified RNG with configurable weights
+     */
+    private generateRespinsSymbol;
+    /**
+     * Calculate potential payout for respins feature
+     */
+    calculatePotentialPayout(betAmount: number): number;
+    /**
+     * Get configuration for client-side preview
+     */
+    getConfig(): IRespinsConfig;
+}
+
+/**
+ * In-Memory Implementation of IWalletStorage
+ * Useful for testing or serverless environments without a DB connection.
+ * NOT recommended for production persistent storage.
+ */
+declare class InMemoryWalletStorage implements IWalletStorage {
+    private balances;
+    private transactions;
+    getBalance(userId: string): Promise<IWalletBalance | null>;
+    updateBalance(userId: string, amount: string, version: number): Promise<IWalletBalance | null>;
+    recordTransaction(transaction: ITransaction): Promise<void>;
+    getTransactionHistory(userId: string, limit?: number): Promise<ITransaction[]>;
+}
+/**
+ * WalletManager
+ * Handles atomic financial operations for the slot engine.
+ */
+declare class WalletManager {
+    private storage;
+    private config;
+    constructor(storage: IWalletStorage, config: IWalletConfig);
+    /**
+     * Place a bet (deduct funds)
+     */
+    placeBet(userId: string, amount: number, gameId: string, roundId: string): Promise<ITransactionResult>;
+    /**
+     * Credit winnings
+     */
+    creditWin(userId: string, amount: number, gameId: string, roundId: string, winType?: 'normal' | 'bonus' | 'jackpot'): Promise<ITransactionResult>;
+    /**
+     * Core transaction logic with optimistic locking
+     */
+    private executeTransaction;
+    /**
+     * Transfer funds between users (e.g., P2P features)
+     */
+    transfer(fromId: string, toId: string, amount: number): Promise<ITransactionResult>;
+}
+
+/**
+ * Audit record storage interface.
+ */
+interface IAuditStorage {
+    save(record: IAuditRecord): Promise<void>;
+    findByPlayer(playerId: string, startTime: number, endTime: number): Promise<IAuditRecord[]>;
+    findById(spinId: string): Promise<IAuditRecord | null>;
+    getSummary(playerId: string, startTime: number, endTime: number): Promise<IPlayerActivitySummary>;
+}
+/**
+ * In-memory audit storage (for development/testing).
+ * In production, replace with database-backed implementation.
+ */
+declare class InMemoryAuditStorage implements IAuditStorage {
+    private records;
+    private playerIndex;
+    save(record: IAuditRecord): Promise<void>;
+    findByPlayer(playerId: string, startTime: number, endTime: number): Promise<IAuditRecord[]>;
+    findById(spinId: string): Promise<IAuditRecord | null>;
+    getSummary(playerId: string, startTime: number, endTime: number): Promise<IPlayerActivitySummary>;
+    /**
+     * Clear all records (for testing).
+     */
+    clear(): void;
+    /**
+     * Get total record count.
+     */
+    getCount(): number;
+}
+/**
+ * Audit Manager for regulatory compliance and game integrity.
+ * Records all spins, transactions, and significant events.
+ */
+declare class AuditManager {
+    private storage;
+    private gameId;
+    private operatorId?;
+    constructor(gameId: string, storage?: IAuditStorage, operatorId?: string);
+    /**
+     * Record a spin for audit purposes.
+     */
+    recordSpin(params: {
+        spinId: string;
+        playerId: string;
+        sessionId: string;
+        stake: number;
+        win: number;
+        balanceBefore: number;
+        balanceAfter: number;
+        rngSeed: string;
+        result: number[][];
+        gameMode: 0 | 1;
+        bonusTriggered: boolean;
+        jackpotContributions: IJackpotContribution[];
+        jackpotWins: IJackpotWin[];
+        ipAddress?: string;
+        deviceInfo?: string;
+        location?: string;
+        platform?: 'web' | 'mobile' | 'desktop';
+    }): Promise<IAuditRecord>;
+    /**
+     * Get audit records for a player within a time range.
+     */
+    getPlayerRecords(playerId: string, startTime: number, endTime: number): Promise<IAuditRecord[]>;
+    /**
+     * Get a specific spin record by ID.
+     */
+    getSpinRecord(spinId: string): Promise<IAuditRecord | null>;
+    /**
+     * Get player activity summary for a period.
+     */
+    getPlayerSummary(playerId: string, startTime: number, endTime: number): Promise<IPlayerActivitySummary>;
+    /**
+     * Export records for regulatory reporting.
+     */
+    exportRecords(playerId: string, startTime: number, endTime: number, format?: 'json' | 'csv'): Promise<string>;
+    /**
+     * Verify game integrity by checking RNG seed chain.
+     */
+    verifyRngChain(spinIds: string[]): Promise<{
+        valid: boolean;
+        errors: string[];
+    }>;
+}
+
+/**
+ * Debug Manager for testing and development.
+ * Provides logging, forced outcomes, and state inspection.
+ */
+declare class DebugManager {
+    private config;
+    private spinCount;
+    private lastRngSeed;
+    private forcedOutcomesApplied;
+    private logs;
+    constructor(config?: Partial<IDebugConfig>);
+    /**
+     * Update debug configuration.
+     */
+    configure(config: Partial<IDebugConfig>): void;
+    /**
+     * Check if debug mode is enabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Get current debug state.
+     */
+    getState(): IDebugState;
+    /**
+     * Reset debug state and logs.
+     */
+    reset(): void;
+    /**
+     * Log a message at specified level.
+     */
+    log(level: IDebugLogEntry['level'], category: string, message: string, data?: any): void;
+    /**
+     * Log a spin result.
+     */
+    logSpin(spinId: string, result: ISpinResponseData, rngSeed: string): void;
+    /**
+     * Check and apply forced outcome if conditions match.
+     */
+    checkForcedOutcome(params: {
+        spinNumber: number;
+        rngSeed: string;
+        betAmount: number;
+        playerId: string;
+    }): ISpinResponseData | null;
+    /**
+     * Check if balance checks should be skipped.
+     */
+    shouldSkipBalanceCheck(): boolean;
+    /**
+     * Get all logs (optionally filtered by level).
+     */
+    getLogs(level?: IDebugLogEntry['level']): IDebugLogEntry[];
+    /**
+     * Export logs as JSON.
+     */
+    exportLogs(): string;
+    /**
+     * Clear all logs.
+     */
+    clearLogs(): void;
+    /**
+     * Determine if a log level should be output based on verboseLevel config.
+     */
+    private shouldLogLevel;
+    /**
+     * Output log entry based on outputFormat config.
+     */
+    private outputLog;
+    /**
+     * Get statistics about logged events.
+     */
+    getStatistics(): {
+        totalLogs: number;
+        errorCount: number;
+        warningCount: number;
+        infoCount: number;
+        debugCount: number;
+        spinsTracked: number;
+        forcedOutcomesApplied: number;
+    };
+}
+
+/**
+ * Session time tracking information.
+ */
+interface ISessionTimeInfo {
+    sessionStartTime: number;
+    elapsedMinutes: number;
+    limitMinutes?: number;
+    isLimitReached: boolean;
+    warningThresholdReached: boolean;
+}
+/**
+ * Loss tracking information.
+ */
+interface ILossTrackingInfo {
+    sessionLoss: number;
+    lossLimit?: number;
+    isLimitReached: boolean;
+    warningThresholdReached: boolean;
+}
+/**
+ * Win tracking information.
+ */
+interface IWinTrackingInfo {
+    sessionWin: number;
+    winGoal?: number;
+    isGoalReached: boolean;
+    notificationSent: boolean;
+}
+/**
+ * Reality check event.
+ */
+interface IRealityCheckEvent {
+    timestamp: number;
+    elapsedMinutes: number;
+    totalSpins: number;
+    totalStaked: number;
+    totalWon: number;
+    netResult: number;
+    message: string;
+}
+/**
+ * Self-exclusion status.
+ */
+interface ISelfExclusionStatus {
+    isExcluded: boolean;
+    exclusionUntil?: Date;
+    remainingDays?: number;
+    reason?: string;
+}
+/**
+ * Responsible gaming alert.
+ */
+interface IRGAlert {
+    type: 'session_time' | 'loss_limit' | 'win_goal' | 'reality_check' | 'self_exclusion' | 'bet_limit';
+    severity: 'info' | 'warning' | 'critical';
+    message: string;
+    timestamp: number;
+    actionRequired?: boolean;
+    suggestedAction?: string;
+}
+/**
+ * Player activity statistics for responsible gaming.
+ */
+interface IPlayerActivityStats {
+    totalSessions: number;
+    totalTimePlayed: number;
+    totalStaked: number;
+    totalWon: number;
+    netResult: number;
+    averageSessionDuration: number;
+    longestSession: number;
+    biggestLoss: number;
+    biggestWin: number;
+    lastSessionDate?: number;
+}
+/**
+ * Responsible Gaming Manager - Comprehensive player protection system.
+ *
+ * Features:
+ * - Session time limits with warnings
+ * - Loss limits with automatic blocking
+ * - Win goals with notifications
+ * - Reality check reminders
+ * - Self-exclusion enforcement
+ * - Bet limit enforcement
+ * - Activity monitoring and alerts
+ * - Pattern analysis for problem gambling detection
+ */
+declare class ResponsibleGamingManager {
+    private limits;
+    private playerState;
+    private alerts;
+    private realityCheckCounter;
+    private lastRealityCheckTime;
+    constructor(limits: IResponsibleGamingLimits, playerState: IPlayerState);
+    /**
+     * Update player state (call after each spin).
+     */
+    updatePlayerState(state: Partial<IPlayerState>): void;
+    /**
+     * Update responsible gaming limits (e.g., player changed their limits).
+     */
+    updateLimits(newLimits: Partial<IResponsibleGamingLimits>): void;
+    /**
+     * Check if player can place a bet of the given amount.
+     */
+    canPlaceBet(betAmount: number): Result<boolean, string>;
+    /**
+     * Check if player can continue playing (general eligibility).
+     */
+    canContinuePlaying(): Result<boolean, string>;
+    /**
+     * Get session time tracking information.
+     */
+    getSessionTimeInfo(): ISessionTimeInfo;
+    /**
+     * Get loss tracking information.
+     */
+    getLossTrackingInfo(): ILossTrackingInfo;
+    /**
+     * Get win tracking information.
+     */
+    getWinTrackingInfo(): IWinTrackingInfo;
+    /**
+     * Get self-exclusion status.
+     */
+    getSelfExclusionStatus(): ISelfExclusionStatus;
+    /**
+     * Check if reality check is due.
+     */
+    shouldShowRealityCheck(): boolean;
+    /**
+     * Generate reality check event.
+     */
+    generateRealityCheck(): IRealityCheckEvent | null;
+    /**
+     * Check all limits and generate alerts.
+     */
+    private checkAllLimits;
+    /**
+     * Add an alert to the list.
+     */
+    private addAlert;
+    /**
+     * Get all active alerts.
+     */
+    getAlerts(): IRGAlert[];
+    /**
+     * Clear alerts (call after player acknowledges them).
+     */
+    clearAlerts(): void;
+    /**
+     * Get player activity statistics.
+     */
+    getPlayerActivityStats(): IPlayerActivityStats;
+    /**
+     * Validate limits configuration.
+     */
+    private validateLimits;
+    /**
+     * Reset session tracking (call when player starts new session).
+     */
+    resetSession(): void;
+    /**
+     * Apply a win/loss result to session tracking.
+     */
+    applyResult(stake: number, win: number): void;
+    /**
+     * Export responsible gaming report for player download.
+     */
+    exportRGReport(): string;
+}
+
+declare const sampleConfig: IGameConfigData;
+
+export { AuditManager, BonusManager, BuyBonusManager, CascadingReelsManager, ConfigBuilder, DebugManager, type DeepPartial, ExpandingWildsManager, GambleManager, GameSession, HistoryManager, type IAuditRecord, type IBonusResponse, type IBonusState, type IBuyBonusConfig, type IBuyBonusRequest, type ICascadeBonus, type ICascadeConfig, type ICascadeResult, type ICascadeStep, type ICurrencyConfig, type IDebugConfig, type IDebugLogEntry, type IDebugState, type IExpandingWildConfig, type IExpandingWildResult, type IForcedOutcome, type IFreeSpinBonus, type IFreeSpinsConfig, type IGambleConfig, type IGambleRequest, type IGambleResponse, type IGameConfigData, type IGameState, type IHistoryEntry, type IHistoryResponse, type IHoldAndSpinBonus, type IInitResponse, type IJackpotConfig, type IJackpotContribution, type IJackpotTier, type IJackpotWin, type IMoneySymbol, type IPickBonus, type IPlayerActivitySummary, type IPlayerState, type IRespinsBonus, type IRespinsConfig, type IRespinsFullScreenBonus, type IRespinsResult, type IRespinsStep, type IRespinsSymbolWeight, type IRespinsTriggerPosition, type IResponsibleGamingLimits, type IScatterConfig, type IScatterMultiplierZone, type IScatterResult, type IScatterTrigger, type IServerAck, type ISpinRequestData, type ISpinResponseData, type IStickyWildConfig, type IStickyWildResult, type ISymbol, type ISymbolConfig, type ITournamentConfig, type ITournamentPlayer, type ITournamentSpinRequest, type ITournamentState, type ITransaction, type ITransactionResult, type IWalletBalance, type IWalletConfig, type IWalletStorage, type IWaysConfig, type IWebSocketMessage, type IWheelBonus, type IWinDetails, type IWinEvaluation, type IWinLine, InMemoryAuditStorage, InMemoryWalletStorage, JackpotManager, type Nullable, type PaylinePattern, type PaytableData, Random, type ReelStrip, RespinsManager, type RespinsTriggerType, ResponsibleGamingManager, type Result, ScatterEnhancementsManager, type ScatterFeatureType, type ScatterTriggerType, SpinEvaluator, type SymbolBehavior, type SymbolMap, type TransactionType, WalletManager, WaysEvaluator, type WildExpandTrigger, sampleConfig };