@slot-engine/core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1306 @@
+declare class GameSymbol {
+    id: string;
+    pays?: Record<number, number>;
+    properties: Map<string, any>;
+    constructor(opts: GameSymbolOpts);
+    /**
+     * Compares this symbol to another symbol or a set of properties.
+     */
+    compare(symbolOrProperties?: GameSymbol | Record<string, any>): boolean;
+}
+interface GameSymbolOpts {
+    /**
+     * Unique identifier for the symbol, e.g. "W", "H1", "L5", etc.
+     */
+    id: string;
+    /**
+     * Paytable for the symbol, where the key is the number of symbols and the value is the payout multiplier.
+     */
+    pays?: Record<number, number>;
+    /**
+     * Additional properties for the symbol, e.g. `multiplier` or `isWild`.
+     *
+     * Properties can help identify special symbols.
+     *
+     * @example
+     * If your game has a "normal" scatter and a "super" scatter, you can define them like this:
+     *
+     * ```ts
+     * properties: {
+     *   isScatter: true,
+     * }
+     * ```
+     */
+    properties?: Record<string, any>;
+}
+
+declare function weightedRandom<T extends Record<string, number>>(weights: T, rng: RandomNumberGenerator): string;
+declare class RandomNumberGenerator {
+    mIdum: number;
+    mIy: number;
+    mIv: Array<number>;
+    NTAB: number;
+    IA: number;
+    IM: number;
+    IQ: number;
+    IR: number;
+    NDIV: number;
+    AM: number;
+    RNMX: number;
+    protected _currentSeed: number;
+    constructor();
+    getCurrentSeed(): number;
+    protected setCurrentSeed(seed: number): void;
+    setSeed(seed: number): void;
+    setSeedIfDifferent(seed: number): void;
+    generateRandomNumber(): number;
+    randomFloat(low: number, high: number): number;
+}
+
+/**
+ * This class is responsible for generating reel sets for slot games based on specified configurations.
+ *
+ * **While it offers a high degree of customization, some configurations may lead to unsolvable scenarios.**
+ *
+ * If the reel generator is unable to fulfill niche constraints,\
+ * you might need to adjust your configuration, or edit the generated reels manually.\
+ * Setting a different seed may also help.
+ */
+declare class ReelGenerator {
+    id: string;
+    associatedGameModeName: string;
+    protected readonly symbolWeights: Map<string, number>;
+    protected readonly rowsAmount: number;
+    reels: Reels;
+    protected limitSymbolsToReels?: Record<string, number[]>;
+    protected readonly spaceBetweenSameSymbols?: number | Record<string, number>;
+    protected readonly spaceBetweenSymbols?: Record<string, Record<string, number>>;
+    protected readonly preferStackedSymbols?: number;
+    protected readonly symbolStacks?: Record<string, {
+        chance: number | Record<string, number>;
+        min?: number | Record<string, number>;
+        max?: number | Record<string, number>;
+    }>;
+    protected readonly symbolQuotas?: Record<string, number | Record<string, number>>;
+    outputDir: string;
+    csvPath: string;
+    overrideExisting: boolean;
+    rng: RandomNumberGenerator;
+    constructor(opts: ReelGeneratorOpts);
+    private validateConfig;
+    private isSymbolAllowedOnReel;
+    private resolveStacking;
+    private tryPlaceStack;
+    /**
+     * Checks if a symbol can be placed at the target index without violating spacing rules.
+     */
+    private violatesSpacing;
+    generateReels(gameConf: AnyGameConfig): void;
+    /**
+     * Reads a reelset CSV file and returns the reels as arrays of GameSymbols.
+     */
+    parseReelsetCSV(reelSetPath: string, { config }: GameConfig): Reels;
+}
+interface ReelGeneratorOpts {
+    /**
+     * The unique identifier of the reel generator.\
+     * Must be unique per game mode.
+     */
+    id: string;
+    /**
+     * The weights of the symbols in the reelset.\
+     * This is a mapping of symbol IDs to their respective weights.
+     */
+    symbolWeights: Record<string, number>;
+    /**
+     * The number of rows in the reelset.\
+     * Default is 250, but can be adjusted as needed.
+     */
+    rowsAmount?: number;
+    /**
+     * The directory where the generated reelset files will be saved.\
+     * **It's recommended to just use `__dirname`**!
+     */
+    outputDir: string;
+    /**
+     * Prevent the same symbol from appearing directly above or below itself.\
+     * This can be a single number for all symbols, or a mapping of symbol IDs to
+     * their respective spacing values.
+     *
+     * Must be 1 or higher, if set.
+     *
+     * **This is overridden by `symbolStacks`**
+     */
+    spaceBetweenSameSymbols?: number | Record<string, number>;
+    /**
+     * Prevents specific symbols from appearing within a certain distance of each other.
+     *
+     * Useful for preventing scatter and super scatter symbols from appearing too close to each other.
+     *
+     * **This is overridden by `symbolStacks`**
+     */
+    spaceBetweenSymbols?: Record<string, Record<string, number>>;
+    /**
+     * A percentage value 0-100 that indicates the likelihood of a symbol being stacked.\
+     * A value of 0 means no stacked symbols, while 100 means all symbols are stacked.
+     *
+     * This is only a preference. Symbols may still not be stacked if\
+     * other restrictions (like `spaceBetweenSameSymbols`) prevent it.
+     *
+     * **This is overridden by `symbolStacks`**
+     */
+    preferStackedSymbols?: number;
+    /**
+     * A mapping of symbols to their respective advanced stacking configuration.
+     *
+     * @example
+     * ```ts
+     * symbolStacks: {
+     *   "W": {
+     *     chance: { "1": 20, "2": 20, "3": 20, "4": 20 }, // 20% chance to be stacked on reels 2-5
+     *     min: 2, // At least 2 wilds in a stack
+     *     max: 4, // At most 4 wilds in a stack
+     *   }
+     * }
+     * ```
+     */
+    symbolStacks?: Record<string, {
+        chance: number | Record<string, number>;
+        min?: number | Record<string, number>;
+        max?: number | Record<string, number>;
+    }>;
+    /**
+     * Configures symbols to be limited to specific reels.\
+     * For example, you could configure Scatters to appear only on reels 1, 3 and 5.
+     *
+     * @example
+     * ```ts
+     * limitSymbolsToReels: {
+     *   "S": [0, 2, 4], // Remember that reels are 0-indexed.
+     * }
+     * ```
+     */
+    limitSymbolsToReels?: Record<string, number[]>;
+    /**
+     * Defines optional quotas for symbols on the reels.\
+     * The quota (1-100%) defines how often a symbol should appear in the reelset, or in a specific reel.
+     *
+     * This is particularly useful for controlling the frequency of special symbols like scatters or wilds.
+     *
+     * Reels not provided for a symbol will use the weights from `symbolWeights`.
+     *
+     * _Any_ small quota will ensure that the symbol appears at least once on the reel.
+     *
+     * @example
+     * ```ts
+     * symbolQuotas: {
+     *   "S": 3, // 3% of symbols on each reel will be scatters
+     *   "W": { "1": 10, "2": 5, "3": 3, "4": 1 }, // Wilds will appear with different quotas on selected reels
+     * }
+     * ```
+     */
+    symbolQuotas?: Record<string, number | Record<string, number>>;
+    /**
+     * If true, existing reels CSV files will be overwritten.
+     */
+    overrideExisting?: boolean;
+    /**
+     * Optional seed for the RNG to ensure reproducible results.
+     *
+     * Default seed is `0`.
+     *
+     * Note: Seeds 0 and 1 produce the same results.
+     */
+    seed?: number;
+}
+type Reels = GameSymbol[][];
+
+declare class GameMode {
+    name: GameModeName;
+    reelsAmount: number;
+    symbolsPerReel: number[];
+    cost: number;
+    rtp: number;
+    reelSets: ReelGenerator[];
+    resultSets: ResultSet<any>[];
+    isBonusBuy: boolean;
+    constructor(opts: GameModeOpts);
+}
+interface GameModeOpts {
+    /**
+     * Name of the game mode.
+     */
+    name: GameModeName;
+    /**
+     * Number of reels the board has.
+     */
+    reelsAmount: number;
+    /**
+     * How many symbols each reel has. Array length must match `reelsAmount`.\
+     * The number at an array index represents the number of symbols on that reel.
+     */
+    symbolsPerReel: number[];
+    /**
+     * Cost of the game mode, multiplied by the base bet.
+     */
+    cost: number;
+    /**
+     * The target RTP of the game.
+     */
+    rtp: number;
+    /**
+     * Defines and generates all reels for the game.\
+     * Which reels are used in a spin is determined by the ResultSet of the current game mode.
+     *
+     * It is common to have one reel set for the base game and another for free spins.\
+     * Each `ResultSet` can then set the weights of these reel sets to control which\
+     * reel set is used for a specific criteria.
+     *
+     * The generator can be adjusted to match the reels to your games needs.
+     */
+    reelSets: ReelGenerator[];
+    /**
+     * A ResultSet defines how often a specific outcome should be generated.\
+     * For example, a ResultSet can be used to force a specific ratio of max wins\
+     * in the simulations to ensure there are different frontend representations.
+     */
+    resultSets: ResultSet<any>[];
+    /**
+     * Whether this game mode is a bonus buy.
+     */
+    isBonusBuy: boolean;
+}
+type GameModeName = "base" | "base-extra-chance-2x" | "base-extra-chance-10x" | "bonus" | string;
+
+declare class Simulation {
+    protected readonly gameConfigOpts: CommonGameOptions;
+    readonly gameConfig: GameConfig;
+    readonly simRunsAmount: Partial<Record<GameModeName, number>>;
+    private readonly concurrency;
+    private wallet;
+    private library;
+    readonly records: RecordItem[];
+    protected debug: boolean;
+    constructor(opts: SimulationConfigOpts, gameConfigOpts: CommonGameOptions);
+    runSimulation(opts: SimulationOpts): Promise<void>;
+    /**
+     * Runs all simulations for a specific game mode.
+     */
+    spawnWorkersForGameMode(opts: {
+        mode: string;
+        simNumsToCriteria: Record<number, string>;
+    }): Promise<void>;
+    callWorker(opts: {
+        basePath: string;
+        mode: string;
+        simStart: number;
+        simEnd: number;
+        index: number;
+        totalSims: number;
+    }): Promise<unknown>;
+    /**
+     * Creates a CSV file in the format "simulationId,weight,payout".
+     *
+     * `weight` defaults to 1.
+     */
+    private static writeLookupTableCSV;
+    /**
+     * Creates a CSV file in the format "simulationId,criteria,payoutBase,payoutFreespins".
+     */
+    private static writeLookupTableSegmentedCSV;
+    private static writeRecords;
+    private static writeIndexJson;
+    private static writeBooksJson;
+    private static logSymbolOccurrences;
+    /**
+     * Compiles user configured game to JS for use in different Node processes
+     */
+    private preprocessFiles;
+    private getSimRangesForChunks;
+    private mergeRecords;
+}
+type SimulationConfigOpts = {
+    /**
+     * Object containing the game modes and their respective simulation runs amount.
+     */
+    simRunsAmount: Partial<Record<GameModeName, number>>;
+    /**
+     * Number of concurrent processes to use for simulations.
+     *
+     * Default: 6
+     */
+    concurrency?: number;
+};
+/**
+ * @internal
+ */
+type AnySimulationContext<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> = SimulationContext<TGameModes, TSymbols, TUserState>;
+/**
+ * @internal
+ */
+declare class SimulationContext<TGameModes extends AnyGameModes, TSymbols extends AnySymbols, TUserState extends AnyUserData> extends Board<TGameModes, TSymbols, TUserState> {
+    constructor(opts: CommonGameOptions<any, any, TUserState>);
+    actualSims: number;
+    /**
+     * Will run a single simulation until the specified criteria is met.
+     */
+    runSingleSimulation(opts: {
+        simId: number;
+        mode: string;
+        criteria: string;
+        index: number;
+    }): void;
+    /**
+     * If a simulation does not meet the required criteria, reset the state to run it again.
+     *
+     * This also runs once before each simulation to ensure a clean state.
+     */
+    protected resetSimulation(): void;
+    /**
+     * Contains and executes the entire game logic:
+     * - Drawing the board
+     * - Evaluating wins
+     * - Updating wallet
+     * - Handling free spins
+     * - Recording events
+     *
+     * You can customize the game flow by implementing the `onHandleGameFlow` hook in the game configuration.
+     */
+    protected handleGameFlow(): void;
+}
+interface SimulationOpts {
+    debug?: boolean;
+}
+
+/**
+ * Stores win amounts for simulations.
+ */
+declare class Wallet {
+    /**
+     * Total win amount (as the bet multiplier) from all simulations.
+     */
+    protected cumulativeWins: number;
+    /**
+     * Total win amount (as the bet multiplier) per spin type.
+     *
+     * @example
+     * ```ts
+     * {
+     *   basegame: 50,
+     *   freespins: 100,
+     *   superfreespins: 200,
+     * }
+     * ```
+     */
+    protected cumulativeWinsPerSpinType: {
+        basegame: number;
+        freespins: number;
+    };
+    /**
+     * Current win amount (as the bet multiplier) for the ongoing simulation.
+     */
+    protected currentWin: number;
+    /**
+     * Current win amount (as the bet multiplier) for the ongoing simulation per spin type.
+     *
+     * @example
+     * ```ts
+     * {
+     *   basegame: 50,
+     *   freespins: 100,
+     *   superfreespins: 200,
+     * }
+     * ```
+     */
+    protected currentWinPerSpinType: {
+        basegame: number;
+        freespins: number;
+    };
+    /**
+     * Holds the current win amount for a single (free) spin.\
+     * After each spin, this amount is added to `currentWinPerSpinType` and then reset to zero.
+     */
+    protected currentSpinWin: number;
+    /**
+     * Current win amount (as the bet multiplier) for the ongoing tumble sequence.
+     */
+    protected currentTumbleWin: number;
+    constructor();
+    /**
+     * Updates the win for the current spin.
+     *
+     * Should be called after each tumble event, if applicable.\
+     * Or generally call this to add wins during a spin.
+     *
+     * After each (free) spin, this amount should be added to `currentWinPerSpinType` via `confirmSpinWin()`
+     */
+    addSpinWin(amount: number): void;
+    /**
+     * Assigns a win amount to the given spin type.
+     *
+     * Should be called after `addSpinWin()`, and after your tumble events are played out,\
+     * and after a (free) spin is played out to finalize the win.
+     */
+    confirmSpinWin(spinType: SpinType): void;
+    /**
+     * Returns the accumulated win amount (as the bet multiplier) from all simulations.
+     */
+    getCumulativeWins(): number;
+    /**
+     * Returns the accumulated win amount (as the bet multiplier) per spin type from all simulations.
+     */
+    getCumulativeWinsPerSpinType(): {
+        basegame: number;
+        freespins: number;
+    };
+    /**
+     * Returns the current win amount (as the bet multiplier) for the ongoing simulation.
+     */
+    getCurrentWin(): number;
+    /**
+     * Returns the current win amount (as the bet multiplier) per spin type for the ongoing simulation.
+     */
+    getCurrentWinPerSpinType(): {
+        basegame: number;
+        freespins: number;
+    };
+    /**
+     * Adds a win to `currentSpinWin` and `currentTumbleWin`.
+     *
+     * After each (free) spin, this amount should be added to `currentWinPerSpinType` via `confirmSpinWin()`
+     */
+    addTumbleWin(amount: number): void;
+    /**
+     * Resets the current win amounts to zero.
+     */
+    resetCurrentWin(): void;
+    /**
+     * Adds current wins to cumulative wins and resets current wins to zero.
+     */
+    confirmWins(ctx: AnySimulationContext): void;
+    serialize(): {
+        cumulativeWins: number;
+        cumulativeWinsPerSpinType: {
+            basegame: number;
+            freespins: number;
+        };
+        currentWin: number;
+        currentWinPerSpinType: {
+            basegame: number;
+            freespins: number;
+        };
+        currentSpinWin: number;
+        currentTumbleWin: number;
+    };
+    merge(wallet: Wallet): void;
+    mergeSerialized(data: ReturnType<Wallet["serialize"]>): void;
+}
+
+declare class Book {
+    id: number;
+    criteria: string;
+    protected events: BookEvent[];
+    protected payout: number;
+    protected basegameWins: number;
+    protected freespinsWins: number;
+    constructor(opts: BookOpts);
+    /**
+     * Adds an event to the book.
+     */
+    addEvent(event: Omit<BookEvent, "index">): void;
+    /**
+     * Transfers the win data from the wallet to the book.
+     */
+    writePayout(ctx: AnySimulationContext): void;
+    getPayout(): number;
+    getBasegameWins(): number;
+    getFreespinsWins(): number;
+    serialize(): {
+        id: number;
+        criteria: string;
+        events: BookEvent[];
+        payout: number;
+        basegameWins: number;
+        freespinsWins: number;
+    };
+    static fromSerialized(data: ReturnType<Book["serialize"]>): Book;
+}
+interface BookEvent {
+    index: number;
+    type: string;
+    data: Record<string, any>;
+}
+interface BookOpts {
+    id: number;
+}
+
+/**
+ * The GameState manages the current state of the game.
+ */
+declare class GameState<TGameModes extends AnyGameModes, TSymbols extends AnySymbols, TUserState extends AnyUserData> extends GameConfig<TGameModes, TSymbols, TUserState> {
+    state: {
+        currentSimulationId: number;
+        /**
+         * e.g. "base", "freespins", etc. (depending on the game config)
+         */
+        currentGameMode: string;
+        /**
+         * Spin type constant as defined in `GameConfig.SPIN_TYPE`
+         */
+        currentSpinType: SpinType;
+        /**
+         * The current ResultSet for the active simulation run.
+         */
+        currentResultSet: ResultSet<any>;
+        /**
+         * Whether the criteria in the ResultSet for the current simulation has been met.
+         */
+        isCriteriaMet: boolean;
+        /**
+         * Number of freespins remaining in the current freespin round.
+         */
+        currentFreespinAmount: number;
+        /**
+         * Total amount of freespins awarded during the active simulation.
+         */
+        totalFreespinAmount: number;
+        /**
+         * A library of all completed books, indexed by their ID.
+         */
+        library: Map<string, Book>;
+        /**
+         * The current book being recorded.
+         */
+        book: Book;
+        /**
+         * Seeded random number generator instance for the current simulation.
+         */
+        rng: RandomNumberGenerator;
+        /**
+         * Custom user data that can be used in game flow logic.
+         */
+        userData: TUserState;
+        /**
+         * Whether a max win has been triggered during the active simulation.
+         */
+        triggeredMaxWin: boolean;
+        /**
+         * Whether freespins have been triggered during the active simulation.
+         */
+        triggeredFreespins: boolean;
+    };
+    /**
+     * The wallet stores win data for the current and all simulations, respectively.
+     */
+    wallet: Wallet;
+    /**
+     * Recorder for statistical analysis (e.g. symbol occurrences, etc.).
+     */
+    private recorder;
+    constructor(opts: CommonGameOptions<TGameModes, TSymbols, TUserState>);
+    /**
+     * Gets the configuration for the current game mode.
+     */
+    getCurrentGameMode(): GameMode;
+    resetState(): void;
+    /**
+     * Checks if a max win is reached by comparing `wallet.currentWin` to `config.maxWin`.
+     *
+     * Should be called after `wallet.confirmSpinWin()`.
+     */
+    isMaxWinTriggered(): void;
+    /**
+     * Empties the list of pending records in the recorder.
+     */
+    clearPendingRecords(): void;
+    /**
+     * Confirms all pending records and adds them to the main records list.
+     */
+    confirmRecords(): void;
+    /**
+     * Record data for statistical analysis.
+     */
+    record(data: Record<string, string | number | boolean>): void;
+    /**
+     * Records a symbol occurrence for statistical analysis.
+     *
+     * Calls `this.record()` with the provided data.
+     */
+    recordSymbolOccurrence(data: {
+        kind: number;
+        symbolId: string;
+        spinType: SpinType;
+        [key: string]: any;
+    }): void;
+    /**
+     * Gets all confirmed records.
+     */
+    getRecords(): RecordItem[];
+    /**
+     * Moves the current book to the library and resets the current book.
+     */
+    moveBookToLibrary(): void;
+    /**
+     * Increases the freespin count by the specified amount.
+     *
+     * Also sets `state.triggeredFreespins` to true.
+     */
+    awardFreespins(amount: number): void;
+    /**
+     * Ensures the requested number of scatters is valid based on the game configuration.\
+     * Returns a valid number of scatters.
+     */
+    verifyScatterCount(numScatters: number): number;
+}
+interface RecordItem {
+    search: Array<{
+        name: string;
+        value: string;
+    }>;
+    timesTriggered: number;
+    bookIds: number[];
+}
+
+/**
+ * A version of the Board class that is disconnected from the actual game state\
+ * and operates on a copy of the game context.
+ *
+ * Can be used in custom game logic where you need to evaluate an additional board or reels independent of the main board,\
+ * similar to the top and bottom reels of the game "San Quentin".
+ */
+declare class StandaloneBoard {
+    protected reels: Reels;
+    protected paddingTop: Reels;
+    protected paddingBottom: Reels;
+    protected anticipation: number[];
+    protected ctx: AnySimulationContext;
+    constructor(opts: StandaloneBoardOpts);
+    /**
+     * Updates the context used by this board instance.
+     */
+    context(ctx: AnySimulationContext): void;
+    /**
+     * Resets the board to an empty state.\
+     * This is called before drawing a new board.
+     */
+    resetBoard(): void;
+    private makeEmptyReels;
+    private resetReels;
+    /**
+     * Counts how many symbols matching the criteria are on a specific reel.
+     */
+    countSymbolsOnReel(symbolOrProperties: GameSymbol | Record<string, any>, reelIndex: number): number;
+    /**
+     * Counts how many symbols matching the criteria are on the board.
+     *
+     * Passing a GameSymbol will compare by ID, passing a properties object will compare by properties.
+     *
+     * Returns a tuple where the first element is the total count, and the second element is a record of counts per reel index.
+     */
+    countSymbolsOnBoard(symbolOrProperties: GameSymbol | Record<string, any>): [number, Record<number, number>];
+    /**
+     * Checks if a symbol appears more than once on any reel in the current reel set.
+     *
+     * Useful to check for "forbidden" generations, e.g. 2 scatters on one reel.
+     */
+    isSymbolOnAnyReelMultipleTimes(symbol: GameSymbol): boolean;
+    /**
+     * Draws a board using specified reel stops.
+     */
+    drawBoardWithForcedStops(reels: Reels, forcedStops: Record<string, number>): void;
+    /**
+     * Draws a board using random reel stops.
+     */
+    drawBoardWithRandomStops(reels: Reels): void;
+    private drawBoardMixed;
+}
+interface StandaloneBoardOpts {
+    ctx: AnySimulationContext;
+}
+/**
+ * Extends GameState. Provides board-related functionality.
+ */
+declare class Board<TGameModes extends AnyGameModes, TSymbols extends AnySymbols, TUserState extends AnyUserData> extends GameState<TGameModes, TSymbols, TUserState> {
+    board: {
+        reels: Reels;
+        paddingTop: Reels;
+        paddingBottom: Reels;
+        anticipation: number[];
+    };
+    constructor(opts: CommonGameOptions<TGameModes, TSymbols, TUserState>);
+    /**
+     * Resets the board to an empty state.\
+     * This is called before drawing a new board.
+     */
+    resetBoard(): void;
+    private makeEmptyReels;
+    private resetReels;
+    /**
+     * Counts how many symbols matching the criteria are on a specific reel.
+     */
+    countSymbolsOnReel(symbolOrProperties: GameSymbol | Record<string, any>, reelIndex: number): number;
+    /**
+     * Counts how many symbols matching the criteria are on the board.
+     *
+     * Passing a GameSymbol will compare by ID, passing a properties object will compare by properties.
+     *
+     * Returns a tuple where the first element is the total count, and the second element is a record of counts per reel index.
+     */
+    countSymbolsOnBoard(symbolOrProperties: GameSymbol | Record<string, any>): [number, Record<number, number>];
+    /**
+     * Checks if a symbol appears more than once on any reel in the current reel set.
+     *
+     * Useful to check for "forbidden" generations, e.g. 2 scatters on one reel.
+     */
+    isSymbolOnAnyReelMultipleTimes(symbol: GameSymbol): boolean;
+    /**
+     * Gets all reel stops (positions) where the specified symbol appears in the current reel set.\
+     * Returns an array of arrays, where each inner array contains the positions for the corresponding reel.
+     */
+    getReelStopsForSymbol(reels: Reels, symbol: GameSymbol): number[][];
+    /**
+     * Combines multiple arrays of reel stops into a single array of reel stops.\
+     */
+    combineReelStops(...reelStops: number[][][]): number[][];
+    /**
+     * From a list of reel stops on reels, selects a random stop for a speficied number of random symbols.
+     *
+     * Mostly useful for placing scatter symbols on the board.
+     */
+    getRandomReelStops(reels: Reels, reelStops: number[][], amount: number): Record<string, number>;
+    /**
+     * Selects a random reelset based on the configured weights for the current game mode.\
+     * Returns the reels as arrays of GameSymbols.
+     */
+    getRandomReelset(): Reels;
+    /**
+     * Draws a board using specified reel stops.
+     */
+    drawBoardWithForcedStops(reels: Reels, forcedStops: Record<string, number>): void;
+    /**
+     * Draws a board using random reel stops.
+     */
+    drawBoardWithRandomStops(reels: Reels): void;
+    private drawBoardMixed;
+}
+
+declare class ResultSet<TUserState extends AnyUserData> {
+    criteria: string;
+    quota: number;
+    multiplier?: number;
+    reelWeights: ReelWeights<TUserState>;
+    userData?: Record<string, any>;
+    forceMaxWin?: boolean;
+    forceFreespins?: boolean;
+    evaluate?: (ctx: AnySimulationContext<any, any, TUserState>) => boolean;
+    constructor(opts: ResultSetOpts<TUserState>);
+    static assignCriteriaToSimulations(ctx: Simulation, gameModeName: string): Record<number, string>;
+    /**
+     * Checks if core criteria is met, e.g. target multiplier or max win.
+     */
+    meetsCriteria(ctx: AnySimulationContext<any, any, TUserState>): boolean;
+}
+interface ResultSetOpts<TUserState extends AnyUserData> {
+    /**
+     * A short string to describe the criteria for this ResultSet.
+     */
+    criteria: string;
+    /**
+     * The quota of spins, out of the total simulations, that must be forced to meet the specified criteria.\
+     * **Float from 0 to 1. Total quota of all ResultSets in a GameMode must be 1.**
+     */
+    quota: number;
+    /**
+     * The required multiplier for a simulated spin to be accepted.
+     */
+    multiplier?: number;
+    /**
+     * Configure the weights of the reels in this ResultSet.
+     *
+     * If you need to support dynamic / special reel weights based on the simulation context,\
+     * you can provide an `evaluate` function that returns the desired weights.
+     *
+     * If the `evaluate` function returns a falsy value, the usual spin type based weights will be used.
+     *
+     * @example
+     * ```ts
+     * new ResultSet({
+     *   criteria: "superFreespins",
+     *   quota: 0.05,
+     *   forceFreespins: true,
+     *   reelWeights: {
+     *     [GameConfig.SPIN_TYPE.BASE_GAME]: { base1: 1 },
+     *     [GameConfig.SPIN_TYPE.FREE_SPINS]: { bonus1: 1, bonus2: 2 },
+     *     evaluate: (ctx) => {
+     *       if (ctx.state.userData.triggeredSuperFreespins) {
+     *         return { superbonus: 1 }
+     *       }
+     *     }
+     *   },
+     *   userData: { forceSuperFreespins: true },
+     * }),
+     * ```
+     */
+    reelWeights: ReelWeights<TUserState>;
+    /**
+     * Optional data to use when evaluating the criteria.\
+     * This can be used to pass additional context or parameters needed for the evaluation.
+     */
+    userData?: Record<string, any>;
+    /**
+     * If set, this will force the game to always trigger a max win.
+     */
+    forceMaxWin?: boolean;
+    /**
+     * If set, this will force the game to always trigger free spins.
+     */
+    forceFreespins?: boolean;
+    /**
+     * Custom function to evaluate if the criteria is met.
+     *
+     * E.g. use this to check for free spins that upgraded to super free spins\
+     * or other arbitrary simulation criteria.
+     */
+    evaluate?: (ctx: EvaluationContext<TUserState>) => boolean;
+}
+interface ReelWeights<TUserState extends AnyUserData> {
+    [GameConfig.SPIN_TYPE.BASE_GAME]: Record<string, number>;
+    [GameConfig.SPIN_TYPE.FREE_SPINS]: Record<string, number>;
+    evaluate?: (ctx: EvaluationContext<TUserState>) => Record<string, number> | undefined | null | false;
+}
+type EvaluationContext<TUserState extends AnyUserData> = Board<any, any, TUserState>;
+
+/**
+ * Static configuration for a slot game.\
+ * This shouldn't change during gameplay.
+ */
+declare class GameConfig<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> {
+    readonly config: {
+        readonly id: string;
+        readonly name: string;
+        readonly providerNumber: number;
+        readonly gameModes: Record<GameModeName, GameMode>;
+        readonly symbols: Map<TSymbols[number]["id"], TSymbols[number]>;
+        readonly padSymbols?: number;
+        readonly scatterToFreespins: Record<string, Record<number, number>>;
+        readonly anticipationTriggers: Record<SpinType, number>;
+        readonly maxWinX: number;
+        readonly outputDir: string;
+        readonly hooks: GameHooks<TGameModes, TSymbols, TUserState>;
+        readonly userState?: TUserState;
+    };
+    constructor(opts: CommonGameOptions<TGameModes, TSymbols, TUserState>);
+    /**
+     * Generates reelset CSV files for all game modes.
+     */
+    generateReelsetFiles(): void;
+    /**
+     * Retrieves a reel set by its ID within a specific game mode.
+     */
+    getReelsetById(gameMode: string, id: string): ReelGenerator;
+    /**
+     * Retrieves the number of free spins awarded for a given spin type and scatter count.
+     */
+    getFreeSpinsForScatters(spinType: SpinType, scatterCount: number): number;
+    /**
+     * Retrieves a result set by its criteria within a specific game mode.
+     */
+    getGameModeCriteria(mode: string, criteria: string): ResultSet<any>;
+    /**
+     * Returns all configured symbols as an array.
+     */
+    getSymbolArray(): TSymbols[number][];
+    static SPIN_TYPE: {
+        readonly BASE_GAME: "basegame";
+        readonly FREE_SPINS: "freespins";
+    };
+}
+type SpinType = (typeof GameConfig.SPIN_TYPE)[keyof typeof GameConfig.SPIN_TYPE];
+type AnyGameConfig = GameConfig<any, any, any>;
+
+declare class WinType {
+    protected payout: number;
+    protected winCombinations: WinCombination[];
+    protected ctx: AnySimulationContext;
+    protected readonly wildSymbol?: WildSymbol;
+    constructor(opts?: WinTypeOpts);
+    /**
+     * Sets the simulation context for this WinType instance.
+     *
+     * This gives the WinType access to the current board.
+     */
+    context(ctx: AnySimulationContext): WinType;
+    protected ensureContext(): void;
+    /**
+     * Implementation of win evaluation logic. Sets `this.payout` and `this.winCombinations`.
+     */
+    evaluateWins(): this;
+    /**
+     * Custom post-processing of wins, e.g. for handling multipliers.
+     */
+    postProcess(func: PostProcessFn<typeof this.winCombinations>): this;
+    /**
+     * Returns the total payout and detailed win combinations.
+     */
+    getWins(): {
+        payout: number;
+        winCombinations: WinCombination[];
+    };
+}
+interface WinTypeOpts {
+    /**
+     * Configuration used to identify wild symbols on the board.\
+     * You can either provide a specific `GameSymbol` instance or a set of properties to match against symbols on the board.
+     *
+     * @example
+     * If you have different wild symbols, each with a property `isWild: true`, you can define:
+     * ```ts
+     * wildSymbol: { isWild: true }
+     * ```
+     *
+     * @example
+     * If you have a single wild symbol instance, you can define:
+     * ```ts
+     * wildSymbol: myWildSymbol
+     * ```
+     */
+    wildSymbol?: WildSymbol;
+}
+type WinCombination = {
+    payout: number;
+    kind: number;
+    symbols: Array<{
+        symbol: GameSymbol;
+        isWild: boolean;
+        substitutedFor?: GameSymbol;
+        reelIndex: number;
+        posIndex: number;
+    }>;
+};
+type PostProcessFn<TWinCombs extends WinCombination[]> = (winType: WinType, ctx: AnySimulationContext) => {
+    payout: number;
+    winCombinations: TWinCombs;
+};
+type WildSymbol = GameSymbol | Record<string, any>;
+
+declare class LinesWinType extends WinType {
+    protected lines: Record<number, number[]>;
+    protected winCombinations: LineWinCombination[];
+    context: (ctx: AnySimulationContext) => LinesWinType;
+    getWins: () => {
+        payout: number;
+        winCombinations: LineWinCombination[];
+    };
+    constructor(opts: LinesWinTypeOpts);
+    private validateConfig;
+    private isWild;
+    evaluateWins(): this;
+}
+interface LinesWinTypeOpts extends WinTypeOpts {
+    /**
+     * Defines the paylines for the slot game.
+     *
+     * @example
+     * ```ts
+     * lines: {
+     *   1: [0, 0, 0, 0, 0],
+     *   2: [1, 1, 1, 1, 1],
+     *   3: [2, 2, 2, 2, 2],
+     * }
+     * ```
+     */
+    lines: Record<number, number[]>;
+}
+interface LineWinCombination extends WinCombination {
+    lineNumber: number;
+    symbol: GameSymbol;
+    winType: "pure-wild" | "substituted";
+    substitutedBaseSymbol: GameSymbol | null;
+    stats: {
+        wildCount: number;
+        nonWildCount: number;
+        leadingWilds: number;
+    };
+}
+
+declare class ClusterWinType extends WinType {
+}
+
+declare class ManywaysWinType extends WinType {
+}
+
+declare class OptimizationConditions {
+    protected rtp?: number | "x";
+    protected avgWin?: number;
+    protected hitRate?: number | "x";
+    protected searchRange: number[];
+    protected forceSearch: Record<string, string>;
+    priority: number;
+    constructor(opts: OptimizationConditionsOpts);
+    getRtp(): number | "x" | undefined;
+    getAvgWin(): number | undefined;
+    getHitRate(): number | "x" | undefined;
+    getSearchRange(): number[];
+    getForceSearch(): Record<string, string>;
+}
+interface OptimizationConditionsOpts {
+    /**
+     * The desired RTP (0-1)
+     */
+    rtp?: number | "x";
+    /**
+     * The desired average win (per spin).
+     */
+    avgWin?: number;
+    /**
+     * The desired hit rate (e.g. `200` to hit 1 in 200 spins).
+     */
+    hitRate?: number | "x";
+    /**
+     * A way of filtering results by
+     *
+     * - A number (payout multiplier), e.g. `5000`
+     * - Force record value, e.g. `{ "symbolId": "scatter" }`
+     * - A range of numbers, e.g. `[0, 100]` (payout multiplier range)
+     */
+    searchConditions?: number | Record<string, string> | [number, number];
+    /**
+     * **Priority matters!**\
+     * Higher priority conditions will be evaluated first.\
+     * After a book matching this condition is found, the book will be removed from the pool\
+     * and can't be used to satisfy other conditions with lower priority.
+     *
+     * TODO add better explanation
+     */
+    priority: number;
+}
+
+declare class OptimizationScaling {
+    protected config: OptimizationScalingOpts;
+    constructor(opts: OptimizationScalingOpts);
+    getConfig(): OptimizationScalingOpts;
+}
+type OptimizationScalingOpts = Array<{
+    criteria: string;
+    scaleFactor: number;
+    winRange: [number, number];
+    probability: number;
+}>;
+
+declare class OptimizationParameters {
+    protected parameters: OptimizationParametersOpts;
+    constructor(opts?: OptimizationParametersOpts);
+    static DEFAULT_PARAMETERS: OptimizationParametersOpts;
+    getParameters(): OptimizationParametersOpts;
+}
+interface OptimizationParametersOpts {
+    readonly numShowPigs: number;
+    readonly numPigsPerFence: number;
+    readonly threadsFenceConstruction: number;
+    readonly threadsShowConstruction: number;
+    readonly testSpins: number[];
+    readonly testSpinsWeights: number[];
+    readonly simulationTrials: number;
+    readonly graphIndexes: number[];
+    readonly run1000Batch: false;
+    readonly minMeanToMedian: number;
+    readonly maxMeanToMedian: number;
+    readonly pmbRtp: number;
+    readonly scoreType: "rtp";
+}
+
+interface OptimizationOpts {
+    gameModes: string[];
+}
+interface OptimizerOpts {
+    game: SlotGame<any, any, any>;
+    gameModes: OptimzierGameModeConfig;
+}
+type OptimzierGameModeConfig = Record<GameModeName, {
+    conditions: Record<string, OptimizationConditions>;
+    scaling: OptimizationScaling;
+    parameters: OptimizationParameters;
+}>;
+
+interface AnalysisOpts {
+    gameModes: string[];
+}
+
+/**
+ * SlotGame class that encapsulates the game configuration and state.\
+ * Main entry point for the slot game.
+ */
+declare class SlotGame<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> {
+    private readonly gameConfigOpts;
+    private simulation?;
+    private optimizer?;
+    private analyzer?;
+    constructor(config: CommonGameOptions<TGameModes, TSymbols, TUserState>);
+    /**
+     * Sets up the simulation configuration.\
+     * Must be called before `runTasks()`.
+     */
+    configureSimulation(opts: SimulationConfigOpts): void;
+    /**
+     * Sets up the optimization configuration.\
+     * Must be called before `runTasks()`.
+     */
+    configureOptimization(opts: Pick<OptimizerOpts, "gameModes">): void;
+    /**
+     * Runs the simulation based on the configured settings.
+     */
+    private runSimulation;
+    /**
+     * Runs the optimization based on the configured settings.
+     */
+    private runOptimization;
+    /**
+     * Runs the analysis based on the configured settings.
+     */
+    private runAnalysis;
+    runTasks(opts?: {
+        debug?: boolean;
+        doSimulation?: boolean;
+        doOptimization?: boolean;
+        doAnalysis?: boolean;
+        simulationOpts?: SimulationOpts;
+        optimizationOpts?: OptimizationOpts;
+        analysisOpts?: AnalysisOpts;
+    }): Promise<void>;
+    /**
+     * Gets the game configuration.
+     */
+    getConfig(): GameConfig<TGameModes, TSymbols, TUserState>;
+}
+
+/**
+ * @internal
+ */
+interface CommonGameOptions<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> {
+    /**
+     * The unique identifier of the game, used for configuration and identification.
+     */
+    id: string;
+    /**
+     * The name of the game, used for display purposes.
+     */
+    name: string;
+    /**
+     * An arbitrary number to identify the provider of this game.
+     */
+    providerNumber: number;
+    /**
+     * A GameMode is the core structure of a slot, defining the board,\
+     * bet cost, win type, and other properties.
+     *
+     * One-off mechanisms can also be injected into the core game logic from here.
+     */
+    gameModes: Record<GameModeName, GameMode>;
+    /**
+     * A list of all symbols that will appear on the reels.
+     */
+    symbols: GameSymbol[];
+    /**
+     * A mapping from spin type to scatter counts to the number of free spins awarded.
+     *
+     * @example
+     * ```ts
+     * scatterToFreespins: {
+     *   [GameConfig.CONSTANTS.BASE_GAME]: {
+     *     3: 10,
+     *     4: 12,
+     *     5: 15,
+     *   },
+     *   [GameConfig.CONSTANTS.FREE_SPINS]: {
+     *     3: 6,
+     *     4: 8,
+     *     5: 10,
+     *   },
+     * },
+     * ```
+     */
+    scatterToFreespins: Record<string, Record<number, number>>;
+    /**
+     * If set, this will pad the board with symbols on the top and bottom of the reels.\
+     * Useful for teasing symbols right above or below the active board.
+     *
+     * Default: 1
+     */
+    padSymbols?: number;
+    /**
+     * The maximum win multiplier of the game, e.g. 5000 for a 5000x max win.
+     */
+    maxWinX: number;
+    /**
+     * Hooks are used to inject custom logic at specific points in the game flow.\
+     * Some required hooks must be implemented for certain features to work.
+     */
+    hooks: GameHooks<TGameModes, TSymbols, TUserState>;
+    /**
+     * Custom additional state that can be used in game flow logic.
+     */
+    userState?: TUserState;
+}
+/**
+ * @internal
+ */
+type AnyUserData = Record<string, any>;
+/**
+ * @internal
+ */
+type AnyGameModes = Record<string, GameMode>;
+/**
+ * @internal
+ */
+type AnySymbols = GameSymbol[];
+/**
+ * @internal
+ */
+interface GameHooks<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> {
+    /**
+     * This hook is called after the simulation state is prepared for a spin,\
+     * and the core is ready to handle the game flow.
+     *
+     * **The developer is responsible for implementing the entire game flow here, including:**
+     * - Drawing the board
+     * - Evaluating wins
+     * - Tumbling mechanics
+     * - Updating wallet
+     * - Handling free spins
+     * - Recording events
+     * - ... and everything in between.
+     *
+     * You can access the config and state from the context.
+     *
+     * The game flow is not built into the core, because it can vary greatly between different games.\
+     * This hook provides the flexibility to implement any game flow you need.
+     */
+    onHandleGameFlow: (ctx: SimulationContext<TGameModes, TSymbols, TUserState>) => void;
+    /**
+     * This hook is called whenever a simulation is accepted, i.e. when the criteria of the current ResultSet is met.
+     */
+    onSimulationAccepted?: (ctx: SimulationContext<TGameModes, TSymbols, TUserState>) => void;
+}
+type InferUserState<T> = T extends SlotGame<infer U> ? U : never;
+type HookContext<T> = T extends SlotGame<infer G, infer S, infer U> ? SimulationContext<G, S, U> : never;
+
+type InferGameType<TGameModes extends AnyGameModes, TSymbols extends AnySymbols, TUserState extends AnyUserData> = SlotGame<TGameModes, TSymbols, TUserState>;
+interface CreateSlotGameOpts<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> {
+    id: CommonGameOptions["id"];
+    name: CommonGameOptions["name"];
+    providerNumber: CommonGameOptions["providerNumber"];
+    gameModes: TGameModes;
+    symbols: TSymbols;
+    scatterToFreespins: CommonGameOptions["scatterToFreespins"];
+    padSymbols?: CommonGameOptions["padSymbols"];
+    maxWinX: CommonGameOptions["maxWinX"];
+    userState?: TUserState;
+    hooks: CommonGameOptions<TGameModes, TSymbols, TUserState>["hooks"];
+}
+declare function createSlotGame<TGame>(opts: TGame extends InferGameType<infer G, infer S, infer U> ? CreateSlotGameOpts<G, S, U> : never): TGame;
+declare const defineUserState: <TUserState extends AnyUserData>(data: TUserState) => TUserState;
+declare const defineSymbols: <TSymbol extends GameSymbol>(symbols: TSymbol[]) => TSymbol[];
+declare const defineGameModes: <TGameModes extends AnyGameModes>(gameModes: TGameModes) => TGameModes;
+declare const defineReelSets: <TSymbols extends AnySymbols>(reelSets: ReelGenerator[]) => ReelGenerator[];
+
+export { type AnyGameModes, type AnySymbols, type AnyUserData, ClusterWinType, type CommonGameOptions, type CreateSlotGameOpts, type EvaluationContext, GameConfig, type GameHooks, GameMode, GameSymbol, type HookContext, type InferGameType, type InferUserState, LinesWinType, ManywaysWinType, OptimizationConditions, OptimizationParameters, OptimizationScaling, ReelGenerator, type Reels, ResultSet, StandaloneBoard, WinType, createSlotGame, defineGameModes, defineReelSets, defineSymbols, defineUserState, weightedRandom };