@slot-engine/core 0.0.1

package/src/analysis/utils.ts

@@ -0,0 +1,128 @@
+export function parseLookupTable(content: string) {
+  const lines = content.trim().split("\n")
+  const lut: LookupTable = []
+  for (const line of lines) {
+    const [indexStr, weightStr, payoutStr] = line.split(",")
+    const index = parseInt(indexStr!.trim())
+    const weight = parseInt(weightStr!.trim())
+    const payout = parseFloat(payoutStr!.trim())
+    lut.push([index, weight, payout])
+  }
+  return lut
+}
+
+export type LookupTable = [number, number, number][]
+
+export function getTotalLutWeight(lut: LookupTable) {
+  return lut.reduce((sum, [, weight]) => sum + weight, 0)
+}
+
+export function getTotalWeight(payoutWeights: PayoutWeights) {
+  return Object.values(payoutWeights).reduce((sum, w) => sum + w, 0)
+}
+
+type PayoutWeights = Record<number, number>
+
+export function getPayoutWeights(
+  lut: LookupTable,
+  opts: { normalize?: boolean } = {},
+): PayoutWeights {
+  const { normalize = true } = opts
+  const totalWeight = getTotalLutWeight(lut)
+
+  let payoutWeights: Record<number, number> = {}
+
+  for (const [, weight, p] of lut) {
+    const payout = p / 100
+    if (payoutWeights[payout] === undefined) {
+      payoutWeights[payout] = 0
+    }
+    payoutWeights[payout] += weight
+  }
+
+  // Sort by payout value
+  payoutWeights = Object.fromEntries(
+    Object.entries(payoutWeights).sort(([a], [b]) => parseFloat(a) - parseFloat(b)),
+  )
+
+  if (normalize) {
+    for (const payout in payoutWeights) {
+      payoutWeights[payout]! /= totalWeight
+    }
+  }
+
+  return payoutWeights
+}
+
+export function getNonZeroHitrate(payoutWeights: PayoutWeights) {
+  const totalWeight = getTotalWeight(payoutWeights)
+  const nonZeroWeight = totalWeight - (payoutWeights[0] ?? 0) * totalWeight
+  return nonZeroWeight / totalWeight
+}
+
+export function getNullHitrate(payoutWeights: PayoutWeights) {
+  return payoutWeights[0] ?? 0
+}
+
+export function getMaxwinHitrate(payoutWeights: PayoutWeights) {
+  const totalWeight = getTotalWeight(payoutWeights)
+  const maxWin = Math.max(...Object.keys(payoutWeights).map(Number))
+  const hitRate = (payoutWeights[maxWin] || 0) / totalWeight
+  return 1 / hitRate
+}
+
+export function getUniquePayouts(payoutWeights: PayoutWeights) {
+  return Object.keys(payoutWeights).length
+}
+
+export function getMinWin(payoutWeights: PayoutWeights) {
+  const payouts = Object.keys(payoutWeights).map(Number)
+  return Math.min(...payouts)
+}
+
+export function getMaxWin(payoutWeights: PayoutWeights) {
+  const payouts = Object.keys(payoutWeights).map(Number)
+  return Math.max(...payouts)
+}
+
+export function getAvgWin(payoutWeights: PayoutWeights) {
+  let avgWin = 0
+  for (const [payoutStr, weight] of Object.entries(payoutWeights)) {
+    const payout = parseFloat(payoutStr)
+    avgWin += payout * weight
+  }
+  return avgWin
+}
+
+export function getRtp(payoutWeights: PayoutWeights, cost: number) {
+  const avgWin = getAvgWin(payoutWeights)
+  return avgWin / cost
+}
+
+export function getStandardDeviation(payoutWeights: PayoutWeights) {
+  const variance = getVariance(payoutWeights)
+  return Math.sqrt(variance)
+}
+
+export function getVariance(payoutWeights: PayoutWeights) {
+  const totalWeight = getTotalWeight(payoutWeights)
+  const avgWin = getAvgWin(payoutWeights)
+  let variance = 0
+  for (const [payoutStr, weight] of Object.entries(payoutWeights)) {
+    const payout = parseFloat(payoutStr)
+    variance += Math.pow(payout - avgWin, 2) * (weight / totalWeight)
+  }
+  return variance
+}
+
+export function getLessBetHitrate(payoutWeights: PayoutWeights, cost: number) {
+  let lessBetWeight = 0
+  const totalWeight = getTotalWeight(payoutWeights)
+  for (const [payoutStr, weight] of Object.entries(payoutWeights)) {
+    const payout = parseFloat(payoutStr)
+    if (payout < cost) {
+      lessBetWeight += weight
+    }
+  }
+  return lessBetWeight / totalWeight
+}

package/src/optimizer/OptimizationConditions.ts

@@ -0,0 +1,99 @@
+import assert from "assert"
+
+export 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) {
+    let { rtp, avgWin, hitRate, searchConditions, priority } = opts
+
+    if (rtp == undefined || rtp === "x") {
+      assert(avgWin !== undefined && hitRate !== undefined, "If RTP is not specified, hit-rate (hr) and average win amount (av_win) must be given.")
+      rtp = Math.round((avgWin! / Number(hitRate)) * 100000) / 100000
+    }
+
+    let noneCount = 0
+    for (const val of [rtp, avgWin, hitRate]) {
+      if (val === undefined) noneCount++
+    }
+    assert(noneCount <= 1, "Invalid combination of optimization conditions.")
+
+    this.searchRange = [-1, -1]
+    this.forceSearch = {}
+
+    if (typeof searchConditions === "number") {
+      this.searchRange = [searchConditions, searchConditions]
+    }
+    if (Array.isArray(searchConditions)) {
+      if (searchConditions[0] > searchConditions[1] || searchConditions.length !== 2) {
+        throw new Error("Invalid searchConditions range.")
+      }
+      this.searchRange = searchConditions
+    }
+    if (typeof searchConditions === "object" && !Array.isArray(searchConditions)) {
+      this.searchRange = [-1, -1]
+      this.forceSearch = searchConditions
+    }
+
+    this.rtp = rtp
+    this.avgWin = avgWin
+    this.hitRate = hitRate
+    this.priority = priority
+  }
+
+  getRtp() {
+    return this.rtp
+  }
+
+  getAvgWin() {
+    return this.avgWin
+  }
+
+  getHitRate() {
+    return this.hitRate
+  }
+
+  getSearchRange() {
+    return this.searchRange
+  }
+
+  getForceSearch() {
+    return this.forceSearch
+  }
+}
+
+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
+}

package/src/optimizer/OptimizationParameters.ts

@@ -0,0 +1,46 @@
+export class OptimizationParameters {
+  protected parameters: OptimizationParametersOpts
+
+  constructor(opts?: OptimizationParametersOpts) {
+    this.parameters = {
+      ...OptimizationParameters.DEFAULT_PARAMETERS,
+      ...opts,
+    }
+  }
+
+  static DEFAULT_PARAMETERS: OptimizationParametersOpts = {
+    numShowPigs: 5000,
+    numPigsPerFence: 10000,
+    threadsFenceConstruction: 16,
+    threadsShowConstruction: 16,
+    testSpins: [50, 100, 200],
+    testSpinsWeights: [0.3, 0.4, 0.3],
+    simulationTrials: 5000,
+    graphIndexes: [],
+    run1000Batch: false,
+    minMeanToMedian: 4,
+    maxMeanToMedian: 8,
+    pmbRtp: 1.0,
+    scoreType: "rtp",
+  }
+
+  getParameters() {
+    return this.parameters
+  }
+}
+
+export interface OptimizationParametersOpts {
+  readonly numShowPigs: number
+  readonly numPigsPerFence: number
+  readonly threadsFenceConstruction: number
+  readonly threadsShowConstruction: number
+  readonly testSpins: number[]
+  readonly testSpinsWeights: number[]
+  readonly simulationTrials: number
+  readonly graphIndexes: number[]
+  readonly run1000Batch: false
+  readonly minMeanToMedian: number
+  readonly maxMeanToMedian: number
+  readonly pmbRtp: number
+  readonly scoreType: "rtp"
+}

package/src/optimizer/OptimizationScaling.ts

@@ -0,0 +1,18 @@
+export class OptimizationScaling {
+  protected config: OptimizationScalingOpts
+
+  constructor(opts: OptimizationScalingOpts) {
+    this.config = opts
+  }
+
+  getConfig() {
+    return this.config
+  }
+}
+
+type OptimizationScalingOpts = Array<{
+  criteria: string
+  scaleFactor: number
+  winRange: [number, number]
+  probability: number
+}>

package/src/optimizer/index.ts

@@ -0,0 +1,142 @@
+import { GameConfig, OptimizationConditions, OptimizationScaling } from "../../index"
+import { GameModeName } from "../GameMode"
+import { OptimizationParameters } from "./OptimizationParameters"
+import { makeMathConfig } from "../utils/math-config"
+import { makeSetupFile } from "../utils/setup-file"
+import { spawn } from "child_process"
+import path from "path"
+import { Analysis } from "../analysis"
+import assert from "assert"
+import { isMainThread } from "worker_threads"
+import { SlotGame } from "../SlotGame"
+
+export class Optimizer {
+  protected readonly gameConfig: GameConfig["config"]
+  protected readonly gameModes: OptimzierGameModeConfig
+
+  constructor(opts: OptimizerOpts) {
+    this.gameConfig = opts.game.getConfig().config
+    this.gameModes = opts.gameModes
+
+    this.verifyConfig()
+  }
+
+  /**
+   * Runs the optimization process, and runs analysis after.
+   */
+  async runOptimization({ gameModes }: OptimizationOpts) {
+    if (!isMainThread) return // IMPORTANT: Prevent workers from kicking off (multiple) optimizations
+
+    const mathConfig = makeMathConfig(this, { writeToFile: true })
+
+    for (const mode of gameModes) {
+      const setupFile = makeSetupFile(this, mode)
+      await this.runSingleOptimization()
+    }
+  }
+
+  private async runSingleOptimization() {
+    return await rustProgram()
+  }
+
+  private verifyConfig() {
+    for (const [k, mode] of Object.entries(this.gameModes)) {
+      const configMode = this.gameConfig.gameModes[k]
+
+      if (!configMode) {
+        throw new Error(
+          `Game mode "${mode}" defined in optimizer config does not exist in the game config.`,
+        )
+      }
+
+      const conditions = Object.keys(mode.conditions)
+      const scalings = Object.keys(mode.scaling)
+      const parameters = Object.keys(mode.parameters)
+
+      for (const condition of conditions) {
+        if (!configMode.resultSets.find((r) => r.criteria === condition)) {
+          throw new Error(
+            `Condition "${condition}" defined in optimizer config for game mode "${k}" does not exist as criteria in any ResultSet of the same game mode.`,
+          )
+        }
+      }
+
+      const criteria = configMode.resultSets.map((r) => r.criteria)
+      assert(
+        conditions.every((c) => criteria.includes(c)),
+        `Not all ResultSet criteria in game mode "${k}" are defined as optimization conditions.`,
+      )
+
+      let gameModeRtp = configMode.rtp
+      let paramRtp = 0
+      for (const cond of conditions) {
+        const paramConfig = mode.conditions[cond]!
+        paramRtp += Number(paramConfig.getRtp())
+      }
+
+      gameModeRtp = Math.round(gameModeRtp * 1000) / 1000
+      paramRtp = Math.round(paramRtp * 1000) / 1000
+
+      assert(
+        gameModeRtp === paramRtp,
+        `Sum of all RTP conditions (${paramRtp}) does not match the game mode RTP (${gameModeRtp}) in game mode "${k}".`,
+      )
+    }
+  }
+
+  getGameConfig() {
+    return this.gameConfig
+  }
+
+  getOptimizerGameModes() {
+    return this.gameModes
+  }
+}
+
+async function rustProgram(...args: string[]) {
+  return new Promise((resolve, reject) => {
+    const task = spawn("cargo", ["run", "--release", ...args], {
+      shell: true,
+      cwd: path.join(__dirname, "./optimizer-rust"),
+      stdio: "pipe",
+    })
+    task.on("error", (error) => {
+      console.error("Error:", error)
+      reject(error)
+    })
+    task.on("exit", () => {
+      resolve(true)
+    })
+    task.on("close", () => {
+      resolve(true)
+    })
+    task.stdout.on("data", (data) => {
+      console.log(data.toString())
+    })
+    task.stderr.on("data", (data) => {
+      console.log(data.toString())
+    })
+    task.stdout.on("error", (data) => {
+      console.log(data.toString())
+      reject(data.toString())
+    })
+  })
+}
+
+export interface OptimizationOpts {
+  gameModes: string[]
+}
+
+export interface OptimizerOpts {
+  game: SlotGame<any, any, any>
+  gameModes: OptimzierGameModeConfig
+}
+
+export type OptimzierGameModeConfig = Record<
+  GameModeName,
+  {
+    conditions: Record<string, OptimizationConditions>
+    scaling: OptimizationScaling
+    parameters: OptimizationParameters
+  }
+>

package/src/utils/math-config.ts

@@ -0,0 +1,109 @@
+import path from "path"
+import { type Optimizer } from "../optimizer"
+import { writeJsonFile } from "../../utils"
+
+export function makeMathConfig(
+  optimizer: Optimizer,
+  opts: { writeToFile?: boolean } = {},
+) {
+  const game = optimizer.getGameConfig()
+  const gameModesCfg = optimizer.getOptimizerGameModes()
+  const { writeToFile } = opts
+
+  const isDefined = <T>(v: T | undefined): v is T => v !== undefined
+
+  const config: MathConfig = {
+    game_id: game.id,
+    bet_modes: Object.entries(game.gameModes).map(([key, mode]) => ({
+      bet_mode: mode.name,
+      cost: mode.cost,
+      rtp: mode.rtp,
+      max_win: game.maxWinX,
+    })),
+    fences: Object.entries(gameModesCfg).map(([gameModeName, modeCfg]) => ({
+      bet_mode: gameModeName,
+      fences: Object.entries(modeCfg.conditions)
+        .map(([fenceName, fence]) => ({
+          name: fenceName,
+          avg_win: isDefined(fence.getAvgWin())
+            ? fence.getAvgWin()!.toString()
+            : undefined,
+          hr: isDefined(fence.getHitRate()) ? fence.getHitRate()!.toString() : undefined,
+          rtp: isDefined(fence.getRtp()) ? fence.getRtp()!.toString() : undefined,
+          identity_condition: {
+            search: Object.entries(fence.getForceSearch()).map(([k, v]) => ({
+              name: k,
+              value: v,
+            })),
+            win_range_start: fence.getSearchRange()[0]!,
+            win_range_end: fence.getSearchRange()[1]!,
+            opposite: false,
+          },
+          priority: fence.priority,
+        }))
+        .sort((a, b) => b.priority - a.priority),
+    })),
+    dresses: Object.entries(gameModesCfg).flatMap(([gameModeName, modeCfg]) => ({
+      bet_mode: gameModeName,
+      dresses: modeCfg.scaling.getConfig().map((s) => ({
+        fence: s.criteria,
+        scale_factor: s.scaleFactor.toString(),
+        identity_condition_win_range: s.winRange,
+        prob: s.probability,
+      })),
+    })),
+  }
+
+  if (writeToFile) {
+    const outPath = path.join(process.cwd(), game.outputDir, "math_config.json")
+    writeJsonFile(outPath, config)
+  }
+
+  return config
+}
+
+export type MathConfig = {
+  game_id: string
+  bet_modes: Array<{
+    bet_mode: string
+    cost: number
+    rtp: number
+    max_win: number
+  }>
+  fences: Array<{
+    bet_mode: string
+    fences: Array<Fence>
+  }>
+  dresses: Array<{
+    bet_mode: string
+    dresses: Dress[]
+  }>
+}
+
+interface Search {
+  name: string
+  value: string
+}
+
+interface IdentityCondition {
+  search: Search[]
+  opposite: boolean
+  win_range_start: number
+  win_range_end: number
+}
+
+interface Fence {
+  name: string
+  avg_win?: string
+  rtp?: string
+  hr?: string
+  identity_condition: IdentityCondition
+  priority: number
+}
+
+interface Dress {
+  fence: string
+  scale_factor: string
+  identity_condition_win_range: [number, number]
+  prob: number
+}

package/src/utils/setup-file.ts

@@ -0,0 +1,36 @@
+import path from "path"
+import { writeFile } from "../../utils"
+import { Optimizer } from "../optimizer"
+
+export function makeSetupFile(optimizer: Optimizer, gameMode: string) {
+  const gameConfig = optimizer.getGameConfig()
+  const optimizerGameModes = optimizer.getOptimizerGameModes()
+  const modeConfig = optimizerGameModes[gameMode]
+
+  if (!modeConfig) {
+    throw new Error(`Game mode "${gameMode}" not found in optimizer configuration.`)
+  }
+
+  const params = modeConfig.parameters.getParameters()
+
+  let content = ""
+  content += `game_name;${gameConfig.id}\n`
+  content += `bet_type;${gameMode}\n`
+  content += `num_show_pigs;${params.numShowPigs}\n`
+  content += `num_pigs_per_fence;${params.numPigsPerFence}\n`
+  content += `threads_for_fence_construction;${params.threadsFenceConstruction}\n`
+  content += `threads_for_show_construction;${params.threadsShowConstruction}\n`
+  content += `score_type;${params.scoreType}\n`
+  content += `test_spins;${JSON.stringify(params.testSpins)}\n`
+  content += `test_spins_weights;${JSON.stringify(params.testSpinsWeights)}\n`
+  content += `simulation_trials;${params.simulationTrials}\n`
+  content += `graph_indexes;0\n`
+  content += `run_1000_batch;False\n`
+  content += `simulation_trials;${params.simulationTrials}\n`
+  content += `user_game_build_path;${path.join(process.cwd(), gameConfig.outputDir)}\n`
+  content += `pmb_rtp;${params.pmbRtp}\n`
+
+  const outPath = path.join(__dirname, "./optimizer-rust/src", "setup.txt")
+
+  writeFile(outPath, content)
+}

package/src/utils/zstd.ts

@@ -0,0 +1,28 @@
+import path from "path"
+import { spawn } from "child_process"
+
+export async function zstd(...args: string[]) {
+  return new Promise((resolve, reject) => {
+    const task = spawn(path.join(__dirname, "./lib/zstd.exe"), args)
+    task.on("error", (error) => {
+      console.error("Error:", error)
+      reject(error)
+    })
+    task.on("exit", () => {
+      resolve(true)
+    })
+    task.on("close", () => {
+      resolve(true)
+    })
+    task.stdout.on("data", (data) => {
+      console.log(data.toString())
+    })
+    task.stderr.on("data", (data) => {
+      console.log(data.toString())
+    })
+    task.stdout.on("error", (data) => {
+      console.log(data.toString())
+      reject(data.toString())
+    })
+  })
+}

package/src/winTypes/ClusterWinType.ts

@@ -0,0 +1,3 @@
+import { WinType } from "../WinType"
+
+export class ClusterWinType extends WinType {}