### Setup Math SDK with Makefile

Source: https://stake-engine.com/docs/math/setup

Use the Makefile for a streamlined setup, which includes creating a virtual environment, installing dependencies, and installing the SDK in editable mode.

```bash
make setup
```

--------------------------------

### Example Bet Levels Configuration

Source: https://stake-engine.com/docs/rgs

Illustrates a typical configuration object for bet levels, including minimum bet, maximum bet, bet step, and an array of predefined bet level values. This guides players on valid bet amounts.

```json
{
  "minBet": 100000,
  "maxBet": 1000000000,
  "stepBet": 10000,
  "betLevels": [
    100000, // $0.10
    200000,
    400000,
    600000,
    ...
    1000000000 // $1000
  ]
}

```

--------------------------------

### Example: Run 'lines' Module Storybook

Source: https://stake-engine.com/docs/front-end/getting-started

An example of running the Storybook for the 'lines' module, identified by its name in '/apps/lines/package.json'.

```bash
pnpm run storybook --filter=lines
```

--------------------------------

### Install Dependencies from requirements.txt

Source: https://stake-engine.com/docs/math/setup

Install all project dependencies listed in the requirements.txt file using pip. Ensure the virtual environment is activated before running this command.

```bash
python3 -m pip install -r requirements.txt
```

--------------------------------

### Install Dependencies

Source: https://stake-engine.com/docs/front-end/getting-started

Installs all project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Install Package in Editable Mode

Source: https://stake-engine.com/docs/math/setup

Install the math-sdk package in editable mode using setup.py. This allows changes in the source code to take effect immediately without reinstallation, ideal for development.

```bash
python3 -m pip install -e .
```

--------------------------------

### Clone Math SDK Repository

Source: https://stake-engine.com/docs/math/setup

Clone the Math SDK repository to begin the setup process.

```bash
git@github.com:StakeEngine/math-sdk.git
```

--------------------------------

### Example Bet Replay Request

Source: https://stake-engine.com/docs/approval-guidelines/game-replay-requirements

An example of a GET request to the RGS endpoint for fetching replay data. Replace placeholders with actual values.

```http
GET https://rgs.stake-engine.com/bet/replay/01996148-eecf-7678-be46-41de88c58951/1/SUPER/55
```

--------------------------------

### Install Rust and Cargo

Source: https://stake-engine.com/docs/math/setup

Install Rust and Cargo, which are required for the optimization algorithm. This command downloads and executes the official installation script.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Verify Package Installation

Source: https://stake-engine.com/docs/math/setup

Check if the package has been successfully installed by listing all installed Python packages.

```bash
python3 -m pip list
```

--------------------------------

### Run Simulation Setup

Source: https://stake-engine.com/docs/math/high-level-structure/game-format

This script sets up and runs simulations for the game. It configures simulation parameters, initializes the game state and configuration, and generates simulation data and configuration files.

```python
if __name__ == "__main__":

    num_threads = 1
    rust_threaeds = 20
    batching_size = 50000
    compression = False
    profiling = False

    num_sim_args = {
        "base": int(10),
        "bonus": int(10),
    }

    config = GameConfig()
    gamestate = GameState(config)

    create_books(
        gamestate,
        config,
        num_sim_args,
        batching_size,
        num_threads,
        compression,
        profiling,
    )
    generate_configs(gamestate)

```

--------------------------------

### Install nvm and Node.js

Source: https://stake-engine.com/docs/front-end/getting-started

Installs Node Version Manager (nvm) and Node.js version 18.18.0. Ensure nvm is sourced before installing Node.js.

```bash
# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# in lieu of restarting the shell
\. "$HOME/.nvm/nvm.sh"

# Download and install Node.js:
nvm install 18.18.0

# Verify the node versions. Should print "v18.18.0".
node -v
```

--------------------------------

### BetMode Class Example for Bonus/Buy Feature

Source: https://stake-engine.com/docs/math/game-state-structure/setup/betmode

This example demonstrates how to configure a BetMode for a bonus or buy feature, including distribution criteria, RTP, max win, and specific conditions for reel weights, multipliers, and scatter triggers.

```python
    BetMode(
        name="bonus",
        cost=100.0,
        rtp=self.rtp,
        max_win=self.wincap,
        auto_close_disabled=False,
        is_feature=False,
        is_buybonus=True,
        distributions=[
            Distribution(
                criteria="wincap",
                quota=0.001,
                win_criteria=self.wincap,
                conditions={
                    "reel_weights": {
                        self.basegame_type: {"BR0": 1},
                        self.freegame_type: {"FR0": 1, "WCAP": 5},
                    },
                    "mult_values": {
                        self.basegame_type: {1: 1},
                        self.freegame_type: {2: 10, 3: 20, 4: 50, 5: 60, 10: 100, 20: 90, 50: 50},
                    },
                    "scatter_triggers": {4: 1, 5: 2},
                    "force_wincap": True,
                    "force_freegame": True,
                },
            ),
            Distribution(
                criteria="freegame",
                quota=0.999,
                conditions={
                    "reel_weights": {
                        self.basegame_type: {"BR0": 1},
                        self.freegame_type: {"FR0": 1},
                    },
                    "scatter_triggers": {3: 20, 4: 10, 5: 2},
                    "mult_values": {
                        self.basegame_type: {1: 1},
                        self.freegame_type: {2: 100, 3: 80, 4: 50, 5: 20, 10: 10, 20: 5, 50: 1},
                    },
                    "force_wincap": False,
                    "force_freegame": True,
                },
            ),
        ],
    ),

```

--------------------------------

### Install pnpm

Source: https://stake-engine.com/docs/front-end/getting-started

Installs pnpm version 10.5.0 globally. Verify the installation by checking the pnpm version.

```bash
# Install pnpm
npm install pnpm@10.5.0 -g

# Verify the pnpm versions. Should print "v10.5.0"
pnpm -v
```

--------------------------------

### Integrate Pixi and HTML UI Components

Source: https://stake-engine.com/docs/front-end/ui

Import and use UI components from 'components-ui-pixi' and 'components-ui-html'. This example shows how to set up the main UI structure and modals.

```svelte
<script lang="ts">
	import { UI, UiGameName } from 'components-ui-pixi';
	import { GameVersion, Modals } from 'components-ui-html';
</script>

<App>
  <UI>
    {#snippet gameName()}
      <UiGameName name="LINES GAME" />
    {/snippet}
    {#snippet logo()}
      <Text
        anchor={{ x: 1, y: 0 }}
        text="ADD YOUR LOGO"
        style={{
          fontFamily: 'proxima-nova',
          fontSize: REM * 1.5,
          fontWeight: '600',
          lineHeight: REM * 2,
          fill: 0xffffff,
        }}
      />
    {/snippet}
  </UI>
</App>

<Modals>
	{#snippet version()}
		<GameVersion version="0.0.0" />
	{/snippet}
</Modals>



```

--------------------------------

### Example Win Data Structure with Meta

Source: https://stake-engine.com/docs/math/game-state-structure/wins

An example of the 'wins' dictionary item within win_data, including 'meta' for additional front-end display information like multipliers and line indices.

```python
'wins': {
    'symbol': 'H1',
    'kind': 5,
    'win': 300,
    'positions': [{'reel':1, 'row':1}, ...],
    'meta':{
        'lineIndex': 12,
        'multiplier': 10,
        'winWithoutMult': 30,
        'globalMult': 1,
        'lineMultiplier': 10
    }
}
```

--------------------------------

### Index File with Two Modes Example

Source: https://stake-engine.com/docs/math/math-file-format

Illustrates the _index.json structure for a game with two distinct modes, 'base' and 'bonus', specifying their respective configurations.

```json
{
    "modes": [
        {
            "name": "base",
            "cost": 1.0,
            "events": "books_base.jsonl.zst",
            "weights": "lookUpTable_base_0.csv"
        },
        {
            "name": "bonus",
            "cost": 100.0,
            "events": "books_bonus.jsonl.zst",
            "weights": "lookUpTable_bonus_0.csv"
        }
    ]
}
```

--------------------------------

### Game Logic JSONL Example Record

Source: https://stake-engine.com/docs/math/math-file-format

Shows a minimal example of a game round record in JSON-lines format before compression, including the essential 'id', 'events', and 'payoutMultiplier' fields.

```json
{
    "id": 1, 
    "events": [{}, ...],
    "payoutMultiplier": 1150
}

```

--------------------------------

### Simulation Output Example

Source: https://stake-engine.com/docs/math/quick-start

Observe the game RTP printed by each thread as it finishes. This output provides insights into game performance and win distributions.

```text
Thread 0 finished with 1.632 RTP. [baseGame: 0.043, freeGame: 1.588]

```

--------------------------------

### Set Total Win Book Event Example

Source: https://stake-engine.com/docs/front-end/flowchart

Example of a 'setTotalWin' type bookEvent, used to update the total win amount.

```json
{
  index: 1,
  type: 'setTotalWin',
  amount: 0
}
```

--------------------------------

### Index File Format Example

Source: https://stake-engine.com/docs/math/math-file-format

Defines the structure for the _index.json file, which must contain game mode details like name, cost, event logic filenames, and lookup table filenames.

```json
{
    "modes": [
        {
            "name": <string>,
            "cost": <float>,
            "events": <string>"<logic_file>.jsonl.zst",
            "weights": <string>"<lookup_table>.csv"
        },
        ...
    ]

}
```

--------------------------------

### CSV Lookup Table Example Data

Source: https://stake-engine.com/docs/math/math-file-format

Provides example rows for the CSV lookup table, demonstrating the expected format for simulation number, round probability, and payout multiplier using unsigned integer values.

```text
1,199895486317,0
2,25668581149,20
3,126752606,140
...

```

--------------------------------

### Reveal Book Event Example

Source: https://stake-engine.com/docs/front-end/flowchart

Example of a 'reveal' type bookEvent, which is part of the book.events array.

```json
{
  index: 0,
  type: 'reveal',
  board: [
    [{ name: 'L2' }, { name: 'L1' }, { name: 'L4' }, { name: 'H2' }, { name: 'L1' }],
    [{ name: 'H1' }, { name: 'L5' }, { name: 'L2' }, { name: 'H3' }, { name: 'L4' }],
    [{ name: 'L3' }, { name: 'L5' }, { name: 'L3' }, { name: 'H4' }, { name: 'L4' }],
    [{ name: 'H4' }, { name: 'H3' }, { name: 'L4' }, { name: 'L5' }, { name: 'L1' }],
    [{ name: 'H3' }, { name: 'L3' }, { name: 'L3' }, { name: 'H1' }, { name: 'H1' }],
  ],
  paddingPositions: [216, 205, 195, 16, 65],
  gameType: 'basegame',
  anticipation: [0, 0, 0, 0, 0],
}
```

--------------------------------

### Example Scatter Pay Entry

Source: https://stake-engine.com/docs/math/source-files/calculations/scatter

Illustrates how to define an 8-kind payout for symbol 'H1' with a 10x multiplier.

```python
((8,8),H1): 10
```

--------------------------------

### Example Force Record JSON Structure

Source: https://stake-engine.com/docs/math/game-state-structure/force-files

Illustrates the structure of a `force_record_<betmode>.json` file, showing aggregated data for custom events like scatter symbol triggers.

```json
[
    {
        "search": {
            "gametype": "basegame",
            "kind": 5,
            "symbol": "scatter"
        },
        "timesTriggered": 22134,
        "bookIds": [
            7,
            12,
            ....
        ]
    },
    {
        "search": {
            "gametype": "basegame",
            "kind": 6,
            "symbol": "scatter"
        },
        "timesTriggered": 1196,
        "bookIds": [
            9,
            10
            ...
        ]
    },
    ...
]

```

--------------------------------

### Test Package Import in Python

Source: https://stake-engine.com/docs/math/setup

Verify the installation by attempting to import the package within a Python interpreter session.

```python
>>> import your_package_name
```

--------------------------------

### Base Game Book Structure

Source: https://stake-engine.com/docs/front-end/flowchart

Example of a base game book JSON returned from the RGS, containing game events.

```json
{
  id: 1,
  payoutMultiplier: 0.0,
  events: [
    {
      index: 0,
      type: 'reveal',
      board: [
        [{ name: 'L2' }, { name: 'L1' }, { name: 'L4' }, { name: 'H2' }, { name: 'L1' }],
        [{ name: 'H1' }, { name: 'L5' }, { name: 'L2' }, { name: 'H3' }, { name: 'L4' }],
        [{ name: 'L3' }, { name: 'L5' }, { name: 'L3' }, { name: 'H4' }, { name: 'L4' }],
        [{ name: 'H4' }, { name: 'H3' }, { name: 'L4' }, { name: 'L5' }, { name: 'L1' }],
        [{ name: 'H3' }, { name: 'L3' }, { name: 'L3' }, { name: 'H1' }, { name: 'H1' }],
      ],
      paddingPositions: [216, 205, 195, 16, 65],
      gameType: 'basegame',
      anticipation: [0, 0, 0, 0, 0],
    },
    { index: 1, type: 'setTotalWin', amount: 0 },
    { index: 2, type: 'finalWin', amount: 0 },
  ],
  criteria: '0',
  baseGameWins: 0.0,
  freeGameWins: 0.0,
}
```

--------------------------------

### Storybook Component Entry

Source: https://stake-engine.com/docs/front-end/file-structure

Example of how a component is rendered within a Storybook story, ensuring context is set.

```svelte
// ComponentsGame.stories.svelte

<script lang="ts">
  ...
  import Game from '../components/Game.svelte';
  import { setContext } from '../game/context';

  ...
  setContext();
</script>

<Story name="component (loadingScreen)">
  <StoryLocale lang="en">
    <Game />
  </StoryLocale>
</Story>

```

--------------------------------

### Example Simulation Output

Source: https://stake-engine.com/docs/math/quick-start

Inspect a detailed JSON output for a specific simulation (e.g., simulation 58). This structure includes payout information, revealed symbols, win details, and game criteria.

```json
{
    "id": 58,
    "payoutMultiplier": 10,
    "events": [
        {
            "index": 0,
            "type": "reveal",
            "board":[...],
            "paddingPositions": [...],
            "gameType": "basegame",
            "anticipation": [...] 
        },
        {
            "index": 1,
            "type": "winInfo",
            "totalWin": 10,
            "wins": [
                {
                    "symbol": "L5",
                    "kind": 3,
                    "win": 10,
                    "positions": [...],
                    "meta": {}
                }
            ]
        },
        {
            "index": 2,
            "type": "setWin",
            "amount": 10,
            "winLevel": 2
        },
        {
            "index": 3,
            "type": "setTotalWin",
            "amount": 10
        },
        {
            "index": 4,
            "type": "finalWin",
            "amount": 10
        }
    ],
    "criteria": "basegame",
    "baseGameWins": 0.1,
    "freeGameWins": 0.0
}
```

--------------------------------

### Example Simulation Result JSON Structure

Source: https://stake-engine.com/docs/math/high-level-structure

Illustrates the expected JSON structure for a single simulation result (a "book"), including payout multiplier, events, and win conditions.

```json
[
    {
        "id": int,
        "payoutMultiplier": float,
        "events": [ {}, {}, {} ],
        "criteria": str,
        "baseGameWins": float,
        "freeGameWins": float
    }
]
```

--------------------------------

### XState Game Actor Machine Setup

Source: https://stake-engine.com/docs/front-end/context

Defines the XState machine for game logic, including states for rendering, idle, betting, and more. It utilizes intermediate machines for specific actions like bet, autoBet, and resumeBet.

```typescript
import { setup, createActor } from 'xstate';

...

const gameMachine = setup({
  actors: {
    bet: intermediateMachines.bet,
    autoBet: intermediateMachines.autoBet,
    resumeBet: intermediateMachines.resumeBet,
    forceResult: intermediateMachines.forceResult,
  },
}).createMachine({
  initial: 'rendering',
  states: {
    [STATE_RENDERING]: stateRendering,
    [STATE_IDLE]: stateIdle,
    [STATE_BET]: stateBet,
    [STATE_AUTOBET]: stateAutoBet,
    [STATE_RESUME_BET]: stateResumeBet,
    [STATE_FORCE_RESULT]: stateForceResult,
  },
});

const gameActor = createActor(gameMachine);

```

--------------------------------

### Implement Task Breakdown for 'tumbleBoard' Event

Source: https://stake-engine.com/docs/front-end/task-breakdown

This example shows how a complex 'tumbleBoard' bookEvent is broken down into multiple smaller emitterEvents for sequential execution. Use this pattern when a single event triggers a series of related actions.

```typescript
// bookEventHandlerMap.ts - Example of task-breakdown

{
  ...,
  tumbleBoard: async (bookEvent: BookEventOfType<'tumbleBoard'>) => {
    eventEmitter.broadcast({ type: 'tumbleBoardShow' });
    eventEmitter.broadcast({ type: 'tumbleBoardInit', addingBoard: bookEvent.newSymbols });
    await eventEmitter.broadcastAsync({
      type: 'tumbleBoardExplode',
      explodingPositions: bookEvent.explodingSymbols,
    });
    eventEmitter.broadcast({ type: 'tumbleBoardRemoveExploded' });
    await eventEmitter.broadcastAsync({ type: 'tumbleBoardSlideDown' });
    eventEmitter.broadcast({
      type: 'boardSettle',
      board: stateGameDerived
        .tumbleBoardCombined()
        .map((tumbleReel) => tumbleReel.map((tumbleSymbol) => tumbleSymbol.rawSymbol)),
    });
    eventEmitter.broadcast({ type: 'tumbleBoardReset' });
    eventEmitter.broadcast({ type: 'tumbleBoardHide' });
  },
  ...,
}

```

--------------------------------

### Calculate Ways for a Symbol Combination

Source: https://stake-engine.com/docs/math/source-files/calculations/ways

Illustrates how to calculate the number of ways a specific symbol combination can win, considering consecutive symbols and their positions on the board. This example shows a basic calculation for 'H1' symbol.

```python
(1) * (2) * (3) = 6 ways
```

--------------------------------

### Clone Repository and Navigate

Source: https://stake-engine.com/docs/front-end/getting-started

Clones the project repository and navigates into the 'web-sdk' directory. Replace '<REPO_CLONE_URL>' with the actual repository URL.

```bash
git clone <REPO_CLONE_URL>
cd web-sdk
```

--------------------------------

### Set Up Optimization Parameters in Python

Source: https://stake-engine.com/docs/math/optimization-algorithm

Configure game-specific optimization parameters using the OptimizationSetup class in run.py. The opt_params dictionary defines settings for different bet modes.

```python
opt_params = <mode_name> : {
    "conditions": ...
    "scaling": ...
    "parameters: 
}

```

--------------------------------

### Create Vite Project with NPM

Source: https://stake-engine.com/docs/rgs/example

Use this command to initialize a new Vite project. Ensure you are using NPM version v22.16.0 or compatible.

```bash
npm create vite@latest
```

--------------------------------

### Initialize WinManager

Source: https://stake-engine.com/docs/math/source-files/win-manager

Initializes the WinManager with modes for base game and free game. Sets up variables for tracking cumulative and spin-level wins.

```python
class WinManager:
    def __init__(self, base_game_mode, free_game_mode):
        self.base_game_mode = base_game_mode
        self.free_game_mode = free_game_mode

        self.total_cumulative_wins = 0
        self.cumulative_base_wins = 0
        self.cumulative_free_wins = 0

        self.running_bet_win = 0.0

        self.basegame_wins = 0.0
        self.freegame_wins = 0.0

        self.spin_win = 0.0
        self.tumble_win = 0.0

```

--------------------------------

### Build Vite Project

Source: https://stake-engine.com/docs/rgs/example

Execute this command to build your Vite project for deployment. The output will be placed in the 'dist/' folder.

```bash
yarn build
```

--------------------------------

### Run Default Game Simulation

Source: https://stake-engine.com/docs/math/quick-start

Execute the default game simulation using the make command. This command initiates the game specified by the GAME environment variable.

```bash
make run GAME=0_0_lines
```

--------------------------------

### Recommended Game File Structure

Source: https://stake-engine.com/docs/math/high-level-structure/game-structure

This is the standard directory structure for a game project. Copy this structure from the games/template folder.

```text
game/
├── library/
|----- books/
|----- books_compressed/
|----- configs/
|----- forces/
|----- lookup_tables/
├── reels/
├── readme.txt
├── run.py
├── game_config.py
├── game_executables.py
├── game_calculations.py
├── game_events.py
├── game_override.py
└── gamestate.py
```

--------------------------------

### Setting Up Multiple Svelte Contexts

Source: https://stake-engine.com/docs/front-end/context

Demonstrates how to set multiple contexts at the entry level of a Svelte application. Ensure all necessary event emitters and state managers are initialized before calling setContext.

```typescript
export const setContext = () => {
  setContextEventEmitter<EmitterEvent>({ eventEmitter });
  setContextXstate({ stateXstate, stateXstateDerived });
  setContextLayout({ stateLayout, stateLayoutDerived });
  setContextApp({ stateApp });
};
```

--------------------------------

### Updating Freespin Event

Source: https://stake-engine.com/docs/math/game-state-structure/events

Shows an example of importing and calling an event update function within a game's run cycle.

```python
from src.Events.Events import update_freespin_event

run_spin():
    ...
    update_freespin_event(self)
    ....

```

--------------------------------

### Update Free Spin Book Event Handler

Source: https://stake-engine.com/docs/front-end/flowchart

Example of a bookEventHandler for 'updateFreeSpin' type. It broadcasts events to update the free spin counter.

```typescript
export const bookEventHandlerMap: BookEventHandlerMap<BookEvent, BookEventContext> = {
  ...,
  updateFreeSpin: async (bookEvent: BookEventOfType<'updateFreeSpin'>) => {
    eventEmitter.broadcast({ type: 'freeSpinCounterShow' });
    eventEmitter.broadcast({
      type: 'freeSpinCounterUpdate',
      current: bookEvent.amount,
      total: bookEvent.total,
    });
  },
  ...,
}
```

--------------------------------

### GeneralGameState Constructor

Source: https://stake-engine.com/docs/math/source-files/state

Initializes the game state with a configuration object and sets up various game-related variables and helper methods.

```APIDOC
## Constructor: `__init__(self, config)`

### Description
Initializes the game state with the provided configuration. This includes setting up internal variables such as `library`, `recorded_events`, `special_symbol_functions`, `win_manager`, and `criteria`. It also calls helper methods to reset seeds, create symbol mappings, reset book values, and assign special symbol functions.

### Parameters
* **config** (object) - The configuration object for the game state.
```

--------------------------------

### Get Random Outcome from Distribution Conditions

Source: https://stake-engine.com/docs/math/game-state-structure/setup/distribution

Use this to draw a random value from the distribution conditions, typically for multipliers. Ensure `betmode.get_distribution_conditions()` is accessible.

```python
multiplier = get_random_outcome(betmode.get_distribution_conditions()['mult_values'])
```

--------------------------------

### Reset Book Initialization

Source: https://stake-engine.com/docs/math/high-level-structure

Initializes or resets the book object at the start of a simulation, setting default values for payout multiplier, events, and criteria.

```python
def reset_book(self) -> None:
    self.book = {
        "id": self.sim + 1,
        "payoutMultiplier": 0.0,
        "events": [],
        "criteria": self.criteria,
    }
```

--------------------------------

### Run Game with Makefile

Source: https://stake-engine.com/docs/math/setup

Execute a specific game using the run.py script via the Makefile, after setting the relevant game parameters.

```bash
make run GAME=<game_id>
```

--------------------------------

### Define an emitterEvent for Free Spin Counter

Source: https://stake-engine.com/docs/front-end/flowchart

An example of an emitterEvent structure used for updating free spin counters. It includes properties for the current and total number of free spins.

```typescript
// bookEventHandlerMap.ts - Example of an emitterEvent

{
  type: 'freeSpinCounterUpdate',
  current: undefined,
  total: bookEvent.totalFs,
}
```

--------------------------------

### Define Game Configuration Parameters

Source: https://stake-engine.com/docs/math/high-level-structure/game-format

Initialize game parameters such as ID, RTP, board dimensions, and special symbol actions within the `GameConfig` class. All required fields from the `Config` class must be explicitly set.

```python
class GameConfig(Config):
    def __init__(self):
        super().__init__()
        self.game_id = ""
        self.provider_number = 0
        self.working_name = ""
        self.wincap = 0
        self.win_type = "lines"
        self.rtp = 0

        self.num_reels = 0
        self.num_rows = [0] * self.num_reels  
        self.paytable = {
            (kind, symbol): payout, 
        }

        self.include_padding = True
        self.special_symbols = {"property": ["sym_name"],...}

        self.freespin_triggers = {
        }
        self.reels = {}
        self.bet_modes = []

```

--------------------------------

### Execute Optimization Modes with Python

Source: https://stake-engine.com/docs/math/optimization-algorithm

Run the optimization script for specified game modes using the OptimizationExecution class. This initiates the Rust binary with the configured parameters.

```python
optimization_modes_to_run = ["base", "bonus"]
OptimizationExecution().run_all_modes(config, optimization_modes_to_run, rust_threads)

```

--------------------------------

### RGS Endpoint for Bet Replay Data

Source: https://stake-engine.com/docs/approval-guidelines/game-replay-requirements

This is the GET endpoint used to fetch replay data from the RGS server. It requires the game ID, version, mode, and event ID.

```http
GET {rgs_url}/bet/replay/{game}/{version}/{mode}/{event}
```

--------------------------------

### Configure Simulation Parameters

Source: https://stake-engine.com/docs/math/quick-start

Set the number of simulations per mode and control simulation and optimization runs. Use compressed output for larger simulations.

```python
num_sim_args = {
    "base": int(1e4),
    "bonus": int(1e4),
}

run_conditions = {
    "run_sims": True,
    "run_optimization": True,
    "run_analysis": True,
    "upload_data": False,
}

```

--------------------------------

### GeneralGameState Methods

Source: https://stake-engine.com/docs/math/source-files/state

Provides documentation for the various methods available in the GeneralGameState class, covering symbol mapping, state resets, bet mode retrieval, win checking, event recording, and simulation running.

```APIDOC
## Methods:

### `create_symbol_map(self) -> None`

#### Description
Extracts all valid symbols from the configuration and constructs a `SymbolStorage` object containing symbols from the paytable and special symbols.

### `assign_special_sym_function(self)` (Abstract Method)

#### Description
This method must be overridden in derived classes to define custom symbol behavior. Issues a warning if no special symbol functions are defined.

### `reset_book(self) -> None`

#### Description
Resets global game state variables including `board`, `book_id`, `book`, and `win_data`. Initializes default values for win tracking and spin conditions, and resets the `win_manager` state.

### `reset_seed(self, sim: int = 0) -> None`

#### Description
Resets the random number generator seed based on the simulation number for reproducibility.

#### Parameters
* **sim** (int, optional) - The simulation number. Defaults to 0.

### `reset_fs_spin(self) -> None`

#### Description
Resets the free spin game state when triggered. Updates `gametype` and resets spin wins in `win_manager`.

### `get_betmode(self, mode_name) -> BetMode`

#### Description
Retrieves a bet mode configuration based on its name. Prints a warning if the bet mode is not found.

#### Parameters
* **mode_name** (str) - The name of the bet mode to retrieve.

### `get_current_betmode(self) -> object`

#### Description
Returns the current active bet mode.

### `get_current_betmode_distributions(self) -> object`

#### Description
Retrieves the distribution information for the current bet mode based on the active criteria. Raises an error if criteria distribution is not found.

### `get_current_distribution_conditions(self) -> dict`

#### Description
Returns the conditions required for the current criteria setup. Raises an error if bet mode conditions are missing.

### `get_wincap_triggered(self) -> bool`

#### Description
Checks if a max-win cap has been reached, stopping further spin progress if triggered.

### `in_criteria(self, *args) -> bool`

#### Description
Checks if the current win criteria match any of the given arguments.

#### Parameters
* **args** - Variable length argument list representing criteria to check.

### `record(self, description: dict) -> None`

#### Description
Records specific game events to the `temp_wins` list for tracking distributions.

#### Parameters
* **description** (dict) - A dictionary describing the event to record.

### `check_force_keys(self, description) -> None`

#### Description
Verifies and adds unique force-key parameters to the bet mode configuration.

#### Parameters
* **description** (dict) - The description containing force-key parameters.

### `combine(self, modes, betmode_name) -> None`

#### Description
Merges forced keys from multiple mode configurations into the target bet mode.

#### Parameters
* **modes** (list) - A list of mode configurations to merge from.
* **betmode_name** (str) - The name of the target bet mode.

### `imprint_wins(self) -> None`

#### Description
Records triggered events in the `library` and updates `win_manager`.

### `update_final_win(self) -> None`

#### Description
Computes and verifies the final win amount across base and free games. Ensures that total wins do not exceed the win cap. Raises an assertion error if the sum of base and free game payouts mismatches the recorded final payout.

### `check_repeat(self) -> None`

#### Description
Determines if a spin needs to be repeated based on criteria constraints.

### `run_spin(self, sim)` (Abstract Method)

#### Description
Must be implemented in derived classes. Placeholder prints a message if not overridden.

#### Parameters
* **sim** - Simulation parameter (type depends on implementation).

### `run_freespin(self)` (Abstract Method)

#### Description
Must be implemented in derived classes. Placeholder prints a message if not overridden.

### `run_sims(self, betmode_copy_list, betmode, sim_to_criteria, total_threads, total_repeats, num_sims, thread_index, repeat_count, compress=True, write_event_list=True) -> None`

#### Description
Runs multiple simulations, setting up bet modes and criteria per simulation. Tracks and prints RTP calculations. Writes temporary JSON files for multi-threaded results. Generates lookup tables for criteria and payout distributions.

#### Parameters
* **betmode_copy_list** (list) - List of bet mode copies for simulations.
* **betmode** (object) - The base bet mode configuration.
* **sim_to_criteria** (dict) - Mapping of simulation to criteria.
* **total_threads** (int) - Total number of threads to use.
* **total_repeats** (int) - Total number of repeats for simulations.
* **num_sims** (int) - Number of simulations to run.
* **thread_index** (int) - The index of the current thread.
* **repeat_count** (int) - The current repeat count.
* **compress** (bool, optional) - Whether to compress output files. Defaults to True.
* **write_event_list** (bool, optional) - Whether to write event lists. Defaults to True.
```

--------------------------------

### Subscribe to Task Breakdown Events in Svelte Component

Source: https://stake-engine.com/docs/front-end/task-breakdown

This Svelte component example demonstrates how to subscribe to individual emitterEvents that are part of a larger task breakdown. Ensure all relevant event handlers are defined to manage the component's state changes.

```svelte
// TumbleBoard.svelte - Example of task-breakdown

context.eventEmitter.subscribeOnMount({
  tumbleBoardShow: () => {},
  tumbleBoardHide: () => {},
  tumbleBoardInit: () => {},
  tumbleBoardReset: () => {},
  tumbleBoardExplode: () => {},
  tumbleBoardRemoveExploded: () => {},
  tumbleBoardSlideDown: () => {},
});

```

--------------------------------

### Build the Rust Optimization Binary

Source: https://stake-engine.com/docs/math/optimization-algorithm

Rebuild the Rust binary if it's the first run or if main.rs has been modified. This command compiles the optimization algorithm for release.

```bash
cargo build --release

```

--------------------------------

### Disabling Button Based on XState Game Status

Source: https://stake-engine.com/docs/front-end/context

Example of integrating Svelte context with UI components to control element behavior. The 'disabled' property of a button is dynamically set based on whether the game is currently playing, using XState derived values.

```svelte
<script lang="ts">
  import { getContext } from '../context';

  const context = getContext();
</script>

<SimpleUiButton disabled={context.stateXstateDerived.isPlaying()} />

```

--------------------------------

### Create AppContext in Pixi-Svelte

Source: https://stake-engine.com/docs/front-end/context

This snippet shows the initialization of the `stateApp` object, which serves as the application context. It includes properties for resetting the app, managing assets, tracking loading progress, and holding the PIXI application instance.

```typescript
// createApp.svelte.ts

const stateApp = $state({
  reset,
  assets,
  loaded: false,
  loadingProgress: 0,
  loadedAssets: {} as LoadedAssets,
  pixiApplication: undefined as PIXI.Application | undefined,
});

```

--------------------------------

### reveal_event(gamestate)

Source: https://stake-engine.com/docs/math/source-files/events

Logs the initial board state, including padding symbols if enabled.

```APIDOC
## reveal_event(gamestate)

### Description
Logs the initial board state, including padding symbols if enabled.

### Parameters
#### Path Parameters
- **gamestate** (object) - Required - The current game state.
```