@slot-engine/core 0.0.4 → 0.0.6

package/dist/index.d.mts

@@ -1,520 +1,473 @@
-declare class GameSymbol {
+declare const SPIN_TYPE: {
+    readonly BASE_GAME: "basegame";
+    readonly FREE_SPINS: "freespins";
+};
+
+interface GameConfigOptions<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;
-    pays?: Record<number, number>;
-    properties: Map<string, any>;
-    constructor(opts: GameSymbolOpts);
     /**
-     * Compares this symbol to another symbol or a set of properties.
+     * The name of the game, used for display purposes.
      */
-    compare(symbolOrProperties?: GameSymbol | Record<string, any>): boolean;
-}
-interface GameSymbolOpts {
+    name: string;
     /**
-     * Unique identifier for the symbol, e.g. "W", "H1", "L5", etc.
+     * A GameMode is the core structure of a slot, defining the board,\
+     * bet cost, win type, and other properties.
      */
-    id: string;
+    gameModes: TGameModes;
     /**
-     * Paytable for the symbol, where the key is the number of symbols and the value is the payout multiplier.
+     * A list of all symbols that will appear on the reels.
      */
-    pays?: Record<number, number>;
+    symbols: TSymbols;
     /**
-     * Additional properties for the symbol, e.g. `multiplier` or `isWild`.
-     *
-     * Properties can help identify special symbols.
+     * A mapping from spin type to scatter counts to the number of free spins awarded.
      *
      * @example
-     * If your game has a "normal" scatter and a "super" scatter, you can define them like this:
-     *
      * ```ts
-     * properties: {
-     *   isScatter: true,
-     * }
+     * scatterToFreespins: {
+     *   [SPIN_TYPE.BASE_GAME]: {
+     *     3: 10,
+     *     4: 12,
+     *     5: 15,
+     *   },
+     *   [SPIN_TYPE.FREE_SPINS]: {
+     *     3: 6,
+     *     4: 8,
+     *     5: 10,
+     *   },
+     * },
      * ```
      */
-    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;
+    scatterToFreespins: Record<string, Record<number, number>>;
     /**
-     * Checks if a symbol can be placed at the target index without violating spacing rules.
+     * 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
      */
-    private violatesSpacing;
-    generateReels(gameConf: AnyGameConfig): void;
+    padSymbols?: number;
     /**
-     * Reads a reelset CSV file and returns the reels as arrays of GameSymbols.
+     * The maximum win multiplier of the game, e.g. 5000 for a 5000x max win.
+     */
+    maxWinX: number;
+    /**
+     * Custom additional state that can be used in game flow logic.
+     */
+    userState?: TUserState;
+    /**
+     * 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.
      */
-    parseReelsetCSV(reelSetPath: string, { config }: GameConfig): Reels;
+    hooks: GameHooks<TGameModes, TSymbols, TUserState>;
 }
-interface ReelGeneratorOpts {
+type GameConfig<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> = Required<Omit<GameConfigOptions<TGameModes, TSymbols, TUserState>, "symbols">> & {
     /**
-     * The unique identifier of the reel generator.\
-     * Must be unique per game mode.
+     * A map of all symbols.
      */
-    id: string;
+    symbols: Map<keyof TSymbols & string, TSymbols[keyof TSymbols]>;
+    outputDir: string;
     /**
-     * The weights of the symbols in the reelset.\
-     * This is a mapping of symbol IDs to their respective weights.
+     * A mapping of spin types to the number of scatter symbols required to trigger anticipation.
      */
-    symbolWeights: Record<string, number>;
+    anticipationTriggers: Record<(typeof SPIN_TYPE)[keyof typeof SPIN_TYPE], number>;
+};
+
+declare class Simulation {
+    readonly gameConfigOpts: GameConfigOptions;
+    readonly gameConfig: GameConfig;
+    readonly simRunsAmount: Partial<Record<string, number>>;
+    readonly concurrency: number;
+    private debug;
+    private actualSims;
+    private library;
+    private recorder;
+    private wallet;
+    constructor(opts: SimulationOptions, gameConfigOpts: GameConfigOptions);
+    runSimulation(opts: SimulationConfigOptions): Promise<void>;
     /**
-     * The number of rows in the reelset.\
-     * Default is 250, but can be adjusted as needed.
+     * Runs all simulations for a specific game mode.
      */
-    rowsAmount?: number;
+    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>;
     /**
-     * The directory where the generated reelset files will be saved.\
-     * **It's recommended to just use `__dirname`**!
+     * Will run a single simulation until the specified criteria is met.
      */
-    outputDir: string;
+    runSingleSimulation(opts: {
+        simId: number;
+        mode: string;
+        criteria: string;
+        index: number;
+    }): void;
     /**
-     * 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.
+     * If a simulation does not meet the required criteria, reset the state to run it again.
      *
-     * **This is overridden by `symbolStacks`**
+     * This also runs once before each simulation to ensure a clean state.
      */
-    spaceBetweenSameSymbols?: number | Record<string, number>;
+    protected resetSimulation(ctx: GameContext): void;
+    protected resetState(ctx: GameContext): void;
     /**
-     * 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.
+     * Contains and executes the entire game logic:
+     * - Drawing the board
+     * - Evaluating wins
+     * - Updating wallet
+     * - Handling free spins
+     * - Recording events
      *
-     * **This is overridden by `symbolStacks`**
+     * You can customize the game flow by implementing the `onHandleGameFlow` hook in the game configuration.
      */
-    spaceBetweenSymbols?: Record<string, Record<string, number>>;
+    protected handleGameFlow(ctx: GameContext): void;
     /**
-     * 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.
+     * Creates a CSV file in the format "simulationId,weight,payout".
      *
-     * **This is overridden by `symbolStacks`**
+     * `weight` defaults to 1.
      */
-    preferStackedSymbols?: number;
+    private writeLookupTableCSV;
     /**
-     * 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
-     *   }
-     * }
-     * ```
+     * Creates a CSV file in the format "simulationId,criteria,payoutBase,payoutFreespins".
      */
-    symbolStacks?: Record<string, {
-        chance: number | Record<string, number>;
-        min?: number | Record<string, number>;
-        max?: number | Record<string, number>;
-    }>;
+    private writeLookupTableSegmentedCSV;
+    private writeRecords;
+    private writeIndexJson;
+    private writeBooksJson;
+    private logSymbolOccurrences;
     /**
-     * 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.
-     * }
-     * ```
+     * Compiles user configured game to JS for use in different Node processes
      */
-    limitSymbolsToReels?: Record<string, number[]>;
+    private preprocessFiles;
+    private getSimRangesForChunks;
+    private mergeRecords;
     /**
-     * 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
-     * }
-     * ```
+     * Generates reelset CSV files for all game modes.
      */
-    symbolQuotas?: Record<string, number | Record<string, number>>;
+    private generateReelsetFiles;
     /**
-     * If true, existing reels CSV files will be overwritten.
+     * Confirms all pending records and adds them to the main records list.
      */
-    overrideExisting?: boolean;
+    confirmRecords(ctx: GameContext): void;
+}
+type SimulationOptions = {
     /**
-     * Optional seed for the RNG to ensure reproducible results.
-     *
-     * Default seed is `0`.
+     * Object containing the game modes and their respective simulation runs amount.
+     */
+    simRunsAmount: Partial<Record<string, number>>;
+    /**
+     * Number of concurrent processes to use for simulations.
      *
-     * Note: Seeds 0 and 1 produce the same results.
+     * Default: 6
      */
-    seed?: number;
-}
-type Reels = GameSymbol[][];
+    concurrency?: number;
+};
+type SimulationConfigOptions = {
+    debug?: boolean;
+};
 
-declare class GameMode {
-    name: GameModeName;
-    reelsAmount: number;
-    symbolsPerReel: number[];
-    cost: number;
-    rtp: number;
-    reelSets: ReelGenerator[];
-    resultSets: ResultSet<any>[];
-    isBonusBuy: boolean;
-    constructor(opts: GameModeOpts);
+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: GameContext<AnyGameModes, AnySymbols, 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: GameContext): boolean;
 }
-interface GameModeOpts {
+interface ResultSetOpts<TUserState extends AnyUserData> {
     /**
-     * Name of the game mode.
+     * A short string to describe the criteria for this ResultSet.
      */
-    name: GameModeName;
+    criteria: string;
     /**
-     * Number of reels the board has.
+     * 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.**
      */
-    reelsAmount: number;
+    quota: 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.
+     * The required multiplier for a simulated spin to be accepted.
      */
-    symbolsPerReel: number[];
+    multiplier?: number;
     /**
-     * Cost of the game mode, multiplied by the base bet.
+     * 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: {
+     *     [SPIN_TYPE.BASE_GAME]: { base1: 1 },
+     *     [SPIN_TYPE.FREE_SPINS]: { bonus1: 1, bonus2: 2 },
+     *     evaluate: (ctx) => {
+     *       if (ctx.state.userData.triggeredSuperFreespins) {
+     *         return { superbonus: 1 }
+     *       }
+     *     }
+     *   },
+     *   userData: { forceSuperFreespins: true },
+     * }),
+     * ```
      */
-    cost: number;
+    reelWeights: ReelWeights<TUserState>;
     /**
-     * The target RTP of the game.
+     * Optional data to use when evaluating the criteria.\
+     * This can be used to pass additional context or parameters needed for the evaluation.
      */
-    rtp: number;
+    userData?: Record<string, any>;
     /**
-     * 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.
+     * If set, this will force the game to always trigger a max win.
      */
-    reelSets: ReelGenerator[];
+    forceMaxWin?: boolean;
     /**
-     * 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.
+     * If set, this will force the game to always trigger free spins.
      */
-    resultSets: ResultSet<any>[];
+    forceFreespins?: boolean;
     /**
-     * Whether this game mode is a bonus buy.
+     * 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.
      */
-    isBonusBuy: boolean;
+    evaluate?: (ctx: GameContext<AnyGameModes, AnySymbols, TUserState>) => boolean;
+}
+interface ReelWeights<TUserState extends AnyUserData> {
+    [SPIN_TYPE.BASE_GAME]: Record<string, number>;
+    [SPIN_TYPE.FREE_SPINS]: Record<string, number>;
+    evaluate?: (ctx: GameContext<AnyGameModes, AnySymbols, TUserState>) => Record<string, number> | undefined | null | false;
 }
-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>;
+interface GameStateOptions<TUserState extends AnyUserData> {
+    currentSimulationId: number;
     /**
-     * Runs all simulations for a specific game mode.
+     * e.g. "base", "freespins", etc. (depending on the game config)
      */
-    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>;
+    currentGameMode: string;
     /**
-     * Creates a CSV file in the format "simulationId,weight,payout".
-     *
-     * `weight` defaults to 1.
+     * Spin type constant as defined in `SPIN_TYPE`
      */
-    private static writeLookupTableCSV;
+    currentSpinType: SpinType;
     /**
-     * Creates a CSV file in the format "simulationId,criteria,payoutBase,payoutFreespins".
+     * The current ResultSet for the active simulation run.
      */
-    private static writeLookupTableSegmentedCSV;
-    private static writeRecords;
-    private static writeIndexJson;
-    private static writeBooksJson;
-    private static logSymbolOccurrences;
+    currentResultSet: ResultSet<any>;
     /**
-     * Compiles user configured game to JS for use in different Node processes
+     * Whether the criteria in the ResultSet for the current simulation has been met.
      */
-    private preprocessFiles;
-    private getSimRangesForChunks;
-    private mergeRecords;
-}
-type SimulationConfigOpts = {
+    isCriteriaMet: boolean;
     /**
-     * Object containing the game modes and their respective simulation runs amount.
+     * Number of freespins remaining in the current freespin round.
      */
-    simRunsAmount: Partial<Record<GameModeName, number>>;
+    currentFreespinAmount: number;
     /**
-     * Number of concurrent processes to use for simulations.
-     *
-     * Default: 6
+     * Total amount of freespins awarded during the active simulation.
      */
-    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;
+    totalFreespinAmount: number;
     /**
-     * Will run a single simulation until the specified criteria is met.
+     * Custom user data that can be used in game flow logic.
      */
-    runSingleSimulation(opts: {
-        simId: number;
-        mode: string;
-        criteria: string;
-        index: number;
-    }): void;
+    userData: TUserState;
     /**
-     * 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.
+     * Whether a max win has been triggered during the active simulation.
      */
-    protected resetSimulation(): void;
+    triggeredMaxWin: boolean;
     /**
-     * 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.
+     * Whether freespins have been triggered during the active simulation.
      */
-    protected handleGameFlow(): void;
+    triggeredFreespins: boolean;
 }
-interface SimulationOpts {
-    debug?: boolean;
+declare function createGameState<TUserState extends AnyUserData = AnyUserData>(opts?: Partial<GameStateOptions<TUserState>>): {
+    currentSimulationId: number;
+    currentGameMode: string;
+    currentSpinType: SpinType;
+    currentResultSet: ResultSet<any>;
+    isCriteriaMet: boolean;
+    currentFreespinAmount: number;
+    totalFreespinAmount: number;
+    userData: TUserState;
+    triggeredMaxWin: boolean;
+    triggeredFreespins: boolean;
+};
+type GameState<TUserState extends AnyUserData = AnyUserData> = ReturnType<typeof createGameState<TUserState>>;
+
+declare class AbstractService {
+    /**
+     * Function that returns the current game context.
+     */
+    protected ctx: () => GameContext;
+    constructor(ctx: () => GameContext);
 }
 
-/**
- * Stores win amounts for simulations.
- */
-declare class Wallet {
+declare class GameSymbol {
+    readonly id: string;
+    readonly pays?: Record<number, number>;
+    readonly properties: Map<string, any>;
+    constructor(opts: GameSymbolOpts);
     /**
-     * Total win amount (as the bet multiplier) from all simulations.
+     * Compares this symbol to another symbol or a set of properties.
      */
-    protected cumulativeWins: number;
+    compare(symbolOrProperties?: GameSymbol | Record<string, any>): boolean;
+}
+interface GameSymbolOpts {
     /**
-     * Total win amount (as the bet multiplier) per spin type.
-     *
-     * @example
-     * ```ts
-     * {
-     *   basegame: 50,
-     *   freespins: 100,
-     *   superfreespins: 200,
-     * }
-     * ```
+     * Unique identifier for the symbol, e.g. "W", "H1", "L5", etc.
      */
-    protected cumulativeWinsPerSpinType: {
-        basegame: number;
-        freespins: number;
-    };
+    id: string;
     /**
-     * Current win amount (as the bet multiplier) for the ongoing simulation.
+     * Paytable for the symbol, where the key is the number of symbols and the value is the payout multiplier.
      */
-    protected currentWin: number;
+    pays?: Record<number, number>;
     /**
-     * Current win amount (as the bet multiplier) for the ongoing simulation per spin type.
+     * 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
-     * {
-     *   basegame: 50,
-     *   freespins: 100,
-     *   superfreespins: 200,
+     * properties: {
+     *   isScatter: true,
      * }
      * ```
      */
-    protected currentWinPerSpinType: {
-        basegame: number;
-        freespins: number;
-    };
+    properties?: Record<string, any>;
+}
+
+declare class BoardService<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> extends AbstractService {
+    private board;
+    constructor(ctx: () => GameContext<TGameModes, TSymbols, TUserState>);
     /**
-     * Holds the current win amount for a single (free) spin.\
-     * After each spin, this amount is added to `currentWinPerSpinType` and then reset to zero.
+     * Resets the board to an empty state.\
+     * This is called before drawing a new board.
      */
-    protected currentSpinWin: number;
+    resetBoard(): void;
     /**
-     * Current win amount (as the bet multiplier) for the ongoing tumble sequence.
+     * Gets the current reels and symbols on the board.
      */
-    protected currentTumbleWin: number;
-    constructor();
+    getBoardReels(): Reels;
+    getPaddingTop(): Reels;
+    getPaddingBottom(): Reels;
+    getAnticipation(): boolean[];
+    private resetReels;
     /**
-     * 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()`
+     * Sets the anticipation value for a specific reel.
      */
-    addSpinWin(amount: number): void;
+    setAnticipationForReel(reelIndex: number, value: boolean): 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.
+     * Counts how many symbols matching the criteria are on a specific reel.
      */
-    confirmSpinWin(spinType: SpinType): void;
+    countSymbolsOnReel(symbolOrProperties: GameSymbol | Record<string, any>, reelIndex: number): number;
     /**
-     * Returns the accumulated win amount (as the bet multiplier) from all simulations.
+     * 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.
      */
-    getCumulativeWins(): number;
+    countSymbolsOnBoard(symbolOrProperties: GameSymbol | Record<string, any>): [number, Record<number, number>];
     /**
-     * Returns the accumulated win amount (as the bet multiplier) per spin type from all simulations.
+     * 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.
      */
-    getCumulativeWinsPerSpinType(): {
-        basegame: number;
-        freespins: number;
-    };
+    isSymbolOnAnyReelMultipleTimes(symbol: GameSymbol): boolean;
     /**
-     * Returns the current win amount (as the bet multiplier) for the ongoing simulation.
+     * 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.
      */
-    getCurrentWin(): number;
+    getReelStopsForSymbol(reels: Reels, symbol: GameSymbol): number[][];
     /**
-     * Returns the current win amount (as the bet multiplier) per spin type for the ongoing simulation.
+     * Combines multiple arrays of reel stops into a single array of reel stops.\
      */
-    getCurrentWinPerSpinType(): {
-        basegame: number;
-        freespins: number;
-    };
+    combineReelStops(...reelStops: number[][][]): number[][];
     /**
-     * Adds a win to `currentSpinWin` and `currentTumbleWin`.
+     * From a list of reel stops on reels, selects a random stop for a speficied number of random symbols.
      *
-     * After each (free) spin, this amount should be added to `currentWinPerSpinType` via `confirmSpinWin()`
+     * Mostly useful for placing scatter symbols on the board.
      */
-    addTumbleWin(amount: number): void;
+    getRandomReelStops(reels: Reels, reelStops: number[][], amount: number): Record<number, number>;
     /**
-     * Resets the current win amounts to zero.
+     * Selects a random reel set based on the configured weights of the current result set.\
+     * Returns the reels as arrays of GameSymbols.
      */
-    resetCurrentWin(): void;
+    getRandomReelset(): Reels;
     /**
-     * Adds current wins to cumulative wins and resets current wins to zero.
+     * Draws a board using specified reel stops.
      */
-    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;
+    drawBoardWithForcedStops(reels: Reels, forcedStops: Record<string, number>): void;
+    /**
+     * Draws a board using random reel stops.
+     */
+    drawBoardWithRandomStops(reels: Reels): void;
+    private drawBoardMixed;
+    /**
+     * Tumbles the board. All given symbols will be deleted and new symbols will fall from the top.
+     */
+    tumbleBoard(symbolsToDelete: Array<{
+        reelIdx: number;
+        rowIdx: number;
+    }>): void;
+}
+
+declare class Recorder {
+    records: RecordItem[];
+    pendingRecords: PendingRecord[];
+    constructor();
+}
+interface PendingRecord {
+    bookId: number;
+    properties: Record<string, string>;
+}
+interface RecordItem {
+    search: Array<{
+        name: string;
+        value: string;
+    }>;
+    timesTriggered: number;
+    bookIds: number[];
 }
 
 declare class Book {
-    id: number;
+    readonly id: number;
     criteria: string;
-    protected events: BookEvent[];
-    protected payout: number;
-    protected basegameWins: number;
-    protected freespinsWins: number;
+    events: BookEvent[];
+    payout: number;
+    basegameWins: number;
+    freespinsWins: number;
     constructor(opts: BookOpts);
+    /**
+     * Intended for internal use only.
+     */
+    setCriteria(criteria: string): void;
     /**
      * Adds an event to the book.
      */
     addEvent(event: Omit<BookEvent, "index">): void;
     /**
-     * Transfers the win data from the wallet to the book.
+     * Intended for internal use only.
      */
-    writePayout(ctx: AnySimulationContext): void;
-    getPayout(): number;
-    getBasegameWins(): number;
-    getFreespinsWins(): number;
     serialize(): {
         id: number;
         criteria: string;
@@ -523,6 +476,9 @@ declare class Book {
         basegameWins: number;
         freespinsWins: number;
     };
+    /**
+     * Intended for internal use only.
+     */
     static fromSerialized(data: ReturnType<Book["serialize"]>): Book;
 }
 interface BookEvent {
@@ -532,85 +488,35 @@ interface BookEvent {
 }
 interface BookOpts {
     id: number;
+    criteria: string;
 }
 
-/**
- * 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;
-    };
+declare class DataService<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> extends AbstractService {
+    private recorder;
+    private book;
+    constructor(ctx: () => GameContext<TGameModes, TSymbols, TUserState>);
+    private ensureRecorder;
+    private ensureBook;
     /**
-     * The wallet stores win data for the current and all simulations, respectively.
+     * Intended for internal use only.
      */
-    wallet: Wallet;
+    _setRecorder(recorder: Recorder): void;
     /**
-     * Recorder for statistical analysis (e.g. symbol occurrences, etc.).
+     * Intended for internal use only.
      */
-    private recorder;
-    constructor(opts: CommonGameOptions<TGameModes, TSymbols, TUserState>);
+    _getBook(): Book;
     /**
-     * Gets the configuration for the current game mode.
+     * Intended for internal use only.
      */
-    getCurrentGameMode(): GameMode;
-    resetState(): void;
+    _setBook(book: Book): void;
     /**
-     * Empties the list of pending records in the recorder.
+     * Intended for internal use only.
      */
-    clearPendingRecords(): void;
+    _getRecorder(): Recorder;
     /**
-     * Confirms all pending records and adds them to the main records list.
+     * Intended for internal use only.
      */
-    confirmRecords(): void;
+    _getRecords(): RecordItem[];
     /**
      * Record data for statistical analysis.
      */
@@ -618,7 +524,7 @@ declare class GameState<TGameModes extends AnyGameModes, TSymbols extends AnySym
     /**
      * Records a symbol occurrence for statistical analysis.
      *
-     * Calls `this.record()` with the provided data.
+     * Calls `ctx.services.data.record()` with the provided data.
      */
     recordSymbolOccurrence(data: {
         kind: number;
@@ -627,458 +533,411 @@ declare class GameState<TGameModes extends AnyGameModes, TSymbols extends AnySym
         [key: string]: any;
     }): void;
     /**
-     * Gets all confirmed records.
+     * Adds an event to the book.
      */
-    getRecords(): RecordItem[];
+    addBookEvent(event: Omit<BookEvent, "index">): void;
     /**
-     * Moves the current book to the library and resets the current book.
+     * Intended for internal use only.
      */
-    moveBookToLibrary(): void;
+    _clearPendingRecords(): void;
+}
+
+declare class RngService<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> extends AbstractService {
+    protected rng: RandomNumberGenerator;
+    constructor(ctx: () => GameContext<TGameModes, TSymbols, TUserState>);
     /**
-     * Increases the freespin count by the specified amount.
-     *
-     * Also sets `state.triggeredFreespins` to true.
+     * Random weighted selection from a set of items.
      */
-    awardFreespins(amount: number): void;
+    weightedRandom: <T extends Record<string, number>>(weights: T) => string;
     /**
-     * Ensures the requested number of scatters is valid based on the game configuration.\
-     * Returns a valid number of scatters.
+     * Selects a random item from an array.
      */
-    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);
+    randomItem: <T>(array: T[]) => NonNullable<T>;
     /**
-     * Updates the context used by this board instance.
+     * Shuffles an array.
      */
-    context(ctx: AnySimulationContext): void;
+    shuffle: <T>(array: T[]) => T[];
     /**
-     * Resets the board to an empty state.\
-     * This is called before drawing a new board.
+     * Generates a random float between two values.
      */
-    resetBoard(): void;
-    private makeEmptyReels;
-    private resetReels;
+    randomFloat: (low: number, high: number) => number;
     /**
-     * Counts how many symbols matching the criteria are on a specific reel.
+     * Sets the seed for the RNG.
      */
-    countSymbolsOnReel(symbolOrProperties: GameSymbol | Record<string, any>, reelIndex: number): number;
+    setSeedIfDifferent: (seed: number) => void;
+}
+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;
+    weightedRandom<T extends Record<string, number>>(weights: T): string;
+    randomItem<T>(array: T[]): NonNullable<T>;
+    shuffle<T>(array: T[]): T[];
+}
+
+declare class ReelSet {
+    id: string;
+    associatedGameModeName: string;
+    reels: Reels;
+    protected rng: RandomNumberGenerator;
+    constructor(opts: ReelSetOptions);
+    generateReels(simulation: Simulation): void;
     /**
-     * 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.
+     * Reads a reelset CSV file and returns the reels as arrays of GameSymbols.
      */
-    countSymbolsOnBoard(symbolOrProperties: GameSymbol | Record<string, any>): [number, Record<number, number>];
+    parseReelsetCSV(reelSetPath: string, config: GameConfig): Reels;
+}
+interface ReelSetOptions {
     /**
-     * Checks if a symbol appears more than once on any reel in the current reel set.
+     * The unique identifier of the reel generator.\
+     * Must be unique per game mode.
+     */
+    id: string;
+    /**
+     * Optional seed for the RNG to ensure reproducible results.
      *
-     * Useful to check for "forbidden" generations, e.g. 2 scatters on one reel.
+     * Default seed is `0`.
+     *
+     * Note: Seeds 0 and 1 produce the same results.
      */
-    isSymbolOnAnyReelMultipleTimes(symbol: GameSymbol): boolean;
+    seed?: number;
+}
+
+declare class GameMode {
+    readonly name: string;
+    readonly reelsAmount: number;
+    readonly symbolsPerReel: number[];
+    readonly cost: number;
+    readonly rtp: number;
+    readonly reelSets: ReelSet[];
+    readonly resultSets: ResultSet<any>[];
+    readonly isBonusBuy: boolean;
+    constructor(opts: GameModeOpts);
+}
+interface GameModeOpts {
     /**
-     * Draws a board using specified reel stops.
+     * Name of the game mode.
      */
-    drawBoardWithForcedStops(reels: Reels, forcedStops: Record<string, number>): void;
+    name: string;
     /**
-     * Draws a board using random reel stops.
+     * Number of reels the board has.
      */
-    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>);
+    reelsAmount: number;
     /**
-     * Resets the board to an empty state.\
-     * This is called before drawing a new board.
+     * 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.
      */
-    resetBoard(): void;
-    private makeEmptyReels;
-    private resetReels;
+    symbolsPerReel: number[];
     /**
-     * Counts how many symbols matching the criteria are on a specific reel.
+     * Cost of the game mode, multiplied by the base bet.
      */
-    countSymbolsOnReel(symbolOrProperties: GameSymbol | Record<string, any>, reelIndex: number): number;
+    cost: 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.
+     * The target RTP of the game.
      */
-    countSymbolsOnBoard(symbolOrProperties: GameSymbol | Record<string, any>): [number, Record<number, number>];
+    rtp: number;
     /**
-     * Checks if a symbol appears more than once on any reel in the current reel set.
+     * 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.
      *
-     * Useful to check for "forbidden" generations, e.g. 2 scatters on one reel.
+     * 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.
      */
-    isSymbolOnAnyReelMultipleTimes(symbol: GameSymbol): boolean;
+    reelSets: ReelSet[];
     /**
-     * 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.
+     * 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.
      */
-    getReelStopsForSymbol(reels: Reels, symbol: GameSymbol): number[][];
+    resultSets: ResultSet<any>[];
     /**
-     * Combines multiple arrays of reel stops into a single array of reel stops.\
+     * Whether this game mode is a bonus buy.
      */
-    combineReelStops(...reelStops: number[][][]): number[][];
+    isBonusBuy: boolean;
+}
+
+declare class GameService<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> extends AbstractService {
+    constructor(ctx: () => GameContext<TGameModes, TSymbols, TUserState>);
     /**
-     * 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.
+     * Retrieves a reel set by its ID within a specific game mode.
      */
-    getRandomReelStops(reels: Reels, reelStops: number[][], amount: number): Record<string, number>;
+    getReelsetById(gameMode: string, id: string): Reels;
     /**
-     * Selects a random reel set based on the configured weights of the current result set.\
-     * Returns the reels as arrays of GameSymbols.
+     * Retrieves the number of free spins awarded for a given spin type and scatter count.
      */
-    getRandomReelset(): Reels;
+    getFreeSpinsForScatters(spinType: SpinType, scatterCount: number): number;
     /**
-     * Draws a board using specified reel stops.
+     * Retrieves a result set by its criteria within a specific game mode.
      */
-    drawBoardWithForcedStops(reels: Reels, forcedStops: Record<string, number>): void;
+    getResultSetByCriteria(mode: string, criteria: string): ResultSet<any>;
     /**
-     * Draws a board using random reel stops.
+     * Returns all configured symbols as an array.
      */
-    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>;
+    getSymbolArray(): GameSymbol[];
     /**
-     * Checks if core criteria is met, e.g. target multiplier or max win.
+     * Gets the configuration for the current game mode.
      */
-    meetsCriteria(ctx: AnySimulationContext<any, any, TUserState>): boolean;
-}
-interface ResultSetOpts<TUserState extends AnyUserData> {
+    getCurrentGameMode(): GameMode;
     /**
-     * A short string to describe the criteria for this ResultSet.
+     * Ensures the requested number of scatters is valid based on the game configuration.\
+     * Returns a valid number of scatters.
      */
-    criteria: string;
+    verifyScatterCount(numScatters: number): number;
     /**
-     * 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.**
+     * Increases the freespin count by the specified amount.
+     *
+     * Also sets `state.triggeredFreespins` to true.
      */
-    quota: number;
+    awardFreespins(amount: number): void;
+}
+
+declare class Wallet {
     /**
-     * The required multiplier for a simulated spin to be accepted.
+     * Total win amount (as the bet multiplier) from all simulations.
      */
-    multiplier?: number;
+    protected cumulativeWins: 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.
+     * Total win amount (as the bet multiplier) per spin type.
      *
      * @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 },
-     * }),
+     * {
+     *   basegame: 50,
+     *   freespins: 100,
+     *   superfreespins: 200,
+     * }
      * ```
      */
-    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;
+    protected cumulativeWinsPerSpinType: {
+        basegame: number;
+        freespins: number;
+    };
     /**
-     * If set, this will force the game to always trigger free spins.
+     * Current win amount (as the bet multiplier) for the ongoing simulation.
      */
-    forceFreespins?: boolean;
+    protected currentWin: number;
     /**
-     * Custom function to evaluate if the criteria is met.
+     * Current win amount (as the bet multiplier) for the ongoing simulation per spin type.
      *
-     * E.g. use this to check for free spins that upgraded to super free spins\
-     * or other arbitrary simulation criteria.
+     * @example
+     * ```ts
+     * {
+     *   basegame: 50,
+     *   freespins: 100,
+     *   superfreespins: 200,
+     * }
+     * ```
      */
-    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 gameModes: Record<GameModeName, GameMode>;
-        readonly symbols: Map<keyof TSymbols & string, TSymbols[keyof TSymbols]>;
-        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;
+    protected currentWinPerSpinType: {
+        basegame: number;
+        freespins: number;
     };
-    constructor(opts: CommonGameOptions<TGameModes, TSymbols, TUserState>);
     /**
-     * Generates reelset CSV files for all game modes.
+     * Holds the current win amount for a single (free) spin.\
+     * After each spin, this amount is added to `currentWinPerSpinType` and then reset to zero.
      */
-    generateReelsetFiles(): void;
+    protected currentSpinWin: number;
     /**
-     * Retrieves a reel set by its ID within a specific game mode.
+     * Current win amount (as the bet multiplier) for the ongoing tumble sequence.
      */
-    getReelsetById(gameMode: string, id: string): Reels;
+    protected currentTumbleWin: number;
+    constructor();
     /**
-     * Retrieves the number of free spins awarded for a given spin type and scatter count.
+     * 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()`
      */
-    getFreeSpinsForScatters(spinType: SpinType, scatterCount: number): number;
+    addSpinWin(amount: number): void;
     /**
-     * Retrieves a result set by its criteria within a specific game mode.
+     * Confirms the wins of the current spin.
+     *
+     * 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.
      */
-    getResultSetByCriteria(mode: string, criteria: string): ResultSet<any>;
+    confirmSpinWin(spinType: SpinType): void;
     /**
-     * Returns all configured symbols as an array.
+     * 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.
      */
-    getSymbolArray(): TSymbols[keyof TSymbols][];
-    static SPIN_TYPE: {
-        readonly BASE_GAME: "basegame";
-        readonly FREE_SPINS: "freespins";
+    getCumulativeWinsPerSpinType(): {
+        basegame: number;
+        freespins: number;
     };
-}
-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.
+     * Returns the current win amount (as the bet multiplier) for the ongoing simulation.
      */
-    context(ctx: SimulationContext<any, any, any>): WinType;
-    protected ensureContext(): void;
+    getCurrentWin(): number;
     /**
-     * Implementation of win evaluation logic. Sets `this.payout` and `this.winCombinations`.
+     * Returns the current spin win amount (as the bet multiplier) for the ongoing simulation.
      */
-    evaluateWins(): this;
+    getCurrentSpinWin(): number;
     /**
-     * Custom post-processing of wins, e.g. for handling multipliers.
+     * Returns the current tumble win amount (as the bet multiplier) for the ongoing simulation.
      */
-    postProcess(func: PostProcessFn<typeof this.winCombinations>): this;
+    getCurrentTumbleWin(): number;
     /**
-     * Returns the total payout and detailed win combinations.
+     * Returns the current win amount (as the bet multiplier) per spin type for the ongoing simulation.
      */
-    getWins(): {
-        payout: number;
-        winCombinations: WinCombination[];
+    getCurrentWinPerSpinType(): {
+        basegame: number;
+        freespins: number;
     };
-}
-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.
+     * Adds a win to `currentSpinWin` and `currentTumbleWin`.
      *
-     * @example
-     * If you have different wild symbols, each with a property `isWild: true`, you can define:
-     * ```ts
-     * wildSymbol: { isWild: true }
-     * ```
+     * After each (free) spin, this amount should be added to `currentWinPerSpinType` via `confirmSpinWin()`
+     */
+    addTumbleWin(amount: number): void;
+    /**
+     * Intended for internal use only.
      *
-     * @example
-     * If you have a single wild symbol instance, you can define:
-     * ```ts
-     * wildSymbol: myWildSymbol
-     * ```
+     * Resets the current win amounts to zero.
      */
-    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: SimulationContext<any, any, any>) => LinesWinType;
-    getWins: () => {
-        payout: number;
-        winCombinations: LineWinCombination[];
-    };
-    constructor(opts: LinesWinTypeOpts);
-    private validateConfig;
-    private isWild;
-    evaluateWins(): this;
-}
-interface LinesWinTypeOpts extends WinTypeOpts {
+    resetCurrentWin(): void;
     /**
-     * Defines the paylines for the slot game.
+     * Intended for internal use only.
      *
-     * @example
-     * ```ts
-     * lines: {
-     *   1: [0, 0, 0, 0, 0],
-     *   2: [1, 1, 1, 1, 1],
-     *   3: [2, 2, 2, 2, 2],
-     * }
-     * ```
+     * Adds current wins to cumulative wins and resets current wins to zero.
      */
-    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;
+    confirmWins(ctx: GameContext): void;
+    /**
+     * Intended for internal use only.
+     *
+     * Transfers the win data from the given wallet to the calling book.
+     */
+    writePayoutToBook(ctx: GameContext): void;
+    /**
+     * Intended for internal use only.
+     */
+    serialize(): {
+        cumulativeWins: number;
+        cumulativeWinsPerSpinType: {
+            basegame: number;
+            freespins: number;
+        };
+        currentWin: number;
+        currentWinPerSpinType: {
+            basegame: number;
+            freespins: number;
+        };
+        currentSpinWin: number;
+        currentTumbleWin: number;
     };
+    /**
+     * Intended for internal use only.
+     */
+    merge(wallet: Wallet): void;
+    /**
+     * Intended for internal use only.
+     */
+    mergeSerialized(data: ReturnType<Wallet["serialize"]>): void;
 }
 
-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 {
+declare class WalletService<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> extends AbstractService {
+    private wallet;
+    constructor(ctx: () => GameContext<TGameModes, TSymbols, TUserState>);
+    private ensureWallet;
     /**
-     * The desired RTP (0-1)
+     * Intended for internal use only.
      */
-    rtp?: number | "x";
+    _getWallet(): Wallet;
     /**
-     * The desired average win (per spin).
+     * Intended for internal use only.
      */
-    avgWin?: number;
+    _setWallet(wallet: Wallet): void;
     /**
-     * The desired hit rate (e.g. `200` to hit 1 in 200 spins).
+     * Adds the given amount to the wallet state.
+     *
+     * After calculating the win for a board, call this method to update the wallet state.\
+     * If your game has tumbling mechanics, you should call this method again after every new tumble and win calculation.
      */
-    hitRate?: number | "x";
+    addSpinWin(amount: number): void;
     /**
-     * A way of filtering results by
+     * Helps to add tumble wins to the wallet state.
      *
-     * - 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)
+     * This also calls `addSpinWin()` internally, to add the tumble win to the overall spin win.
      */
-    searchConditions?: number | Record<string, string> | [number, number];
+    addTumbleWin(amount: number): void;
     /**
-     * **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.
+     * Confirms the wins of the current spin.
      *
-     * TODO add better explanation
+     * 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.
      */
-    priority: number;
+    confirmSpinWin(): void;
+    /**
+     * Gets the total win amount of the current simulation.
+     */
+    getCurrentWin(): number;
+    /**
+     * Gets the current spin win amount of the ongoing spin.
+     */
+    getCurrentSpinWin(): number;
+    /**
+     * Gets the current tumble win amount of the ongoing spin.
+     */
+    getCurrentTumbleWin(): number;
 }
 
-declare class OptimizationScaling {
-    protected config: OptimizationScalingOpts;
-    constructor(opts: OptimizationScalingOpts);
-    getConfig(): OptimizationScalingOpts;
+type GameContext<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> = {
+    /**
+     * The static configuration of the game.
+     */
+    config: GameConfig<TGameModes, TSymbols, TUserState>;
+    /**
+     * Game state holding information about the current simulation.
+     */
+    state: GameState<TUserState>;
+    /**
+     * Services providing game functionality.
+     */
+    services: GameContextServices;
+};
+interface GameContextServices {
+    /**
+     * Service providing common utility functions.
+     */
+    game: GameService;
+    /**
+     * Service for interacting with the book data or recorder.
+     */
+    data: DataService;
+    /**
+     * Service managing the game board and reels.
+     */
+    board: BoardService;
+    /**
+     * Service providing win related functionality.
+     */
+    wallet: WalletService;
+    /**
+     * Service for seeded random number generation.
+     */
+    rng: RngService;
 }
-type OptimizationScalingOpts = Array<{
-    criteria: string;
-    scaleFactor: number;
-    winRange: [number, number];
-    probability: number;
-}>;
 
 declare class OptimizationParameters {
     protected parameters: OptimizationParametersOpts;
@@ -1102,6 +961,64 @@ interface OptimizationParametersOpts {
     readonly scoreType: "rtp";
 }
 
+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;
+}>;
+
 interface OptimizationOpts {
     gameModes: string[];
 }
@@ -1109,7 +1026,7 @@ interface OptimizerOpts {
     game: SlotGame<any, any, any>;
     gameModes: OptimzierGameModeConfig;
 }
-type OptimzierGameModeConfig = Record<GameModeName, {
+type OptimzierGameModeConfig = Record<string, {
     conditions: Record<string, OptimizationConditions>;
     scaling: OptimizationScaling;
     parameters: OptimizationParameters;
@@ -1124,16 +1041,16 @@ interface AnalysisOpts {
  * 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 readonly configOpts;
     private simulation?;
     private optimizer?;
     private analyzer?;
-    constructor(config: CommonGameOptions<TGameModes, TSymbols, TUserState>);
+    constructor(config: GameConfigOptions<TGameModes, TSymbols, TUserState>);
     /**
      * Sets up the simulation configuration.\
      * Must be called before `runTasks()`.
      */
-    configureSimulation(opts: SimulationConfigOpts): void;
+    configureSimulation(opts: SimulationOptions): void;
     /**
      * Sets up the optimization configuration.\
      * Must be called before `runTasks()`.
@@ -1151,34 +1068,39 @@ declare class SlotGame<TGameModes extends AnyGameModes = AnyGameModes, TSymbols
      * Runs the analysis based on the configured settings.
      */
     private runAnalysis;
+    /**
+     * Runs the configured tasks: simulation, optimization, and/or analysis.
+     */
     runTasks(opts?: {
         doSimulation?: boolean;
         doOptimization?: boolean;
         doAnalysis?: boolean;
-        simulationOpts?: SimulationOpts;
+        simulationOpts?: SimulationConfigOptions;
         optimizationOpts?: OptimizationOpts;
         analysisOpts?: AnalysisOpts;
     }): Promise<void>;
     /**
      * Gets the game configuration.
      */
-    getConfig(): GameConfig<TGameModes, TSymbols, TUserState>;
+    getConfig(): {
+        symbols: Map<keyof TSymbols & string, TSymbols[keyof TSymbols]>;
+        anticipationTriggers: {
+            basegame: number;
+            freespins: number;
+        };
+        outputDir: string;
+        id: string;
+        name: string;
+        gameModes: TGameModes;
+        scatterToFreespins: Record<string, Record<number, number>>;
+        padSymbols: number;
+        maxWinX: number;
+        userState: TUserState;
+        hooks: GameHooks<TGameModes, TSymbols, TUserState>;
+    };
 }
 
-/**
- * @internal
- */
-interface CommonGameOptions<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> {
-    id: string;
-    name: string;
-    gameModes: Record<GameModeName, GameMode>;
-    symbols: TSymbols;
-    scatterToFreespins: Record<string, Record<number, number>>;
-    padSymbols?: number;
-    maxWinX: number;
-    hooks: GameHooks<TGameModes, TSymbols, TUserState>;
-    userState?: TUserState;
-}
+type InferGameType<TGameModes extends AnyGameModes, TSymbols extends AnySymbols, TUserState extends AnyUserData> = SlotGame<TGameModes, TSymbols, TUserState>;
 /**
  * @internal
  */
@@ -1213,79 +1135,367 @@ interface GameHooks<TGameModes extends AnyGameModes = AnyGameModes, TSymbols ext
      * 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;
+    onHandleGameFlow: (ctx: GameContext<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;
+    onSimulationAccepted?: (ctx: GameContext<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 SpinType = (typeof SPIN_TYPE)[keyof typeof SPIN_TYPE];
+type Reels = GameSymbol[][];
 
-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> {
+declare function createSlotGame<TGame>(opts: TGame extends InferGameType<infer G, infer S, infer U> ? GameConfigOptions<G, S, U> : never): TGame;
+declare const defineUserState: <TUserState extends AnyUserData>(data: TUserState) => TUserState;
+declare const defineSymbols: <TSymbols extends AnySymbols>(symbols: TSymbols) => TSymbols;
+declare const defineGameModes: <TGameModes extends AnyGameModes>(gameModes: TGameModes) => TGameModes;
+
+declare class WinType {
+    protected payout: number;
+    protected winCombinations: WinCombination[];
+    protected ctx: GameContext;
+    protected readonly wildSymbol?: WildSymbol;
+    constructor(opts: WinTypeOpts);
     /**
-     * The unique identifier of the game, used for configuration and identification.
+     * Implementation of win evaluation logic. Sets `this.payout` and `this.winCombinations`.
      */
-    id: CommonGameOptions["id"];
+    evaluateWins(board: Reels): this;
     /**
-     * The name of the game, used for display purposes.
+     * Custom post-processing of wins, e.g. for handling multipliers.
      */
-    name: CommonGameOptions["name"];
+    postProcess(func: PostProcessFn<typeof this.winCombinations>): this;
     /**
-     * A GameMode is the core structure of a slot, defining the board,\
-     * bet cost, win type, and other properties.
+     * Returns the total payout and detailed win combinations.
      */
-    gameModes: TGameModes;
+    getWins(): {
+        payout: number;
+        winCombinations: WinCombination[];
+    };
+    protected isWild(symbol: GameSymbol): boolean;
+}
+interface WinTypeOpts {
     /**
-     * A list of all symbols that will appear on the reels.
+     * A reference to the game context.
      */
-    symbols: TSymbols;
+    ctx: GameContext<any, any, any>;
     /**
-     * A mapping from spin type to scatter counts to the number of free spins awarded.
+     * 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
-     * scatterToFreespins: {
-     *   [GameConfig.SPIN_TYPE.BASE_GAME]: {
-     *     3: 10,
-     *     4: 12,
-     *     5: 15,
-     *   },
-     *   [GameConfig.SPIN_TYPE.FREE_SPINS]: {
-     *     3: 6,
-     *     4: 8,
-     *     5: 10,
-     *   },
-     * },
+     * wildSymbol: { isWild: true }
+     * ```
+     *
+     * @example
+     * If you have a single wild symbol instance, you can define:
+     * ```ts
+     * wildSymbol: myWildSymbol
      * ```
      */
-    scatterToFreespins: CommonGameOptions["scatterToFreespins"];
+    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: GameContext) => {
+    payout: number;
+    winCombinations: TWinCombs;
+};
+type WildSymbol = GameSymbol | Record<string, any>;
+
+declare class LinesWinType extends WinType {
+    protected lines: Record<number, number[]>;
+    protected winCombinations: LineWinCombination[];
+    getWins: () => {
+        payout: number;
+        winCombinations: LineWinCombination[];
+    };
+    constructor(opts: LinesWinTypeOpts);
+    private validateConfig;
     /**
-     * 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.
+     * Calculates wins based on the defined paylines and provided board state.\
+     * Retrieve the results using `getWins()` after.
+     */
+    evaluateWins(board: Reels): this;
+}
+interface LinesWinTypeOpts extends WinTypeOpts {
+    /**
+     * Defines the paylines for the slot game.
      *
-     * Default: 1
+     * @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 {
+}
+
+/**
+ * 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 GeneratedReelSet extends ReelSet {
+    protected readonly symbolWeights: Map<string, number>;
+    protected readonly rowsAmount: number;
+    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>>;
+    private overrideExisting;
+    constructor(opts: GeneratedReelSetOptions);
+    private validateConfig;
+    private isSymbolAllowedOnReel;
+    private resolveStacking;
+    private tryPlaceStack;
+    /**
+     * Checks if a symbol can be placed at the target index without violating spacing rules.
      */
-    padSymbols?: CommonGameOptions["padSymbols"];
+    private violatesSpacing;
+    generateReels({ gameConfig: config }: Simulation): void;
+}
+interface GeneratedReelSetOptions extends ReelSetOptions {
     /**
-     * The maximum win multiplier of the game, e.g. 5000 for a 5000x max win.
+     * The weights of the symbols in the reelset.\
+     * This is a mapping of symbol IDs to their respective weights.
      */
-    maxWinX: CommonGameOptions["maxWinX"];
+    symbolWeights: Record<string, number>;
     /**
-     * Custom additional state that can be used in game flow logic.
+     * The number of rows in the reelset.\
+     * Default is 250, but can be adjusted as needed.
      */
-    userState?: TUserState;
+    rowsAmount?: 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.
+     * 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.
      */
-    hooks: CommonGameOptions<TGameModes, TSymbols, TUserState>["hooks"];
+    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;
+}
+
+/**
+ * This class is responsible for providing reel sets for slot games based on a static configuration or file.
+ */
+declare class StaticReelSet extends ReelSet {
+    reels: Reels;
+    csvPath: string;
+    private _strReels;
+    constructor(opts: StaticReelSetOptions);
+    private validateConfig;
+    generateReels({ gameConfig: config }: Simulation): void;
+}
+interface StaticReelSetOptions extends ReelSetOptions {
+    reels?: string[][];
+    csvPath?: string;
+}
+
+declare class StandaloneBoard {
+    private board;
+    private ctx;
+    private reelsAmount;
+    private symbolsPerReel;
+    private padSymbols;
+    constructor(opts: StandaloneBoardOptions);
+    /**
+     * Resets the board to an empty state.\
+     * This is called before drawing a new board.
+     */
+    resetBoard(): void;
+    /**
+     * Gets the current reels and symbols on the board.
+     */
+    getBoardReels(): Reels;
+    getPaddingTop(): Reels;
+    getPaddingBottom(): Reels;
+    private resetReels;
+    /**
+     * Sets the anticipation value for a specific reel.
+     */
+    setAnticipationForReel(reelIndex: number, value: boolean): void;
+    /**
+     * 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<number, number>;
+    /**
+     * Selects a random reel set based on the configured weights of the current result set.\
+     * 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;
+    /**
+     * Tumbles the board. All given symbols will be deleted and new symbols will fall from the top.
+     */
+    tumbleBoard(symbolsToDelete: Array<{
+        reelIdx: number;
+        rowIdx: number;
+    }>): void;
+}
+interface StandaloneBoardOptions {
+    ctx: GameContext;
+    reelsAmount: number;
+    symbolsPerReel: number[];
+    padSymbols: number;
 }
-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: <TSymbols extends AnySymbols>(symbols: TSymbols) => TSymbols;
-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 };
+export { type AnyGameModes, type AnySymbols, type AnyUserData, ClusterWinType, type GameContext, type GameHooks, GameMode, GameSymbol, GeneratedReelSet, type InferGameType, LinesWinType, ManywaysWinType, OptimizationConditions, OptimizationParameters, OptimizationScaling, type Reels, ResultSet, SPIN_TYPE, type SpinType, StandaloneBoard, StaticReelSet, createSlotGame, defineGameModes, defineSymbols, defineUserState };