@slot-engine/core 0.2.2 → 0.2.4

package/dist/index.d.mts

@@ -64,6 +64,7 @@ type PermanentFilePaths = {
     simulationSummary: string;
     statsPayouts: string;
     statsSummary: string;
+    statsRecords: string;
 };
 type TemporaryFilePaths = {
     tempBooks: (mode: string, i: number) => string;
@@ -558,6 +559,10 @@ declare class BoardService<TGameModes extends AnyGameModes = AnyGameModes, TSymb
      * Removes the symbol at the specified reel and row index.
      */
     removeSymbol(reelIndex: number, rowIndex: number): void;
+    /**
+     * Updates properties of the symbol at the specified reel and row index.
+     */
+    updateSymbol(reelIndex: number, rowIndex: number, properties: Record<string, any>): void;
     private resetReels;
     /**
      * Sets the anticipation value for a specific reel.
@@ -781,7 +786,6 @@ declare class DataService<TGameModes extends AnyGameModes = AnyGameModes, TSymbo
     recordSymbolOccurrence(data: {
         kind: number;
         symbolId: string;
-        spinType: SpinType;
         [key: string]: any;
     }): void;
     /**
@@ -1242,7 +1246,40 @@ interface PayoutStatistics {
     };
 }
 interface AnalysisOpts {
+    /**
+     * Which game modes to analyze.
+     */
     gameModes: string[];
+    /**
+     * Configure which recorded properties to analyze.
+     * This will provide you with hit rates for the specified groupings.
+     * Each entry defines a grouping strategy for statistics.
+     *
+     * @example
+     * ```ts
+     * recordStats: [
+     *   { groupBy: ["symbolId", "kind", "spinType"] }, // All win combinations
+     *   { groupBy: ["symbolId", "kind"], filter: { spinType: "basegame" } }, // Base game win combinations only
+     *   { groupBy: ["criteria"] }, // Hit rate by result set criteria
+     * ]
+     * ```
+     */
+    recordStats?: RecordStatsConfig[];
+}
+interface RecordStatsConfig {
+    /**
+     * Properties to group by from the recorded search entries.\
+     * E.g. `["symbolId", "kind", "spinType"]` for symbol hit rates.
+     */
+    groupBy: string[];
+    /**
+     * Optional filter to only include records matching these values.
+     */
+    filter?: Record<string, string>;
+    /**
+     * Optional custom name for this stats group in the output.
+     */
+    name?: string;
 }
 interface Statistics {
     gameMode: string;
@@ -1554,7 +1591,9 @@ declare class ManywaysWinType extends WinType {
      * Calculates wins based on the defined paylines and provided board state.\
      * Retrieve the results using `getWins()` after.
      */
-    evaluateWins(board: Reels): this;
+    evaluateWins(board: Reels, opts?: {
+        jumpGaps?: boolean;
+    }): this;
     private getWayLength;
 }
 interface ManywaysWinTypeOpts extends WinTypeOpts {
@@ -1748,6 +1787,10 @@ declare class StandaloneBoard {
      * Removes the symbol at the specified reel and row index.
      */
     removeSymbol(reelIndex: number, rowIndex: number): void;
+    /**
+     * Updates properties of the symbol at the specified reel and row index.
+     */
+    updateSymbol(reelIndex: number, rowIndex: number, properties: Record<string, any>): void;
     private resetReels;
     /**
      * Sets the anticipation value for a specific reel.

package/dist/index.d.ts

@@ -64,6 +64,7 @@ type PermanentFilePaths = {
     simulationSummary: string;
     statsPayouts: string;
     statsSummary: string;
+    statsRecords: string;
 };
 type TemporaryFilePaths = {
     tempBooks: (mode: string, i: number) => string;
@@ -558,6 +559,10 @@ declare class BoardService<TGameModes extends AnyGameModes = AnyGameModes, TSymb
      * Removes the symbol at the specified reel and row index.
      */
     removeSymbol(reelIndex: number, rowIndex: number): void;
+    /**
+     * Updates properties of the symbol at the specified reel and row index.
+     */
+    updateSymbol(reelIndex: number, rowIndex: number, properties: Record<string, any>): void;
     private resetReels;
     /**
      * Sets the anticipation value for a specific reel.
@@ -781,7 +786,6 @@ declare class DataService<TGameModes extends AnyGameModes = AnyGameModes, TSymbo
     recordSymbolOccurrence(data: {
         kind: number;
         symbolId: string;
-        spinType: SpinType;
         [key: string]: any;
     }): void;
     /**
@@ -1242,7 +1246,40 @@ interface PayoutStatistics {
     };
 }
 interface AnalysisOpts {
+    /**
+     * Which game modes to analyze.
+     */
     gameModes: string[];
+    /**
+     * Configure which recorded properties to analyze.
+     * This will provide you with hit rates for the specified groupings.
+     * Each entry defines a grouping strategy for statistics.
+     *
+     * @example
+     * ```ts
+     * recordStats: [
+     *   { groupBy: ["symbolId", "kind", "spinType"] }, // All win combinations
+     *   { groupBy: ["symbolId", "kind"], filter: { spinType: "basegame" } }, // Base game win combinations only
+     *   { groupBy: ["criteria"] }, // Hit rate by result set criteria
+     * ]
+     * ```
+     */
+    recordStats?: RecordStatsConfig[];
+}
+interface RecordStatsConfig {
+    /**
+     * Properties to group by from the recorded search entries.\
+     * E.g. `["symbolId", "kind", "spinType"]` for symbol hit rates.
+     */
+    groupBy: string[];
+    /**
+     * Optional filter to only include records matching these values.
+     */
+    filter?: Record<string, string>;
+    /**
+     * Optional custom name for this stats group in the output.
+     */
+    name?: string;
 }
 interface Statistics {
     gameMode: string;
@@ -1554,7 +1591,9 @@ declare class ManywaysWinType extends WinType {
      * Calculates wins based on the defined paylines and provided board state.\
      * Retrieve the results using `getWins()` after.
      */
-    evaluateWins(board: Reels): this;
+    evaluateWins(board: Reels, opts?: {
+        jumpGaps?: boolean;
+    }): this;
     private getWayLength;
 }
 interface ManywaysWinTypeOpts extends WinTypeOpts {
@@ -1748,6 +1787,10 @@ declare class StandaloneBoard {
      * Removes the symbol at the specified reel and row index.
      */
     removeSymbol(reelIndex: number, rowIndex: number): void;
+    /**
+     * Updates properties of the symbol at the specified reel and row index.
+     */
+    updateSymbol(reelIndex: number, rowIndex: number, properties: Record<string, any>): void;
     private resetReels;
     /**
      * Sets the anticipation value for a specific reel.

package/dist/index.js

@@ -92,7 +92,8 @@ function createPermanentFilePaths(basePath) {
     publishFiles: import_path.default.join(basePath, "publish_files"),
     simulationSummary: import_path.default.join(basePath, "simulation_summary.json"),
     statsPayouts: import_path.default.join(basePath, "stats_payouts.json"),
-    statsSummary: import_path.default.join(basePath, "stats_summary.json")
+    statsSummary: import_path.default.join(basePath, "stats_summary.json"),
+    statsRecords: import_path.default.join(basePath, "stats_records.json")
   };
 }
 function createTemporaryFilePaths(basePath, tempFolder) {
@@ -510,6 +511,14 @@ var Board = class {
       this.reels[reelIndex].splice(rowIndex, 1);
     }
   }
+  updateSymbol(reelIndex, rowIndex, properties) {
+    const symbol = this.getSymbol(reelIndex, rowIndex);
+    if (symbol) {
+      for (const [key, value] of Object.entries(properties)) {
+        symbol.properties.set(key, value);
+      }
+    }
+  }
   makeEmptyReels(opts) {
     const length = opts.reelsAmount ?? opts.ctx.services.game.getCurrentGameMode().reelsAmount;
     (0, import_assert3.default)(length, "Cannot make empty reels without context or reelsAmount.");
@@ -879,6 +888,12 @@ var BoardService = class extends AbstractService {
   removeSymbol(reelIndex, rowIndex) {
     this.board.removeSymbol(reelIndex, rowIndex);
   }
+  /**
+   * Updates properties of the symbol at the specified reel and row index.
+   */
+  updateSymbol(reelIndex, rowIndex, properties) {
+    this.board.updateSymbol(reelIndex, rowIndex, properties);
+  }
   resetReels() {
     this.board.resetReels({
       ctx: this.ctx()
@@ -1087,7 +1102,10 @@ var DataService = class extends AbstractService {
    * Calls `ctx.services.data.record()` with the provided data.
    */
   recordSymbolOccurrence(data) {
-    this.record(data);
+    this.record({
+      ...data,
+      spinType: this.ctx().state.currentSpinType
+    });
   }
   /**
    * Adds an event to the book.
@@ -3109,15 +3127,21 @@ function getLessBetHitrate(payoutWeights, cost) {
 
 // src/analysis/index.ts
 var import_worker_threads3 = require("worker_threads");
+var import_chalk3 = __toESM(require("chalk"));
 var Analysis = class {
   game;
   constructor(game) {
     this.game = game;
   }
-  async runAnalysis(gameModes) {
+  async runAnalysis(opts) {
+    const { gameModes, recordStats = [] } = opts;
     if (!import_worker_threads3.isMainThread) return;
+    console.log(import_chalk3.default.gray("Starting analysis..."));
     this.getNumberStats(gameModes);
     this.getWinRanges(gameModes);
+    if (recordStats.length > 0) {
+      this.getRecordStats(gameModes, recordStats);
+    }
     console.log("Analysis complete. Files written to build directory.");
   }
   getNumberStats(gameModes) {
@@ -3294,6 +3318,85 @@ var Analysis = class {
     }
     writeJsonFile(meta.paths.statsPayouts, payoutRanges);
   }
+  getRecordStats(gameModes, recordStatsConfig) {
+    const meta = this.game.getMetadata();
+    const allStats = [];
+    for (const modeStr of gameModes) {
+      const lutOptimized = parseLookupTable(
+        import_fs4.default.readFileSync(meta.paths.lookupTablePublish(modeStr), "utf-8")
+      );
+      const totalWeight = getTotalLutWeight(lutOptimized);
+      const weightMap = /* @__PURE__ */ new Map();
+      lutOptimized.forEach(([bookId, weight]) => {
+        weightMap.set(bookId, weight);
+      });
+      const forceRecordsPath = meta.paths.forceRecords(modeStr);
+      if (!import_fs4.default.existsSync(forceRecordsPath)) continue;
+      const forceRecords = JSON.parse(
+        import_fs4.default.readFileSync(forceRecordsPath, "utf-8")
+      );
+      const modeStats = {
+        gameMode: modeStr,
+        groups: []
+      };
+      for (const config of recordStatsConfig) {
+        const groupName = config.name || config.groupBy.join("_");
+        const aggregated = /* @__PURE__ */ new Map();
+        for (const record of forceRecords) {
+          const searchMap = new Map(record.search.map((s) => [s.name, s.value]));
+          if (config.filter) {
+            let matches = true;
+            for (const [key2, value] of Object.entries(config.filter)) {
+              if (searchMap.get(key2) !== value) {
+                matches = false;
+                break;
+              }
+            }
+            if (!matches) continue;
+          }
+          const hasAllProps = config.groupBy.every((prop) => searchMap.has(prop));
+          if (!hasAllProps) continue;
+          const key = config.groupBy.map((prop) => searchMap.get(prop)).join("|");
+          const properties = Object.fromEntries(
+            config.groupBy.map((prop) => [prop, searchMap.get(prop)])
+          );
+          let totalWeight2 = 0;
+          for (const bookId of record.bookIds) {
+            totalWeight2 += weightMap.get(bookId) ?? 0;
+          }
+          const existing = aggregated.get(key);
+          if (existing) {
+            existing.count += record.timesTriggered;
+            existing.totalWeight += totalWeight2;
+          } else {
+            aggregated.set(key, {
+              properties,
+              count: record.timesTriggered,
+              totalWeight: totalWeight2
+            });
+          }
+        }
+        const items = Array.from(aggregated.entries()).map(([key, data]) => {
+          const hitRate = round(totalWeight / data.totalWeight, 4);
+          return {
+            key,
+            properties: data.properties,
+            count: data.count,
+            hitRateString: `1 in ${Math.round(hitRate).toLocaleString()}`,
+            hitRate
+          };
+        }).sort((a, b) => a.hitRate - b.hitRate);
+        modeStats.groups.push({
+          name: groupName,
+          groupBy: config.groupBy,
+          filter: config.filter,
+          items
+        });
+      }
+      allStats.push(modeStats);
+    }
+    writeJsonFile(meta.paths.statsRecords, allStats);
+  }
   getGameModeConfig(mode) {
     const config = this.game.getConfig().gameModes[mode];
     (0, import_assert6.default)(config, `Game mode "${mode}" not found in game config`);
@@ -3658,7 +3761,7 @@ var SlotGame = class _SlotGame {
    */
   runAnalysis(opts) {
     this.analyzer = new Analysis(this);
-    this.analyzer.runAnalysis(opts.gameModes);
+    this.analyzer.runAnalysis(opts);
   }
   /**
    * Runs the configured tasks: simulation, optimization, and/or analysis.
@@ -4104,27 +4207,36 @@ var ManywaysWinType = class extends WinType {
    * Calculates wins based on the defined paylines and provided board state.\
    * Retrieve the results using `getWins()` after.
    */
-  evaluateWins(board) {
+  evaluateWins(board, opts = {}) {
     this.validateConfig();
+    const { jumpGaps = false } = opts;
     const waysWins = [];
     const reels = board;
     const possibleWaysWins = /* @__PURE__ */ new Map();
     const candidateSymbols = /* @__PURE__ */ new Map();
-    let searchReelIdx = 0;
-    let searchActive = true;
-    while (searchActive && searchReelIdx < reels.length) {
-      const reel = reels[searchReelIdx];
-      let hasWild = false;
-      for (const symbol of reel) {
-        candidateSymbols.set(symbol.id, symbol);
-        if (this.isWild(symbol)) {
-          hasWild = true;
+    if (jumpGaps) {
+      for (const reel of reels) {
+        for (const symbol of reel) {
+          candidateSymbols.set(symbol.id, symbol);
         }
       }
-      if (!hasWild) {
-        searchActive = false;
+    } else {
+      let searchReelIdx = 0;
+      let searchActive = true;
+      while (searchActive && searchReelIdx < reels.length) {
+        const reel = reels[searchReelIdx];
+        let hasWild = false;
+        for (const symbol of reel) {
+          candidateSymbols.set(symbol.id, symbol);
+          if (this.isWild(symbol)) {
+            hasWild = true;
+          }
+        }
+        if (!hasWild) {
+          searchActive = false;
+        }
+        searchReelIdx++;
       }
-      searchReelIdx++;
     }
     for (const baseSymbol of candidateSymbols.values()) {
       let symbolList = {};
@@ -4140,7 +4252,7 @@ var ManywaysWinType = class extends WinType {
             symbolList[ridx].push({ reel: ridx, row: sidx, symbol });
           }
         }
-        if (!symbolList[ridx]) {
+        if (!symbolList[ridx] && !jumpGaps) {
           isInterrupted = true;
           break;
         }
@@ -4156,7 +4268,7 @@ var ManywaysWinType = class extends WinType {
     for (const [baseSymbolId, symbolList] of possibleWaysWins.entries()) {
       const wayLength = this.getWayLength(symbolList);
       let baseSymbol = Object.values(symbolList).flatMap((l) => l.map((s) => s)).find((s) => !this.isWild(s.symbol))?.symbol;
-      if (!baseSymbol) baseSymbol = symbolList[0][0].symbol;
+      if (!baseSymbol) baseSymbol = symbolList[Object.keys(symbolList)[0]][0].symbol;
       const singleWayPayout = this.getSymbolPayout(baseSymbol, wayLength);
       const totalWays = Object.values(symbolList).reduce(
         (ways, syms) => ways * syms.length,
@@ -4190,7 +4302,7 @@ var ManywaysWinType = class extends WinType {
     return this;
   }
   getWayLength(symbolList) {
-    return Math.max(...Object.keys(symbolList).map((k) => parseInt(k, 10))) + 1;
+    return Object.keys(symbolList).length;
   }
 };
 
@@ -4652,6 +4764,12 @@ var StandaloneBoard = class {
   removeSymbol(reelIndex, rowIndex) {
     this.board.removeSymbol(reelIndex, rowIndex);
   }
+  /**
+   * Updates properties of the symbol at the specified reel and row index.
+   */
+  updateSymbol(reelIndex, rowIndex, properties) {
+    this.board.updateSymbol(reelIndex, rowIndex, properties);
+  }
   resetReels() {
     this.board.resetReels({
       ctx: this.ctx