@slot-engine/core 0.0.1 → 0.0.3

package/src/GameConfig.ts

@@ -1,148 +0,0 @@
-import { AnyGameModes, AnySymbols, AnyUserData, CommonGameOptions, GameHooks } from "../index"
-import { GameMode, GameModeName } from "./GameMode"
-import { GameSymbol } from "./GameSymbol"
-
-/**
- * Static configuration for a slot game.\
- * This shouldn't change during gameplay.
- */
-export class GameConfig<
-  TGameModes extends AnyGameModes = AnyGameModes,
-  TSymbols extends AnySymbols = AnySymbols,
-  TUserState extends AnyUserData = AnyUserData,
-> {
-  readonly config: {
-    readonly id: string
-    readonly name: string
-    readonly providerNumber: number
-    readonly gameModes: Record<GameModeName, GameMode>
-    readonly symbols: Map<TSymbols[number]["id"], TSymbols[number]>
-    readonly padSymbols?: number
-    readonly scatterToFreespins: Record<string, Record<number, number>>
-    readonly anticipationTriggers: Record<SpinType, number>
-    readonly maxWinX: number
-    readonly outputDir: string
-    readonly hooks: GameHooks<TGameModes, TSymbols, TUserState>
-    readonly userState?: TUserState
-  }
-
-  constructor(opts: CommonGameOptions<TGameModes, TSymbols, TUserState>) {
-    this.config = {
-      id: opts.id,
-      name: opts.name,
-      providerNumber: opts.providerNumber,
-      gameModes: opts.gameModes,
-      symbols: new Map<string, GameSymbol>(),
-      padSymbols: opts.padSymbols || 0,
-      scatterToFreespins: opts.scatterToFreespins,
-      anticipationTriggers: {
-        [GameConfig.SPIN_TYPE.BASE_GAME]: getAnticipationTrigger(
-          GameConfig.SPIN_TYPE.BASE_GAME,
-        ),
-        [GameConfig.SPIN_TYPE.FREE_SPINS]: getAnticipationTrigger(
-          GameConfig.SPIN_TYPE.FREE_SPINS,
-        ),
-      },
-      maxWinX: opts.maxWinX,
-      hooks: opts.hooks,
-      userState: opts.userState,
-      outputDir: "__build__",
-    }
-
-    for (const symbol of opts.symbols) {
-      if (!this.config.symbols.has(symbol.id)) {
-        this.config.symbols.set(symbol.id, symbol)
-      } else {
-        console.warn(
-          `Symbol with id "${symbol.id}" already exists in the game config. Skipping duplicate. This is probably not intentional.`,
-        )
-      }
-    }
-
-    function getAnticipationTrigger(spinType: string) {
-      return Math.min(...Object.keys(opts.scatterToFreespins[spinType]!).map(Number)) - 1
-    }
-  }
-
-  /**
-   * Generates reelset CSV files for all game modes.
-   */
-  generateReelsetFiles() {
-    for (const mode of Object.values(this.config.gameModes)) {
-      if (mode.reelSets && mode.reelSets.length > 0) {
-        for (const reelGenerator of Object.values(mode.reelSets)) {
-          reelGenerator.associatedGameModeName = mode.name
-          reelGenerator.outputDir = this.config.outputDir
-          reelGenerator.generateReels(this)
-        }
-      } else {
-        throw new Error(
-          `Game mode "${mode.name}" has no reel sets defined. Cannot generate reelset files.`,
-        )
-      }
-    }
-  }
-
-  /**
-   * Retrieves a reel set by its ID within a specific game mode.
-   */
-  getReelsetById(gameMode: string, id: string) {
-    const reelSet = this.config.gameModes[gameMode]!.reelSets.find((rs) => rs.id === id)
-    if (!reelSet) {
-      throw new Error(
-        `Reel set with id "${id}" not found in game mode "${gameMode}". Available reel sets: ${this.config.gameModes[
-          gameMode
-        ]!.reelSets.map((rs) => rs.id).join(", ")}`,
-      )
-    }
-    return reelSet
-  }
-
-  /**
-   * Retrieves the number of free spins awarded for a given spin type and scatter count.
-   */
-  getFreeSpinsForScatters(spinType: SpinType, scatterCount: number) {
-    const freespinsConfig = this.config.scatterToFreespins[spinType]
-    if (!freespinsConfig) {
-      throw new Error(
-        `No free spins configuration found for spin type "${spinType}". Please check your game configuration.`,
-      )
-    }
-    return freespinsConfig[scatterCount] || 0
-  }
-
-  /**
-   * Retrieves a result set by its criteria within a specific game mode.
-   */
-  getGameModeCriteria(mode: string, criteria: string) {
-    const gameMode = this.config.gameModes[mode]
-    if (!gameMode) {
-      throw new Error(`Game mode "${mode}" not found in game config.`)
-    }
-    const resultSet = gameMode.resultSets.find((rs) => rs.criteria === criteria)
-    if (!resultSet) {
-      throw new Error(
-        `Criteria "${criteria}" not found in game mode "${mode}". Available criteria: ${gameMode.resultSets
-          .map((rs) => rs.criteria)
-          .join(", ")}`,
-      )
-    }
-    return resultSet
-  }
-
-  /**
-   * Returns all configured symbols as an array.
-   */
-  getSymbolArray() {
-    return Array.from(this.config.symbols).map(([n, v]) => v)
-  }
-
-  static SPIN_TYPE = {
-    BASE_GAME: "basegame",
-    FREE_SPINS: "freespins",
-  } as const
-}
-
-export type SpinType = (typeof GameConfig.SPIN_TYPE)[keyof typeof GameConfig.SPIN_TYPE]
-
-export type AnyGameConfig = GameConfig<any, any, any>

package/src/GameMode.ts

@@ -1,86 +0,0 @@
-import { type ReelGenerator } from "./ReelGenerator"
-import { type ResultSet } from "./ResultSet"
-
-export class GameMode {
-  name: GameModeName
-  reelsAmount: number
-  symbolsPerReel: number[]
-  cost: number
-  rtp: number
-  reelSets: ReelGenerator[]
-  resultSets: ResultSet<any>[]
-  isBonusBuy: boolean
-
-  constructor(opts: GameModeOpts) {
-    this.name = opts.name
-    this.reelsAmount = opts.reelsAmount
-    this.symbolsPerReel = opts.symbolsPerReel
-    this.cost = opts.cost
-    this.rtp = opts.rtp
-    this.reelSets = opts.reelSets
-    this.resultSets = opts.resultSets
-    this.isBonusBuy = opts.isBonusBuy
-
-    if (this.symbolsPerReel.length !== this.reelsAmount) {
-      throw new Error(
-        `symbolsPerReel length (${this.symbolsPerReel.length}) must match reelsAmount (${this.reelsAmount}).`,
-      )
-    }
-
-    if (this.resultSets.length == 0) {
-      throw new Error("GameMode must have at least one ResultSet defined.")
-    }
-  }
-}
-
-export interface GameModeOpts {
-  /**
-   * Name of the game mode.
-   */
-  name: GameModeName
-  /**
-   * Number of reels the board has.
-   */
-  reelsAmount: number
-  /**
-   * How many symbols each reel has. Array length must match `reelsAmount`.\
-   * The number at an array index represents the number of symbols on that reel.
-   */
-  symbolsPerReel: number[]
-  /**
-   * Cost of the game mode, multiplied by the base bet.
-   */
-  cost: number
-  /**
-   * The target RTP of the game.
-   */
-  rtp: number
-  /**
-   * Defines and generates all reels for the game.\
-   * Which reels are used in a spin is determined by the ResultSet of the current game mode.
-   *
-   * It is common to have one reel set for the base game and another for free spins.\
-   * Each `ResultSet` can then set the weights of these reel sets to control which\
-   * reel set is used for a specific criteria.
-   *
-   * The generator can be adjusted to match the reels to your games needs.
-   */
-  reelSets: ReelGenerator[]
-  /**
-   * A ResultSet defines how often a specific outcome should be generated.\
-   * For example, a ResultSet can be used to force a specific ratio of max wins\
-   * in the simulations to ensure there are different frontend representations.
-   */
-  resultSets: ResultSet<any>[]
-  /**
-   * Whether this game mode is a bonus buy.
-   */
-  isBonusBuy: boolean
-}
-
-export type GameModeName =
-  | "base"
-  | "base-extra-chance-2x"
-  | "base-extra-chance-10x"
-  | "bonus"
-  | string

package/src/GameState.ts

@@ -1,272 +0,0 @@
-import { GameConfig, SpinType } from "./GameConfig"
-import { Wallet } from "./Wallet"
-import { Book } from "./Book"
-import { ResultSet } from "./ResultSet"
-import { RandomNumberGenerator } from "../utils"
-import { AnyGameModes, AnySymbols, AnyUserData, CommonGameOptions } from "../index"
-
-/**
- * The GameState manages the current state of the game.
- */
-export class GameState<
-  TGameModes extends AnyGameModes,
-  TSymbols extends AnySymbols,
-  TUserState extends AnyUserData,
-> extends GameConfig<TGameModes, TSymbols, TUserState> {
-  state: {
-    currentSimulationId: number
-    /**
-     * e.g. "base", "freespins", etc. (depending on the game config)
-     */
-    currentGameMode: string
-    /**
-     * Spin type constant as defined in `GameConfig.SPIN_TYPE`
-     */
-    currentSpinType: SpinType
-    /**
-     * The current ResultSet for the active simulation run.
-     */
-    currentResultSet: ResultSet<any>
-    /**
-     * Whether the criteria in the ResultSet for the current simulation has been met.
-     */
-    isCriteriaMet: boolean
-    /**
-     * Number of freespins remaining in the current freespin round.
-     */
-    currentFreespinAmount: number
-    /**
-     * Total amount of freespins awarded during the active simulation.
-     */
-    totalFreespinAmount: number
-    /**
-     * A library of all completed books, indexed by their ID.
-     */
-    library: Map<string, Book>
-    /**
-     * The current book being recorded.
-     */
-    book: Book
-    /**
-     * Seeded random number generator instance for the current simulation.
-     */
-    rng: RandomNumberGenerator
-    /**
-     * Custom user data that can be used in game flow logic.
-     */
-    userData: TUserState
-    /**
-     * Whether a max win has been triggered during the active simulation.
-     */
-    triggeredMaxWin: boolean
-    /**
-     * Whether freespins have been triggered during the active simulation.
-     */
-    triggeredFreespins: boolean
-  }
-
-  /**
-   * The wallet stores win data for the current and all simulations, respectively.
-   */
-  wallet: Wallet
-
-  /**
-   * Recorder for statistical analysis (e.g. symbol occurrences, etc.).
-   */
-  private recorder: {
-    pendingRecords: PendingRecord[]
-    readonly records: RecordItem[]
-  }
-
-  constructor(opts: CommonGameOptions<TGameModes, TSymbols, TUserState>) {
-    super(opts)
-
-    this.state = {
-      currentSpinType: GameConfig.SPIN_TYPE.BASE_GAME,
-      library: new Map(),
-      book: new Book({ id: 0 }),
-      currentGameMode: "N/A",
-      currentSimulationId: 0,
-      isCriteriaMet: false,
-      currentFreespinAmount: 0,
-      totalFreespinAmount: 0,
-      rng: new RandomNumberGenerator(),
-      userData: opts.userState || ({} as TUserState),
-      triggeredMaxWin: false,
-      triggeredFreespins: false,
-      // This is a placeholder ResultSet to avoid null checks elsewhere.
-      currentResultSet: new ResultSet({
-        criteria: "N/A",
-        quota: 0,
-        reelWeights: {
-          [GameConfig.SPIN_TYPE.BASE_GAME]: {},
-          [GameConfig.SPIN_TYPE.FREE_SPINS]: {},
-        },
-      }),
-    }
-
-    this.wallet = new Wallet()
-
-    this.recorder = {
-      pendingRecords: [],
-      records: [],
-    }
-  }
-
-  /**
-   * Gets the configuration for the current game mode.
-   */
-  getCurrentGameMode() {
-    return this.config.gameModes[this.state.currentGameMode]!
-  }
-
-  resetState() {
-    this.state.rng.setSeedIfDifferent(this.state.currentSimulationId)
-    this.state.book = new Book({ id: this.state.currentSimulationId })
-    this.state.currentSpinType = GameConfig.SPIN_TYPE.BASE_GAME
-    this.state.currentFreespinAmount = 0
-    this.state.totalFreespinAmount = 0
-    this.state.triggeredMaxWin = false
-    this.state.triggeredFreespins = false
-    this.wallet.resetCurrentWin()
-    this.clearPendingRecords()
-    this.state.userData = this.config.userState || ({} as TUserState)
-  }
-
-  /**
-   * Checks if a max win is reached by comparing `wallet.currentWin` to `config.maxWin`.
-   *
-   * Should be called after `wallet.confirmSpinWin()`.
-   */
-  isMaxWinTriggered() {}
-
-  /**
-   * Empties the list of pending records in the recorder.
-   */
-  clearPendingRecords() {
-    this.recorder.pendingRecords = []
-  }
-
-  /**
-   * Confirms all pending records and adds them to the main records list.
-   */
-  confirmRecords() {
-    for (const pendingRecord of this.recorder.pendingRecords) {
-      const search = Object.entries(pendingRecord.properties)
-        .map(([name, value]) => ({ name, value }))
-        .sort((a, b) => a.name.localeCompare(b.name))
-
-      let record = this.recorder.records.find((r) => {
-        if (r.search.length !== search.length) return false
-        for (let i = 0; i < r.search.length; i++) {
-          if (r.search[i]!.name !== search[i]!.name) return false
-          if (r.search[i]!.value !== search[i]!.value) return false
-        }
-        return true
-      })
-      if (!record) {
-        record = {
-          search,
-          timesTriggered: 0,
-          bookIds: [],
-        }
-        this.recorder.records.push(record)
-      }
-      record.timesTriggered++
-      if (!record.bookIds.includes(pendingRecord.bookId)) {
-        record.bookIds.push(pendingRecord.bookId)
-      }
-    }
-
-    this.clearPendingRecords()
-  }
-
-  /**
-   * Record data for statistical analysis.
-   */
-  record(data: Record<string, string | number | boolean>) {
-    this.recorder.pendingRecords.push({
-      bookId: this.state.currentSimulationId,
-      properties: Object.fromEntries(
-        Object.entries(data).map(([k, v]) => [k, String(v)]),
-      ),
-    })
-  }
-
-  /**
-   * Records a symbol occurrence for statistical analysis.
-   *
-   * Calls `this.record()` with the provided data.
-   */
-  recordSymbolOccurrence(data: {
-    kind: number
-    symbolId: string
-    spinType: SpinType
-    [key: string]: any
-  }) {
-    this.record(data)
-  }
-
-  /**
-   * Gets all confirmed records.
-   */
-  getRecords() {
-    return this.recorder.records
-  }
-
-  /**
-   * Moves the current book to the library and resets the current book.
-   */
-  moveBookToLibrary() {
-    this.state.library.set(this.state.book.id.toString(), this.state.book)
-    this.state.book = new Book({ id: 0 })
-  }
-
-  /**
-   * Increases the freespin count by the specified amount.
-   *
-   * Also sets `state.triggeredFreespins` to true.
-   */
-  awardFreespins(amount: number) {
-    this.state.currentFreespinAmount += amount
-    this.state.totalFreespinAmount += amount
-    this.state.triggeredFreespins = true
-  }
-
-  /**
-   * Ensures the requested number of scatters is valid based on the game configuration.\
-   * Returns a valid number of scatters.
-   */
-  verifyScatterCount(numScatters: number) {
-    const scatterCounts = this.config.scatterToFreespins[this.state.currentSpinType]
-    if (!scatterCounts) {
-      throw new Error(
-        `No scatter counts defined for spin type "${this.state.currentSpinType}". Please check your game configuration.`,
-      )
-    }
-    const validCounts = Object.keys(scatterCounts).map((key) => parseInt(key, 10))
-    if (validCounts.length === 0) {
-      throw new Error(
-        `No scatter counts defined for spin type "${this.state.currentSpinType}". Please check your game configuration.`,
-      )
-    }
-    if (numScatters < Math.min(...validCounts)) {
-      return Math.min(...validCounts)
-    }
-    if (numScatters > Math.max(...validCounts)) {
-      return Math.max(...validCounts)
-    }
-    return numScatters
-  }
-}
-
-interface PendingRecord {
-  bookId: number
-  properties: Record<string, string>
-}
-
-export interface RecordItem {
-  search: Array<{ name: string; value: string }>
-  timesTriggered: number
-  bookIds: number[]
-}

package/src/GameSymbol.ts

@@ -1,61 +0,0 @@
-export class GameSymbol {
-  id: string
-  pays?: Record<number, number>
-  properties: Map<string, any>
-
-  constructor(opts: GameSymbolOpts) {
-    this.id = opts.id
-    this.pays = opts.pays
-    this.properties = new Map<string, any>(Object.entries(opts.properties || {}))
-
-    if (this.pays && Object.keys(this.pays).length === 0) {
-      throw new Error(`GameSymbol "${this.id}" must have pays defined.`)
-    }
-  }
-
-  /**
-   * Compares this symbol to another symbol or a set of properties.
-   */
-  compare(symbolOrProperties?: GameSymbol | Record<string, any>) {
-    if (!symbolOrProperties) {
-      console.warn("No symbol or properties provided for comparison.")
-      return false
-    }
-    if (symbolOrProperties instanceof GameSymbol) {
-      return this.id === symbolOrProperties.id
-    } else {
-      for (const [key, value] of Object.entries(symbolOrProperties)) {
-        if (!this.properties.has(key) || this.properties.get(key) !== value) {
-          return false
-        }
-      }
-      return true
-    }
-  }
-}
-
-export 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>
-}