@slot-engine/core 0.1.10 → 0.1.12

package/dist/index.mjs

@@ -32,7 +32,7 @@ function createGameConfig(opts) {
 // src/simulation/index.ts
 import fs2 from "fs";
 import path from "path";
-import assert6 from "assert";
+import assert7 from "assert";
 import zlib from "zlib";
 import readline2 from "readline";
 import { buildSync } from "esbuild";
@@ -258,6 +258,9 @@ var JSONL = class {
     });
   }
 };
+function round(value, decimals) {
+  return Number(Math.round(Number(value + "e" + decimals)) + "e-" + decimals);
+}
 
 // src/result-set/index.ts
 var ResultSet = class {
@@ -279,7 +282,7 @@ var ResultSet = class {
     this.forceFreespins = opts.forceFreespins;
     this.evaluate = opts.evaluate;
   }
-  static assignCriteriaToSimulations(ctx, gameModeName) {
+  static getNumberOfSimsForCriteria(ctx, gameModeName) {
     const rng = new RandomNumberGenerator();
     rng.setSeed(0);
     assert2(ctx.simRunsAmount, "Simulation configuration is not set.");
@@ -306,7 +309,7 @@ var ResultSet = class {
     const criteriaToWeights = Object.fromEntries(
       resultSets.map((rs) => [rs.criteria, rs.quota])
     );
-    while (totalSims != simNums) {
+    while (totalSims !== simNums) {
       const rs = rng.weightedRandom(criteriaToWeights);
       if (reduceSims && numberOfSimsForCriteria[rs] > 1) {
         numberOfSimsForCriteria[rs] -= 1;
@@ -319,18 +322,7 @@ var ResultSet = class {
       );
       reduceSims = totalSims > simNums;
     }
-    let allCriteria = [];
-    const simNumsToCriteria = {};
-    Object.entries(numberOfSimsForCriteria).forEach(([criteria, num]) => {
-      for (let i = 0; i <= num; i++) {
-        allCriteria.push(criteria);
-      }
-    });
-    allCriteria = rng.shuffle(allCriteria);
-    for (let i = 1; i <= Math.min(simNums, allCriteria.length); i++) {
-      simNumsToCriteria[i] = allCriteria[i];
-    }
-    return simNumsToCriteria;
+    return numberOfSimsForCriteria;
   }
   /**
    * Checks if core criteria is met, e.g. target multiplier or max win.
@@ -1287,7 +1279,7 @@ function createGameContext(opts) {
 }
 
 // src/book/index.ts
-var Book = class _Book {
+var Book = class {
   id;
   criteria = "N/A";
   events = [];
@@ -1309,7 +1301,11 @@ var Book = class _Book {
    */
   addEvent(event) {
     const index = this.events.length + 1;
-    this.events.push({ index, ...event });
+    this.events.push({
+      index,
+      type: event.type,
+      data: copy(event.data)
+    });
   }
   /**
    * Intended for internal use only.
@@ -1324,17 +1320,6 @@ var Book = class _Book {
       freespinsWins: this.freespinsWins
     };
   }
-  /**
-   * Intended for internal use only.
-   */
-  static fromSerialized(data) {
-    const book = new _Book({ id: data.id, criteria: data.criteria });
-    book.events = data.events;
-    book.payout = data.payout;
-    book.basegameWins = data.basegameWins;
-    book.freespinsWins = data.freespinsWins;
-    return book;
-  }
 };
 
 // src/wallet/index.ts
@@ -1560,6 +1545,107 @@ var Wallet = class {
 
 // src/simulation/index.ts
 import { pipeline } from "stream/promises";
+
+// src/simulation/utils.ts
+import assert6 from "assert";
+function hashStringToInt(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function splitCountsAcrossChunks(totalCounts, chunkSizes) {
+  const total = chunkSizes.reduce((a, b) => a + b, 0);
+  const allCriteria = Object.keys(totalCounts);
+  const totalCountsSum = allCriteria.reduce((s, c) => s + (totalCounts[c] ?? 0), 0);
+  assert6(
+    totalCountsSum === total,
+    `Counts (${totalCountsSum}) must match chunk total (${total}).`
+  );
+  const perChunk = chunkSizes.map(() => ({}));
+  for (const criteria of allCriteria) {
+    const count = totalCounts[criteria] ?? 0;
+    if (count <= 0) {
+      for (let i = 0; i < chunkSizes.length; i++) perChunk[i][criteria] = 0;
+      continue;
+    }
+    let chunks = chunkSizes.map((size) => count * size / total);
+    chunks = chunks.map((x) => Math.floor(x));
+    let assigned = chunks.reduce((a, b) => a + b, 0);
+    let remaining = count - assigned;
+    const remainders = chunks.map((x, i) => ({ i, r: x - Math.floor(x) })).sort((a, b) => b.r - a.r);
+    for (let i = 0; i < chunkSizes.length; i++) {
+      perChunk[i][criteria] = chunks[i];
+    }
+    let idx = 0;
+    while (remaining > 0) {
+      perChunk[remainders[idx].i][criteria] += 1;
+      remaining--;
+      idx = (idx + 1) % remainders.length;
+    }
+  }
+  const chunkTotals = () => perChunk.map((m) => Object.values(m).reduce((s, v) => s + v, 0));
+  let totals = chunkTotals();
+  const getDeficits = () => totals.map((t, i) => chunkSizes[i] - t);
+  let deficits = getDeficits();
+  for (let target = 0; target < chunkSizes.length; target++) {
+    while (deficits[target] > 0) {
+      const src = deficits.findIndex((d) => d < 0);
+      assert6(src !== -1, "No surplus chunk found, but deficits remain.");
+      const crit = allCriteria.find((c) => (perChunk[src][c] ?? 0) > 0);
+      assert6(crit, `No movable criteria found from surplus chunk ${src}.`);
+      perChunk[src][crit] -= 1;
+      perChunk[target][crit] = (perChunk[target][crit] ?? 0) + 1;
+      totals[src] -= 1;
+      totals[target] += 1;
+      deficits[src] += 1;
+      deficits[target] -= 1;
+    }
+  }
+  totals = chunkTotals();
+  for (let i = 0; i < chunkSizes.length; i++) {
+    assert6(
+      totals[i] === chunkSizes[i],
+      `Chunk ${i} size mismatch. Expected ${chunkSizes[i]}, got ${totals[i]}`
+    );
+  }
+  for (const c of allCriteria) {
+    const sum = perChunk.reduce((s, m) => s + (m[c] ?? 0), 0);
+    assert6(sum === (totalCounts[c] ?? 0), `Chunk split mismatch for criteria "${c}"`);
+  }
+  return perChunk;
+}
+function createCriteriaSampler(counts, seed) {
+  const rng = new RandomNumberGenerator();
+  rng.setSeed(seed);
+  const keys = Object.keys(counts).filter((k) => (counts[k] ?? 0) > 0);
+  const remaining = Object.fromEntries(keys.map((k) => [k, counts[k] ?? 0]));
+  let remainingTotal = Object.values(remaining).reduce((a, b) => a + b, 0);
+  return () => {
+    if (remainingTotal <= 0) return "N/A";
+    const roll = Math.min(
+      remainingTotal - Number.EPSILON,
+      rng.randomFloat(0, remainingTotal)
+    );
+    let acc = 0;
+    for (const k of keys) {
+      const w = remaining[k] ?? 0;
+      if (w <= 0) continue;
+      acc += w;
+      if (roll < acc) {
+        remaining[k] = w - 1;
+        remainingTotal--;
+        return k;
+      }
+    }
+    remainingTotal--;
+    return keys.find((k) => (remaining[k] ?? 0) > 0) ?? "N/A";
+  };
+}
+
+// src/simulation/index.ts
 var completedSimulations = 0;
 var TEMP_FILENAME = "__temp_compiled_src_IGNORE.js";
 var TEMP_FOLDER = "temp_files";
@@ -1570,25 +1656,46 @@ var Simulation = class {
   concurrency;
   debug = false;
   actualSims = 0;
-  library;
   wallet;
   recordsWriteStream;
   hasWrittenRecord = false;
+  maxPendingSims;
+  maxHighWaterMark;
+  PATHS = {};
+  // Worker related
+  credits = 0;
+  creditWaiters = [];
+  creditListenerInit = false;
   constructor(opts, gameConfigOpts) {
     this.gameConfig = createGameConfig(gameConfigOpts);
     this.gameConfigOpts = gameConfigOpts;
     this.simRunsAmount = opts.simRunsAmount || {};
     this.concurrency = (opts.concurrency || 6) >= 2 ? opts.concurrency || 6 : 2;
-    this.library = /* @__PURE__ */ new Map();
     this.wallet = new Wallet();
+    this.maxPendingSims = Math.max(10, opts.maxPendingSims ?? 250);
+    this.maxHighWaterMark = (opts.maxDiskBuffer ?? 50) * 1024 * 1024;
     const gameModeKeys = Object.keys(this.gameConfig.gameModes);
-    assert6(
+    assert7(
       Object.values(this.gameConfig.gameModes).map((m) => gameModeKeys.includes(m.name)).every((v) => v === true),
       "Game mode name must match its key in the gameModes object."
     );
-    if (isMainThread) {
-      this.preprocessFiles();
-    }
+    this.PATHS.base = path.join(this.gameConfig.rootDir, this.gameConfig.outputDir);
+    this.PATHS = {
+      ...this.PATHS,
+      books: (mode) => path.join(this.PATHS.base, `books_${mode}.jsonl`),
+      booksCompressed: (mode) => path.join(this.PATHS.base, "publish_files", `books_${mode}.jsonl.zst`),
+      tempBooks: (mode, i) => path.join(this.PATHS.base, TEMP_FOLDER, `temp_books_${mode}_${i}.jsonl`),
+      lookupTable: (mode) => path.join(this.PATHS.base, `lookUpTable_${mode}.csv`),
+      tempLookupTable: (mode, i) => path.join(this.PATHS.base, TEMP_FOLDER, `temp_lookup_${mode}_${i}.csv`),
+      lookupTableSegmented: (mode) => path.join(this.PATHS.base, `lookUpTableSegmented_${mode}.csv`),
+      tempLookupTableSegmented: (mode, i) => path.join(this.PATHS.base, TEMP_FOLDER, `temp_lookup_segmented_${mode}_${i}.csv`),
+      lookupTablePublish: (mode) => path.join(this.PATHS.base, "publish_files", `lookUpTable_${mode}_0.csv`),
+      tempRecords: (mode) => path.join(this.PATHS.base, TEMP_FOLDER, `temp_records_${mode}.jsonl`),
+      forceRecords: (mode) => path.join(this.PATHS.base, `force_record_${mode}.json`),
+      indexJson: path.join(this.PATHS.base, "publish_files", "index.json"),
+      optimizationFiles: path.join(this.PATHS.base, "optimization_files"),
+      publishFiles: path.join(this.PATHS.base, "publish_files")
+    };
   }
   async runSimulation(opts) {
     const debug = opts.debug || false;
@@ -1600,11 +1707,11 @@ var Simulation = class {
     }
     this.generateReelsetFiles();
     if (isMainThread) {
+      this.preprocessFiles();
       const debugDetails = {};
       for (const mode of gameModesToSimulate) {
         completedSimulations = 0;
         this.wallet = new Wallet();
-        this.library = /* @__PURE__ */ new Map();
         this.hasWrittenRecord = false;
         debugDetails[mode] = {};
         console.log(`
@@ -1617,37 +1724,37 @@ Simulating game mode: ${mode}`);
             `Tried to simulate game mode "${mode}", but it's not configured in the game config.`
           );
         }
-        const booksPath = path.join(
-          this.gameConfig.rootDir,
-          this.gameConfig.outputDir,
-          `books_${mode}.jsonl`
-        );
-        const tempRecordsPath = path.join(
-          this.gameConfig.rootDir,
-          this.gameConfig.outputDir,
-          TEMP_FOLDER,
-          `temp_records_${mode}.jsonl`
-        );
-        createDirIfNotExists(
-          path.join(this.gameConfig.rootDir, this.gameConfig.outputDir)
+        const booksPath = this.PATHS.books(mode);
+        const tempRecordsPath = this.PATHS.tempRecords(mode);
+        createDirIfNotExists(this.PATHS.base);
+        createDirIfNotExists(path.join(this.PATHS.base, TEMP_FOLDER));
+        this.recordsWriteStream = fs2.createWriteStream(tempRecordsPath, {
+          highWaterMark: this.maxHighWaterMark
+        }).setMaxListeners(30);
+        const criteriaCounts = ResultSet.getNumberOfSimsForCriteria(this, mode);
+        const totalSims = Object.values(criteriaCounts).reduce((a, b) => a + b, 0);
+        assert7(
+          totalSims === runs,
+          `Criteria mismatch for mode "${mode}". Expected ${runs}, got ${totalSims}`
         );
-        createDirIfNotExists(
-          path.join(this.gameConfig.rootDir, this.gameConfig.outputDir, TEMP_FOLDER)
+        const chunks = this.getSimRangesForChunks(totalSims, this.concurrency);
+        const chunkSizes = chunks.map(([s, e]) => Math.max(0, e - s + 1));
+        const chunkCriteriaCounts = splitCountsAcrossChunks(criteriaCounts, chunkSizes);
+        await this.spawnWorkersForGameMode({
+          mode,
+          chunks,
+          chunkCriteriaCounts,
+          totalSims
+        });
+        createDirIfNotExists(this.PATHS.optimizationFiles);
+        createDirIfNotExists(this.PATHS.publishFiles);
+        console.log(
+          `Writing final files for game mode "${mode}". This may take a while...`
         );
-        this.recordsWriteStream = fs2.createWriteStream(tempRecordsPath);
-        const simNumsToCriteria = ResultSet.assignCriteriaToSimulations(this, mode);
-        await this.spawnWorkersForGameMode({ mode, simNumsToCriteria });
         const finalBookStream = fs2.createWriteStream(booksPath);
-        const numSims = Object.keys(simNumsToCriteria).length;
-        const chunks = this.getSimRangesForChunks(numSims, this.concurrency);
         let isFirstChunk = true;
         for (let i = 0; i < chunks.length; i++) {
-          const tempBookPath = path.join(
-            this.gameConfig.rootDir,
-            this.gameConfig.outputDir,
-            TEMP_FOLDER,
-            `temp_books_${mode}_${i}.jsonl`
-          );
+          const tempBookPath = this.PATHS.tempBooks(mode, i);
           if (fs2.existsSync(tempBookPath)) {
             if (!isFirstChunk) {
               finalBookStream.write("\n");
@@ -1662,6 +1769,16 @@ Simulating game mode: ${mode}`);
         }
         finalBookStream.end();
         await new Promise((resolve) => finalBookStream.on("finish", resolve));
+        const lutPath = this.PATHS.lookupTable(mode);
+        const lutPathPublish = this.PATHS.lookupTablePublish(mode);
+        const lutSegmentedPath = this.PATHS.lookupTableSegmented(mode);
+        await this.mergeCsv(chunks, lutPath, (i) => `temp_lookup_${mode}_${i}.csv`);
+        fs2.copyFileSync(lutPath, lutPathPublish);
+        await this.mergeCsv(
+          chunks,
+          lutSegmentedPath,
+          (i) => `temp_lookup_segmented_${mode}_${i}.csv`
+        );
         if (this.recordsWriteStream) {
           await new Promise((resolve) => {
             this.recordsWriteStream.end(() => {
@@ -1670,26 +1787,21 @@ Simulating game mode: ${mode}`);
           });
           this.recordsWriteStream = void 0;
         }
-        createDirIfNotExists(
-          path.join(
-            this.gameConfig.rootDir,
-            this.gameConfig.outputDir,
-            "optimization_files"
-          )
-        );
-        createDirIfNotExists(
-          path.join(this.gameConfig.rootDir, this.gameConfig.outputDir, "publish_files")
-        );
-        console.log(`Writing final files for game mode: ${mode} ...`);
-        this.writeLookupTableCSV(mode);
-        this.writeLookupTableSegmentedCSV(mode);
-        this.writeRecords(mode);
+        await this.writeRecords(mode);
         await this.writeBooksJson(mode);
         this.writeIndexJson();
         console.log(`Mode ${mode} done!`);
-        debugDetails[mode].rtp = this.wallet.getCumulativeWins() / (runs * this.gameConfig.gameModes[mode].cost);
-        debugDetails[mode].wins = this.wallet.getCumulativeWins();
-        debugDetails[mode].winsPerSpinType = this.wallet.getCumulativeWinsPerSpinType();
+        debugDetails[mode].rtp = round(
+          this.wallet.getCumulativeWins() / (runs * this.gameConfig.gameModes[mode].cost),
+          3
+        );
+        debugDetails[mode].wins = round(this.wallet.getCumulativeWins(), 3);
+        debugDetails[mode].winsPerSpinType = Object.fromEntries(
+          Object.entries(this.wallet.getCumulativeWinsPerSpinType()).map(([k, v]) => [
+            k,
+            round(v, 3)
+          ])
+        );
         console.timeEnd(mode);
       }
       console.log("\n=== SIMULATION SUMMARY ===");
@@ -1699,14 +1811,14 @@ Simulating game mode: ${mode}`);
     let actualSims = 0;
     const criteriaToRetries = {};
     if (!isMainThread) {
-      const { mode, simStart, simEnd, index } = workerData;
-      const simNumsToCriteria = ResultSet.assignCriteriaToSimulations(this, mode);
+      const { mode, simStart, simEnd, index, criteriaCounts } = workerData;
+      const seed = hashStringToInt(mode) + index >>> 0;
+      const nextCriteria = createCriteriaSampler(criteriaCounts, seed);
       for (let simId = simStart; simId <= simEnd; simId++) {
         if (this.debug) desiredSims++;
-        const criteria = simNumsToCriteria[simId] || "N/A";
-        if (!criteriaToRetries[criteria]) {
-          criteriaToRetries[criteria] = 0;
-        }
+        const criteria = nextCriteria();
+        if (!criteriaToRetries[criteria]) criteriaToRetries[criteria] = 0;
+        await this.acquireCredit();
         this.runSingleSimulation({ simId, mode, criteria, index });
         if (this.debug) {
           criteriaToRetries[criteria] += this.actualSims - 1;
@@ -1721,30 +1833,31 @@ Simulating game mode: ${mode}`);
         type: "done",
         workerNum: index
       });
+      parentPort?.removeAllListeners();
+      parentPort?.close();
     }
   }
   /**
    * Runs all simulations for a specific game mode.
    */
   async spawnWorkersForGameMode(opts) {
-    const { mode, simNumsToCriteria } = opts;
-    const numSims = Object.keys(simNumsToCriteria).length;
-    const simRangesPerChunk = this.getSimRangesForChunks(numSims, this.concurrency);
+    const { mode, chunks, chunkCriteriaCounts, totalSims } = opts;
     await Promise.all(
-      simRangesPerChunk.map(([simStart, simEnd], index) => {
+      chunks.map(([simStart, simEnd], index) => {
         return this.callWorker({
-          basePath: path.join(this.gameConfig.rootDir, this.gameConfig.outputDir),
+          basePath: this.PATHS.base,
           mode,
           simStart,
           simEnd,
           index,
-          totalSims: numSims
+          totalSims,
+          criteriaCounts: chunkCriteriaCounts[index]
         });
       })
     );
   }
   async callWorker(opts) {
-    const { mode, simEnd, simStart, basePath, index, totalSims } = opts;
+    const { mode, simEnd, simStart, basePath, index, totalSims, criteriaCounts } = opts;
     function logArrowProgress(current, total) {
       const percentage = current / total * 100;
       const progressBarLength = 50;
@@ -1755,6 +1868,11 @@ Simulating game mode: ${mode}`);
         process.stdout.write("\n");
       }
     }
+    const write = async (stream, chunk) => {
+      if (!stream.write(chunk)) {
+        await new Promise((resolve) => stream.once("drain", resolve));
+      }
+    };
     return new Promise((resolve, reject) => {
       const scriptPath = path.join(basePath, TEMP_FILENAME);
       const worker = new Worker(scriptPath, {
@@ -1762,42 +1880,77 @@ Simulating game mode: ${mode}`);
           mode,
           simStart,
           simEnd,
-          index
+          index,
+          criteriaCounts
         }
       });
-      const tempBookPath = path.join(
-        basePath,
-        TEMP_FOLDER,
-        `temp_books_${mode}_${index}.jsonl`
-      );
-      const bookStream = fs2.createWriteStream(tempBookPath);
+      worker.postMessage({ type: "credit", amount: this.maxPendingSims });
+      const tempBookPath = this.PATHS.tempBooks(mode, index);
+      const bookStream = fs2.createWriteStream(tempBookPath, {
+        highWaterMark: this.maxHighWaterMark
+      });
+      const tempLookupPath = this.PATHS.tempLookupTable(mode, index);
+      const lookupStream = fs2.createWriteStream(tempLookupPath, {
+        highWaterMark: this.maxHighWaterMark
+      });
+      const tempLookupSegPath = this.PATHS.tempLookupTableSegmented(mode, index);
+      const lookupSegmentedStream = fs2.createWriteStream(tempLookupSegPath, {
+        highWaterMark: this.maxHighWaterMark
+      });
+      let writeChain = Promise.resolve();
       worker.on("message", (msg) => {
         if (msg.type === "log") {
-        } else if (msg.type === "complete") {
-          completedSimulations++;
-          if (completedSimulations % 250 === 0) {
-            logArrowProgress(completedSimulations, totalSims);
-          }
-          const book = Book.fromSerialized(msg.book);
-          const bookData = {
-            id: book.id,
-            payoutMultiplier: book.payout,
-            events: book.events
-          };
-          const prefix = book.id === simStart ? "" : "\n";
-          bookStream.write(prefix + JSONL.stringify([bookData]));
-          book.events = [];
-          this.library.set(book.id, book);
-          if (this.recordsWriteStream) {
-            for (const record of msg.records) {
-              const recordPrefix = this.hasWrittenRecord ? "\n" : "";
-              this.recordsWriteStream.write(recordPrefix + JSONL.stringify([record]));
-              this.hasWrittenRecord = true;
+          return;
+        }
+        if (msg.type === "complete") {
+          writeChain = writeChain.then(async () => {
+            completedSimulations++;
+            if (completedSimulations % 250 === 0) {
+              logArrowProgress(completedSimulations, totalSims);
             }
-          }
-          this.wallet.mergeSerialized(msg.wallet);
-        } else if (msg.type === "done") {
-          resolve(true);
+            const book = msg.book;
+            const bookData = {
+              id: book.id,
+              payoutMultiplier: book.payout,
+              events: book.events
+            };
+            const prefix = book.id === simStart ? "" : "\n";
+            await write(bookStream, prefix + JSONL.stringify([bookData]));
+            await write(lookupStream, `${book.id},1,${Math.round(book.payout)}
+`);
+            await write(
+              lookupSegmentedStream,
+              `${book.id},${book.criteria},${book.basegameWins},${book.freespinsWins}
+`
+            );
+            if (this.recordsWriteStream) {
+              for (const record of msg.records) {
+                const recordPrefix = this.hasWrittenRecord ? "\n" : "";
+                await write(
+                  this.recordsWriteStream,
+                  recordPrefix + JSONL.stringify([record])
+                );
+                this.hasWrittenRecord = true;
+              }
+            }
+            this.wallet.mergeSerialized(msg.wallet);
+            worker.postMessage({ type: "credit", amount: 1 });
+          }).catch(reject);
+          return;
+        }
+        if (msg.type === "done") {
+          writeChain.then(async () => {
+            bookStream.end();
+            lookupStream.end();
+            lookupSegmentedStream.end();
+            await Promise.all([
+              new Promise((r) => bookStream.on("finish", () => r())),
+              new Promise((r) => lookupStream.on("finish", () => r())),
+              new Promise((r) => lookupSegmentedStream.on("finish", () => r()))
+            ]);
+            resolve(true);
+          }).catch(reject);
+          return;
         }
       });
       worker.on("error", (error) => {
@@ -1858,6 +2011,31 @@ ${error.stack}
       records: ctx.services.data._getRecords()
     });
   }
+  initCreditListener() {
+    if (this.creditListenerInit) return;
+    this.creditListenerInit = true;
+    parentPort?.on("message", (msg) => {
+      if (msg?.type !== "credit") return;
+      const amount = Number(msg?.amount ?? 0);
+      if (!Number.isFinite(amount) || amount <= 0) return;
+      this.credits += amount;
+      while (this.credits > 0 && this.creditWaiters.length > 0) {
+        this.credits -= 1;
+        const resolve = this.creditWaiters.shift();
+        resolve();
+      }
+    });
+  }
+  acquireCredit() {
+    this.initCreditListener();
+    if (this.credits > 0) {
+      this.credits -= 1;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.creditWaiters.push(resolve);
+    });
+  }
   /**
    * If a simulation does not meet the required criteria, reset the state to run it again.
    *
@@ -1885,7 +2063,7 @@ ${error.stack}
     ctx.state.totalFreespinAmount = 0;
     ctx.state.triggeredMaxWin = false;
     ctx.state.triggeredFreespins = false;
-    ctx.state.userData = ctx.config.userState || {};
+    ctx.state.userData = copy(ctx.config.userState);
   }
   /**
    * Contains and executes the entire game logic:
@@ -1900,64 +2078,9 @@ ${error.stack}
   handleGameFlow(ctx) {
     this.gameConfig.hooks.onHandleGameFlow(ctx);
   }
-  /**
-   * Creates a CSV file in the format "simulationId,weight,payout".
-   *
-   * `weight` defaults to 1.
-   */
-  writeLookupTableCSV(gameMode) {
-    const rows = [];
-    for (const [bookId, book] of this.library.entries()) {
-      rows.push(`${book.id},1,${Math.round(book.payout)}`);
-    }
-    rows.sort((a, b) => Number(a.split(",")[0]) - Number(b.split(",")[0]));
-    let outputFileName = `lookUpTable_${gameMode}.csv`;
-    let outputFilePath = path.join(
-      this.gameConfig.rootDir,
-      this.gameConfig.outputDir,
-      outputFileName
-    );
-    writeFile(outputFilePath, rows.join("\n"));
-    outputFileName = `lookUpTable_${gameMode}_0.csv`;
-    outputFilePath = path.join(
-      this.gameConfig.rootDir,
-      this.gameConfig.outputDir,
-      "publish_files",
-      outputFileName
-    );
-    writeFile(outputFilePath, rows.join("\n"));
-    return outputFilePath;
-  }
-  /**
-   * Creates a CSV file in the format "simulationId,criteria,payoutBase,payoutFreespins".
-   */
-  writeLookupTableSegmentedCSV(gameMode) {
-    const rows = [];
-    for (const [bookId, book] of this.library.entries()) {
-      rows.push(`${book.id},${book.criteria},${book.basegameWins},${book.freespinsWins}`);
-    }
-    rows.sort((a, b) => Number(a.split(",")[0]) - Number(b.split(",")[0]));
-    const outputFileName = `lookUpTableSegmented_${gameMode}.csv`;
-    const outputFilePath = path.join(
-      this.gameConfig.rootDir,
-      this.gameConfig.outputDir,
-      outputFileName
-    );
-    writeFile(outputFilePath, rows.join("\n"));
-    return outputFilePath;
-  }
   async writeRecords(mode) {
-    const tempRecordsPath = path.join(
-      this.gameConfig.rootDir,
-      this.gameConfig.outputDir,
-      TEMP_FOLDER,
-      `temp_records_${mode}.jsonl`
-    );
-    const forceRecordsPath = path.join(
-      this.gameConfig.rootDir,
-      this.gameConfig.outputDir,
-      `force_record_${mode}.json`
-    );
+    const tempRecordsPath = this.PATHS.tempRecords(mode);
+    const forceRecordsPath = this.PATHS.forceRecords(mode);
     const aggregatedRecords = /* @__PURE__ */ new Map();
     if (fs2.existsSync(tempRecordsPath)) {
       const fileStream = fs2.createReadStream(tempRecordsPath);
@@ -2003,15 +2126,10 @@ ${error.stack}
     fs2.rmSync(tempRecordsPath, { force: true });
   }
   writeIndexJson() {
-    const outputFilePath = path.join(
-      this.gameConfig.rootDir,
-      this.gameConfig.outputDir,
-      "publish_files",
-      "index.json"
-    );
+    const outputFilePath = this.PATHS.indexJson;
     const modes = Object.keys(this.simRunsAmount).map((id) => {
       const mode = this.gameConfig.gameModes[id];
-      assert6(mode, `Game mode "${id}" not found in game config.`);
+      assert7(mode, `Game mode "${id}" not found in game config.`);
       return {
         name: mode.name,
         cost: mode.cost,
@@ -2022,17 +2140,8 @@ ${error.stack}
     writeFile(outputFilePath, JSON.stringify({ modes }, null, 2));
   }
   async writeBooksJson(gameMode) {
-    const outputFilePath = path.join(
-      this.gameConfig.rootDir,
-      this.gameConfig.outputDir,
-      `books_${gameMode}.jsonl`
-    );
-    const compressedFilePath = path.join(
-      this.gameConfig.rootDir,
-      this.gameConfig.outputDir,
-      "publish_files",
-      `books_${gameMode}.jsonl.zst`
-    );
+    const outputFilePath = this.PATHS.books(gameMode);
+    const compressedFilePath = this.PATHS.booksCompressed(gameMode);
     fs2.rmSync(compressedFilePath, { force: true });
     if (fs2.existsSync(outputFilePath)) {
       await pipeline(
@@ -2065,11 +2174,12 @@ ${error.stack}
     });
   }
   getSimRangesForChunks(total, chunks) {
-    const base = Math.floor(total / chunks);
-    const remainder = total % chunks;
+    const realChunks = Math.min(chunks, Math.max(total, 1));
+    const base = Math.floor(total / realChunks);
+    const remainder = total % realChunks;
     const result = [];
     let current = 1;
-    for (let i = 0; i < chunks; i++) {
+    for (let i = 0; i < realChunks; i++) {
       const size = base + (i < remainder ? 1 : 0);
       const start = current;
       const end = current + size - 1;
@@ -2095,6 +2205,22 @@ ${error.stack}
       }
     }
   }
+  async mergeCsv(chunks, outPath, tempName) {
+    fs2.rmSync(outPath, { force: true });
+    const out = fs2.createWriteStream(outPath);
+    let wroteAny = false;
+    for (let i = 0; i < chunks.length; i++) {
+      const p = path.join(this.PATHS.base, TEMP_FOLDER, tempName(i));
+      if (!fs2.existsSync(p)) continue;
+      if (wroteAny) out.write("");
+      const rs = fs2.createReadStream(p);
+      for await (const buf of rs) out.write(buf);
+      fs2.rmSync(p);
+      wroteAny = true;
+    }
+    out.end();
+    await new Promise((resolve) => out.on("finish", resolve));
+  }
   /**
    * Confirms all pending records and adds them to the main records list.
    */
@@ -2130,7 +2256,7 @@ ${error.stack}
 // src/analysis/index.ts
 import fs3 from "fs";
 import path2 from "path";
-import assert7 from "assert";
+import assert8 from "assert";
 
 // src/analysis/utils.ts
 function parseLookupTable(content) {
@@ -2307,7 +2433,7 @@ var Analysis = class {
         booksJsonlCompressed
       };
       for (const p of Object.values(paths[modeStr])) {
-        assert7(
+        assert8(
           fs3.existsSync(p),
           `File "${p}" does not exist. Run optimization to auto-create it.`
         );
@@ -2429,14 +2555,14 @@ var Analysis = class {
   }
   getGameModeConfig(mode) {
     const config = this.gameConfig.gameModes[mode];
-    assert7(config, `Game mode "${mode}" not found in game config`);
+    assert8(config, `Game mode "${mode}" not found in game config`);
     return config;
   }
 };
 
 // src/optimizer/index.ts
 import path5 from "path";
-import assert9 from "assert";
+import assert10 from "assert";
 import { spawn } from "child_process";
 import { isMainThread as isMainThread3 } from "worker_threads";
 
@@ -2537,7 +2663,7 @@ function makeSetupFile(optimizer, gameMode) {
 }
 
 // src/optimizer/OptimizationConditions.ts
-import assert8 from "assert";
+import assert9 from "assert";
 var OptimizationConditions = class {
   rtp;
   avgWin;
@@ -2548,14 +2674,14 @@ var OptimizationConditions = class {
   constructor(opts) {
     let { rtp, avgWin, hitRate, searchConditions, priority } = opts;
     if (rtp == void 0 || rtp === "x") {
-      assert8(avgWin !== void 0 && hitRate !== void 0, "If RTP is not specified, hit-rate (hr) and average win amount (av_win) must be given.");
+      assert9(avgWin !== void 0 && hitRate !== void 0, "If RTP is not specified, hit-rate (hr) and average win amount (av_win) must be given.");
       rtp = Math.round(avgWin / Number(hitRate) * 1e5) / 1e5;
     }
     let noneCount = 0;
     for (const val of [rtp, avgWin, hitRate]) {
       if (val === void 0) noneCount++;
     }
-    assert8(noneCount <= 1, "Invalid combination of optimization conditions.");
+    assert9(noneCount <= 1, "Invalid combination of optimization conditions.");
     this.searchRange = [-1, -1];
     this.forceSearch = {};
     if (typeof searchConditions === "number") {
@@ -2683,7 +2809,7 @@ var Optimizer = class {
       }
       gameModeRtp = Math.round(gameModeRtp * 1e3) / 1e3;
       paramRtp = Math.round(paramRtp * 1e3) / 1e3;
-      assert9(
+      assert10(
         gameModeRtp === paramRtp,
         `Sum of all RTP conditions (${paramRtp}) does not match the game mode RTP (${gameModeRtp}) in game mode "${k}".`
       );
@@ -2822,7 +2948,7 @@ var defineSymbols = (symbols) => symbols;
 var defineGameModes = (gameModes) => gameModes;
 
 // src/game-mode/index.ts
-import assert10 from "assert";
+import assert11 from "assert";
 var GameMode = class {
   name;
   _reelsAmount;
@@ -2845,12 +2971,12 @@ var GameMode = class {
     this.reelSets = opts.reelSets;
     this.resultSets = opts.resultSets;
     this.isBonusBuy = opts.isBonusBuy;
-    assert10(this.rtp >= 0.9 && this.rtp <= 0.99, "RTP must be between 0.9 and 0.99");
-    assert10(
+    assert11(this.rtp >= 0.9 && this.rtp <= 0.99, "RTP must be between 0.9 and 0.99");
+    assert11(
       this.symbolsPerReel.length === this.reelsAmount,
       "symbolsPerReel length must match reelsAmount."
     );
-    assert10(this.reelSets.length > 0, "GameMode must have at least one ReelSet defined.");
+    assert11(this.reelSets.length > 0, "GameMode must have at least one ReelSet defined.");
   }
   /**
    * Intended for internal use only.
@@ -2863,7 +2989,7 @@ var GameMode = class {
    * Intended for internal use only.
    */
   _setSymbolsPerReel(symbolsPerReel) {
-    assert10(
+    assert11(
       symbolsPerReel.length === this._reelsAmount,
       "symbolsPerReel length must match reelsAmount."
     );
@@ -2929,7 +3055,7 @@ var WinType = class {
 };
 
 // src/win-types/LinesWinType.ts
-import assert11 from "assert";
+import assert12 from "assert";
 var LinesWinType = class extends WinType {
   lines;
   constructor(opts) {
@@ -2983,8 +3109,8 @@ var LinesWinType = class extends WinType {
         if (!baseSymbol) {
           baseSymbol = thisSymbol;
         }
-        assert11(baseSymbol, `No symbol found at line ${lineNum}, reel ${ridx}`);
-        assert11(thisSymbol, `No symbol found at line ${lineNum}, reel ${ridx}`);
+        assert12(baseSymbol, `No symbol found at line ${lineNum}, reel ${ridx}`);
+        assert12(thisSymbol, `No symbol found at line ${lineNum}, reel ${ridx}`);
         if (potentialWinLine.length == 0) {
           if (this.isWild(thisSymbol)) {
             potentialWildLine.push({ reel: ridx, row: sidx, symbol: thisSymbol });
@@ -3653,7 +3779,7 @@ var GeneratedReelSet = class extends ReelSet {
 };
 
 // src/reel-set/StaticReelSet.ts
-import assert12 from "assert";
+import assert13 from "assert";
 var StaticReelSet = class extends ReelSet {
   reels;
   csvPath;
@@ -3663,7 +3789,7 @@ var StaticReelSet = class extends ReelSet {
     this.reels = [];
     this._strReels = opts.reels || [];
     this.csvPath = opts.csvPath || "";
-    assert12(
+    assert13(
       opts.reels || opts.csvPath,
       `Either 'reels' or 'csvPath' must be provided for StaticReelSet ${this.id}`
     );