@slot-engine/core 0.1.14 → 0.2.0

package/dist/index.d.mts

@@ -3,6 +3,75 @@ declare const SPIN_TYPE: {
     readonly FREE_SPINS: "freespins";
 };
 
+declare class GameSymbol {
+    readonly id: string;
+    readonly pays?: Record<number, number>;
+    readonly 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;
+    /**
+     * Creates a clone of this GameSymbol.
+     */
+    clone(): GameSymbol;
+}
+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>;
+}
+
+type PermanentFilePaths = {
+    base: string;
+    books: (mode: string) => string;
+    booksIndex: (mode: string, worker: number) => string;
+    booksIndexMeta: (mode: string) => string;
+    booksChunk: (mode: string, worker: number, chunk: number) => string;
+    booksCompressed: (mode: string) => string;
+    lookupTable: (mode: string) => string;
+    lookupTableIndex: (mode: string) => string;
+    lookupTableSegmented: (mode: string) => string;
+    lookupTableSegmentedIndex: (mode: string) => string;
+    lookupTablePublish: (mode: string) => string;
+    forceRecords: (mode: string) => string;
+    forceKeys: (mode: string) => string;
+    indexJson: string;
+    publishFiles: string;
+    optimizationFiles: string;
+    simulationSummary: string;
+    statsPayouts: string;
+    statsSummary: string;
+};
+type TemporaryFilePaths = {
+    tempBooks: (mode: string, i: number) => string;
+    tempLookupTable: (mode: string, i: number) => string;
+    tempLookupTableSegmented: (mode: string, i: number) => string;
+    tempRecords: (mode: string) => string;
+};
+type FilePaths = PermanentFilePaths & TemporaryFilePaths;
+
 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.
@@ -68,18 +137,22 @@ interface GameConfigOptions<TGameModes extends AnyGameModes = AnyGameModes, TSym
      */
     rootDir?: string;
 }
-type GameConfig<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> = Required<Omit<GameConfigOptions<TGameModes, TSymbols, TUserState>, "symbols">> & {
+type GameConfig<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> = Required<Omit<GameConfigOptions<TGameModes, TSymbols, TUserState>, "symbols" | "rootDir">> & {
     /**
      * A map of all symbols.
      */
     symbols: Map<keyof TSymbols & string, TSymbols[keyof TSymbols]>;
-    outputDir: string;
-    rootDir: string;
     /**
      * A mapping of spin types to the number of scatter symbols required to trigger anticipation.
      */
     anticipationTriggers: Record<(typeof SPIN_TYPE)[keyof typeof SPIN_TYPE], number>;
 };
+type GameMetadata = {
+    outputDir: string;
+    rootDir: string;
+    isCustomRoot: boolean;
+    paths: PermanentFilePaths;
+};
 
 /**
  * Class for handling simulations of the slot game.
@@ -99,21 +172,32 @@ type GameConfig<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends
  */
 declare class Simulation {
     readonly gameConfigOpts: GameConfigOptions;
-    readonly gameConfig: GameConfig;
+    readonly gameConfig: GameConfig & GameMetadata;
     readonly simRunsAmount: Partial<Record<string, number>>;
     readonly concurrency: number;
     private debug;
     private actualSims;
     private wallet;
+    private summary;
     private recordsWriteStream;
     private hasWrittenRecord;
     private readonly streamHighWaterMark;
     private readonly maxPendingSims;
     private readonly maxHighWaterMark;
-    private PATHS;
+    private panelPort;
+    private panelActive;
+    private panelWsUrl;
+    private socket;
+    private tui;
+    private tempBookIndexPaths;
+    private bookIndexMetas;
+    PATHS: FilePaths;
     private credits;
     private creditWaiters;
     private creditListenerInit;
+    private bookBuffers;
+    private bookBufferSizes;
+    private bookChunkIndexes;
     constructor(opts: SimulationOptions, gameConfigOpts: GameConfigOptions);
     runSimulation(opts: SimulationConfigOptions): Promise<void>;
     /**
@@ -165,7 +249,6 @@ declare class Simulation {
     protected handleGameFlow(ctx: GameContext): void;
     private writeRecords;
     private writeIndexJson;
-    private writeBooksJson;
     /**
      * Compiles user configured game to JS for use in different Node processes
      */
@@ -175,11 +258,13 @@ declare class Simulation {
      * Generates reelset CSV files for all game modes.
      */
     private generateReelsetFiles;
+    private getTimeRemaining;
     private mergeCsv;
     /**
      * Confirms all pending records and adds them to the main records list.
      */
     confirmRecords(ctx: GameContext): void;
+    printSimulationSummary(): Promise<void>;
 }
 type SimulationOptions = {
     /**
@@ -211,7 +296,22 @@ type SimulationOptions = {
 };
 type SimulationConfigOptions = {
     debug?: boolean;
+    panelPort?: number;
 };
+type SimulationSummary = Record<string, {
+    total: {
+        numSims: number;
+        bsWins: number;
+        fsWins: number;
+        rtp: number;
+    };
+    criteria: Record<string, {
+        numSims: number;
+        bsWins: number;
+        fsWins: number;
+        rtp: number;
+    }>;
+}>;
 
 declare class ResultSet<TUserState extends AnyUserData> {
     criteria: string;
@@ -359,46 +459,6 @@ declare class AbstractService {
     constructor(ctx: () => GameContext);
 }
 
-declare class GameSymbol {
-    readonly id: string;
-    readonly pays?: Record<number, number>;
-    readonly 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;
-    /**
-     * Creates a clone of this GameSymbol.
-     */
-    clone(): GameSymbol;
-}
-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 class WinType {
     protected payout: number;
     protected winCombinations: WinCombination[];
@@ -605,8 +665,13 @@ declare class BoardService<TGameModes extends AnyGameModes = AnyGameModes, TSymb
 
 declare class Recorder {
     records: RecordItem[];
+    recordsMap: Map<string, RecordItem>;
     pendingRecords: PendingRecord[];
     constructor();
+    /**
+     * Intended for internal use only.
+     */
+    _reset(): void;
 }
 interface PendingRecord {
     bookId: number;
@@ -622,7 +687,7 @@ interface RecordItem {
 }
 
 declare class Book {
-    readonly id: number;
+    id: number;
     criteria: string;
     events: BookEvent[];
     payout: number;
@@ -632,7 +697,11 @@ declare class Book {
     /**
      * Intended for internal use only.
      */
-    setCriteria(criteria: string): void;
+    _reset(id: number, criteria: string): void;
+    /**
+     * Intended for internal use only.
+     */
+    _setCriteria(criteria: string): void;
     /**
      * Adds an event to the book.
      */
@@ -640,7 +709,7 @@ declare class Book {
     /**
      * Intended for internal use only.
      */
-    serialize(): {
+    _serialize(): {
         id: number;
         criteria: string;
         events: BookEvent[];
@@ -658,13 +727,16 @@ interface BookOpts {
     id: number;
     criteria: string;
 }
+interface WrittenBook {
+    id: number;
+    payoutMultiplier: number;
+    events: BookEvent[];
+}
 
 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;
     /**
      * Intended for internal use only.
      */
@@ -704,36 +776,16 @@ declare class DataService<TGameModes extends AnyGameModes = AnyGameModes, TSymbo
      * Adds an event to the book.
      */
     addBookEvent(event: Omit<BookEvent, "index">): void;
+    /**
+     * Write a log message to the terminal UI.
+     */
+    log(message: string): void;
     /**
      * Intended for internal use only.
      */
     _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>);
-    /**
-     * Random weighted selection from a set of items.
-     */
-    weightedRandom: <T extends Record<string, number>>(weights: T) => string;
-    /**
-     * Selects a random item from an array.
-     */
-    randomItem: <T>(array: T[]) => NonNullable<T>;
-    /**
-     * Shuffles an array.
-     */
-    shuffle: <T>(array: T[]) => T[];
-    /**
-     * Generates a random float between two values.
-     */
-    randomFloat: (low: number, high: number) => number;
-    /**
-     * Sets the seed for the RNG.
-     */
-    setSeedIfDifferent: (seed: number) => void;
-}
 declare class RandomNumberGenerator {
     mIdum: number;
     mIy: number;
@@ -907,6 +959,31 @@ declare class GameService<TGameModes extends AnyGameModes = AnyGameModes, TSymbo
     }[];
 }
 
+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>);
+    /**
+     * Random weighted selection from a set of items.
+     */
+    weightedRandom: <T extends Record<string, number>>(weights: T) => string;
+    /**
+     * Selects a random item from an array.
+     */
+    randomItem: <T>(array: T[]) => NonNullable<T>;
+    /**
+     * Shuffles an array.
+     */
+    shuffle: <T>(array: T[]) => T[];
+    /**
+     * Generates a random float between two values.
+     */
+    randomFloat: (low: number, high: number) => number;
+    /**
+     * Sets the seed for the RNG.
+     */
+    setSeedIfDifferent: (seed: number) => void;
+}
+
 declare class Wallet {
     /**
      * Total win amount (as the bet multiplier) from all simulations.
@@ -958,6 +1035,10 @@ declare class Wallet {
      */
     protected currentTumbleWin: number;
     constructor();
+    /**
+     * Intended for internal use only.
+     */
+    _reset(): void;
     /**
      * Updates the win for the current spin.
      *
@@ -1058,7 +1139,6 @@ declare class Wallet {
 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;
     /**
      * Intended for internal use only.
      */
@@ -1138,6 +1218,36 @@ interface GameContextServices {
     rng: RngService;
 }
 
+interface PayoutStatistics {
+    gameMode: string;
+    allPayouts: {
+        overall: Record<string, number>;
+        criteria: Record<string, Record<string, number>>;
+    };
+    uniquePayouts: {
+        overall: Record<string, number>;
+        criteria: Record<string, Record<string, number>>;
+    };
+}
+interface AnalysisOpts {
+    gameModes: string[];
+}
+interface Statistics {
+    gameMode: string;
+    totalWeight: number;
+    rtp: number;
+    avgWin: number;
+    minWin: number;
+    maxWin: number;
+    stdDev: number;
+    variance: number;
+    maxwinHitRate: number;
+    nonZeroHitRate: number;
+    nullHitRate: number;
+    lessBetHitRate: number;
+    uniquePayouts: number;
+}
+
 declare class OptimizationParameters {
     protected parameters: OptimizationParametersOpts;
     constructor(opts?: Partial<OptimizationParametersOpts>);
@@ -1231,10 +1341,6 @@ type OptimzierGameModeConfig = Record<string, {
     parameters: OptimizationParameters;
 }>;
 
-interface AnalysisOpts {
-    gameModes: string[];
-}
-
 /**
  * SlotGame class that encapsulates the game configuration and state.\
  * Main entry point for the slot game.
@@ -1270,14 +1376,7 @@ declare class SlotGame<TGameModes extends AnyGameModes = AnyGameModes, TSymbols
     /**
      * Runs the configured tasks: simulation, optimization, and/or analysis.
      */
-    runTasks(opts?: {
-        doSimulation?: boolean;
-        doOptimization?: boolean;
-        doAnalysis?: boolean;
-        simulationOpts?: SimulationConfigOptions;
-        optimizationOpts?: OptimizationOpts;
-        analysisOpts?: AnalysisOpts;
-    }): Promise<void>;
+    runTasks(opts?: TaskOptions): Promise<void>;
     /**
      * Gets the game configuration.
      */
@@ -1287,8 +1386,6 @@ declare class SlotGame<TGameModes extends AnyGameModes = AnyGameModes, TSymbols
             basegame: number;
             freespins: number;
         };
-        outputDir: string;
-        rootDir: string;
         id: string;
         name: string;
         gameModes: TGameModes;
@@ -1297,8 +1394,26 @@ declare class SlotGame<TGameModes extends AnyGameModes = AnyGameModes, TSymbols
         maxWinX: number;
         userState: TUserState;
         hooks: GameHooks<TGameModes, TSymbols, TUserState>;
+        rootDir?: string;
     };
+    getMetadata(): {
+        outputDir: string;
+        rootDir: string;
+        isCustomRoot: boolean;
+        paths: PermanentFilePaths;
+    };
+    clone(): SlotGame<TGameModes, TSymbols, TUserState>;
+}
+interface TaskOptions {
+    _internal_ignore_args?: boolean;
+    doSimulation?: boolean;
+    doOptimization?: boolean;
+    doAnalysis?: boolean;
+    simulationOpts?: SimulationConfigOptions;
+    optimizationOpts?: OptimizationOpts;
+    analysisOpts?: AnalysisOpts;
 }
+type SlotGameType<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends AnySymbols = AnySymbols, TUserState extends AnyUserData = AnyUserData> = SlotGame<TGameModes, TSymbols, TUserState>;
 
 type InferGameType<TGameModes extends AnyGameModes, TSymbols extends AnySymbols, TUserState extends AnyUserData> = SlotGame<TGameModes, TSymbols, TUserState>;
 /**
@@ -1343,12 +1458,17 @@ interface GameHooks<TGameModes extends AnyGameModes = AnyGameModes, TSymbols ext
 }
 type SpinType = (typeof SPIN_TYPE)[keyof typeof SPIN_TYPE];
 type Reels = GameSymbol[][];
+type LookupTable = [number, number, number][];
+type LookupTableSegmented = [number, string, number, number][];
 
 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 function parseLookupTable(content: string): LookupTable;
+declare function parseLookupTableSegmented(content: string): LookupTableSegmented;
+
 declare class LinesWinType extends WinType {
     protected lines: Record<number, number[]>;
     protected winCombinations: LineWinCombination[];
@@ -1463,7 +1583,7 @@ declare class GeneratedReelSet extends ReelSet {
      * Checks if a symbol can be placed at the target index without violating spacing rules.
      */
     private violatesSpacing;
-    generateReels(config: GameConfig): this;
+    generateReels(config: GameConfig & GameMetadata): this;
 }
 interface GeneratedReelSetOptions extends ReelSetOptions {
     /**
@@ -1729,4 +1849,4 @@ interface StandaloneBoardOptions {
     padSymbols: number;
 }
 
-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, type WinCombination, createSlotGame, defineGameModes, defineSymbols, defineUserState };
+export { type AnyGameModes, type AnySymbols, type AnyUserData, ClusterWinType, type GameContext, type GameHooks, GameMode, GameSymbol, GeneratedReelSet, type InferGameType, LinesWinType, type LookupTable, type LookupTableSegmented, ManywaysWinType, OptimizationConditions, OptimizationParameters, OptimizationScaling, type PayoutStatistics, RandomNumberGenerator, type RecordItem, type Reels, ResultSet, SPIN_TYPE, type SimulationSummary, type SlotGameType as SlotGame, type SpinType, StandaloneBoard, StaticReelSet, type Statistics, type WinCombination, type WrittenBook, createSlotGame, defineGameModes, defineSymbols, defineUserState, parseLookupTable, parseLookupTableSegmented };