@slot-engine/core 0.1.10 → 0.1.11

package/dist/index.d.mts

@@ -81,6 +81,22 @@ type GameConfig<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends
     anticipationTriggers: Record<(typeof SPIN_TYPE)[keyof typeof SPIN_TYPE], number>;
 };
 
+/**
+ * Class for handling simulations of the slot game.
+ *
+ * High level overview:
+ * - Main thread compiles user code to JS and spawns workers
+ * - Workers run compiled code to execute simulations
+ * - Workers send data to main thread
+ * - Main thread merges data and writes files
+ *
+ * Notes:
+ * - Backpressure system with credits to avoid overwhelming the main thread
+ * - Limited amount of credits
+ * - Worker uses credit to return data to main thread
+ * - After writing data, main thread gives worker new credit
+ * - Prevents workers sending more data than the main thread can write in time
+ */
 declare class Simulation {
     readonly gameConfigOpts: GameConfigOptions;
     readonly gameConfig: GameConfig;
@@ -88,10 +104,15 @@ declare class Simulation {
     readonly concurrency: number;
     private debug;
     private actualSims;
-    private library;
     private wallet;
     private recordsWriteStream;
     private hasWrittenRecord;
+    private readonly maxPendingSims;
+    private readonly maxHighWaterMark;
+    private PATHS;
+    private credits;
+    private creditWaiters;
+    private creditListenerInit;
     constructor(opts: SimulationOptions, gameConfigOpts: GameConfigOptions);
     runSimulation(opts: SimulationConfigOptions): Promise<void>;
     /**
@@ -99,7 +120,9 @@ declare class Simulation {
      */
     spawnWorkersForGameMode(opts: {
         mode: string;
-        simNumsToCriteria: Record<number, string>;
+        chunks: [number, number][];
+        chunkCriteriaCounts: Array<Record<string, number>>;
+        totalSims: number;
     }): Promise<void>;
     callWorker(opts: {
         basePath: string;
@@ -108,6 +131,7 @@ declare class Simulation {
         simEnd: number;
         index: number;
         totalSims: number;
+        criteriaCounts: Record<string, number>;
     }): Promise<unknown>;
     /**
      * Will run a single simulation until the specified criteria is met.
@@ -118,6 +142,8 @@ declare class Simulation {
         criteria: string;
         index: number;
     }): void;
+    private initCreditListener;
+    private acquireCredit;
     /**
      * If a simulation does not meet the required criteria, reset the state to run it again.
      *
@@ -136,16 +162,6 @@ declare class Simulation {
      * You can customize the game flow by implementing the `onHandleGameFlow` hook in the game configuration.
      */
     protected handleGameFlow(ctx: GameContext): void;
-    /**
-     * Creates a CSV file in the format "simulationId,weight,payout".
-     *
-     * `weight` defaults to 1.
-     */
-    private writeLookupTableCSV;
-    /**
-     * Creates a CSV file in the format "simulationId,criteria,payoutBase,payoutFreespins".
-     */
-    private writeLookupTableSegmentedCSV;
     private writeRecords;
     private writeIndexJson;
     private writeBooksJson;
@@ -158,6 +174,7 @@ declare class Simulation {
      * Generates reelset CSV files for all game modes.
      */
     private generateReelsetFiles;
+    private mergeCsv;
     /**
      * Confirms all pending records and adds them to the main records list.
      */
@@ -167,13 +184,29 @@ type SimulationOptions = {
     /**
      * Object containing the game modes and their respective simulation runs amount.
      */
-    simRunsAmount: Partial<Record<string, number>>;
+    simRunsAmount: Record<string, number>;
     /**
      * Number of concurrent processes to use for simulations.
      *
      * Default: 6
      */
     concurrency?: number;
+    /**
+     * The maximum number of simulation results to keep pending in memory before writing to disk.
+     *
+     * Higher values may speed up simulations but use more RAM.
+     *
+     * Default: 250
+     */
+    maxPendingSims?: number;
+    /**
+     * The maximum data buffer in MB for writing simulation results to disk.
+     *
+     * Higher values may speed up simulations but use more RAM.
+     *
+     * Default: 50
+     */
+    maxDiskBuffer?: number;
 };
 type SimulationConfigOptions = {
     debug?: boolean;
@@ -189,7 +222,7 @@ declare class ResultSet<TUserState extends AnyUserData> {
     forceFreespins?: boolean;
     evaluate?: (ctx: GameContext<AnyGameModes, AnySymbols, TUserState>) => boolean;
     constructor(opts: ResultSetOpts<TUserState>);
-    static assignCriteriaToSimulations(ctx: Simulation, gameModeName: string): Record<number, string>;
+    static getNumberOfSimsForCriteria(ctx: Simulation, gameModeName: string): Record<string, number>;
     /**
      * Checks if core criteria is met, e.g. target multiplier or max win.
      */
@@ -614,10 +647,6 @@ declare class Book {
         basegameWins: number;
         freespinsWins: number;
     };
-    /**
-     * Intended for internal use only.
-     */
-    static fromSerialized(data: ReturnType<Book["serialize"]>): Book;
 }
 interface BookEvent {
     index: number;

package/dist/index.d.ts

@@ -81,6 +81,22 @@ type GameConfig<TGameModes extends AnyGameModes = AnyGameModes, TSymbols extends
     anticipationTriggers: Record<(typeof SPIN_TYPE)[keyof typeof SPIN_TYPE], number>;
 };
 
+/**
+ * Class for handling simulations of the slot game.
+ *
+ * High level overview:
+ * - Main thread compiles user code to JS and spawns workers
+ * - Workers run compiled code to execute simulations
+ * - Workers send data to main thread
+ * - Main thread merges data and writes files
+ *
+ * Notes:
+ * - Backpressure system with credits to avoid overwhelming the main thread
+ * - Limited amount of credits
+ * - Worker uses credit to return data to main thread
+ * - After writing data, main thread gives worker new credit
+ * - Prevents workers sending more data than the main thread can write in time
+ */
 declare class Simulation {
     readonly gameConfigOpts: GameConfigOptions;
     readonly gameConfig: GameConfig;
@@ -88,10 +104,15 @@ declare class Simulation {
     readonly concurrency: number;
     private debug;
     private actualSims;
-    private library;
     private wallet;
     private recordsWriteStream;
     private hasWrittenRecord;
+    private readonly maxPendingSims;
+    private readonly maxHighWaterMark;
+    private PATHS;
+    private credits;
+    private creditWaiters;
+    private creditListenerInit;
     constructor(opts: SimulationOptions, gameConfigOpts: GameConfigOptions);
     runSimulation(opts: SimulationConfigOptions): Promise<void>;
     /**
@@ -99,7 +120,9 @@ declare class Simulation {
      */
     spawnWorkersForGameMode(opts: {
         mode: string;
-        simNumsToCriteria: Record<number, string>;
+        chunks: [number, number][];
+        chunkCriteriaCounts: Array<Record<string, number>>;
+        totalSims: number;
     }): Promise<void>;
     callWorker(opts: {
         basePath: string;
@@ -108,6 +131,7 @@ declare class Simulation {
         simEnd: number;
         index: number;
         totalSims: number;
+        criteriaCounts: Record<string, number>;
     }): Promise<unknown>;
     /**
      * Will run a single simulation until the specified criteria is met.
@@ -118,6 +142,8 @@ declare class Simulation {
         criteria: string;
         index: number;
     }): void;
+    private initCreditListener;
+    private acquireCredit;
     /**
      * If a simulation does not meet the required criteria, reset the state to run it again.
      *
@@ -136,16 +162,6 @@ declare class Simulation {
      * You can customize the game flow by implementing the `onHandleGameFlow` hook in the game configuration.
      */
     protected handleGameFlow(ctx: GameContext): void;
-    /**
-     * Creates a CSV file in the format "simulationId,weight,payout".
-     *
-     * `weight` defaults to 1.
-     */
-    private writeLookupTableCSV;
-    /**
-     * Creates a CSV file in the format "simulationId,criteria,payoutBase,payoutFreespins".
-     */
-    private writeLookupTableSegmentedCSV;
     private writeRecords;
     private writeIndexJson;
     private writeBooksJson;
@@ -158,6 +174,7 @@ declare class Simulation {
      * Generates reelset CSV files for all game modes.
      */
     private generateReelsetFiles;
+    private mergeCsv;
     /**
      * Confirms all pending records and adds them to the main records list.
      */
@@ -167,13 +184,29 @@ type SimulationOptions = {
     /**
      * Object containing the game modes and their respective simulation runs amount.
      */
-    simRunsAmount: Partial<Record<string, number>>;
+    simRunsAmount: Record<string, number>;
     /**
      * Number of concurrent processes to use for simulations.
      *
      * Default: 6
      */
     concurrency?: number;
+    /**
+     * The maximum number of simulation results to keep pending in memory before writing to disk.
+     *
+     * Higher values may speed up simulations but use more RAM.
+     *
+     * Default: 250
+     */
+    maxPendingSims?: number;
+    /**
+     * The maximum data buffer in MB for writing simulation results to disk.
+     *
+     * Higher values may speed up simulations but use more RAM.
+     *
+     * Default: 50
+     */
+    maxDiskBuffer?: number;
 };
 type SimulationConfigOptions = {
     debug?: boolean;
@@ -189,7 +222,7 @@ declare class ResultSet<TUserState extends AnyUserData> {
     forceFreespins?: boolean;
     evaluate?: (ctx: GameContext<AnyGameModes, AnySymbols, TUserState>) => boolean;
     constructor(opts: ResultSetOpts<TUserState>);
-    static assignCriteriaToSimulations(ctx: Simulation, gameModeName: string): Record<number, string>;
+    static getNumberOfSimsForCriteria(ctx: Simulation, gameModeName: string): Record<string, number>;
     /**
      * Checks if core criteria is met, e.g. target multiplier or max win.
      */
@@ -614,10 +647,6 @@ declare class Book {
         basegameWins: number;
         freespinsWins: number;
     };
-    /**
-     * Intended for internal use only.
-     */
-    static fromSerialized(data: ReturnType<Book["serialize"]>): Book;
 }
 interface BookEvent {
     index: number;