> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/StakeEngine/math-sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# Game Structure

> The recommended directory layout for a Stake Engine game, what each file does, and how game-specific code relates to the shared engine source.

## Directory layout

All games follow a standard directory structure. The recommended starting point is to copy `games/template/` and rename it to your game ID.

```
games/<game_id>/
├── 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
```

The `library/` subdirectories are created automatically when simulations are run if they do not already exist. `readme.txt` is for developer notes about game mechanics and any miscellaneous information relevant to that game.

***

## File reference

| File                   | Purpose                                                                                                                                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `game_config.py`       | Defines the `GameConfig` class (inherits `Config`). Sets game ID, RTP, board dimensions, paytable, reel strips, special symbols, and `BetMode` definitions with their `Distribution` criteria. |
| `gamestate.py`         | Defines the `GameState` class. Contains `run_spin()` (required entry point for every simulation) and `run_freespin()` (required if the game has a freespin mode).                              |
| `run.py`               | Sets simulation parameters and calls `create_books()` and `generate_configs()`. This is the script you execute to produce all output files.                                                    |
| `game_executables.py`  | Groups commonly used game actions (board drawing, win evaluation, freespin triggering) into named functions. Inherits from the engine `Executables` class.                                     |
| `game_calculations.py` | Handles game-specific board calculations. Inherits from `GameExecutables`.                                                                                                                     |
| `game_events.py`       | Contains event-emission functions specific to this game. Events are imported explicitly and not attached to the gamestate object.                                                              |
| `game_override.py`     | First in the Python MRO. Use this to override core engine functions (such as `reset_book()`) without modifying shared source code.                                                             |

***

## `src/` vs `games/`

The repository is split into two top-level areas:

* **`src/`** — reusable engine code shared across all games. This includes win calculators, the wallet manager, the state machine, event helpers, config base classes, and output writers. You should not need to modify files in `src/` for normal game development.
* **`games/<game_id>/`** — all game-specific logic. Every file in the directory layout above lives here. Python's Method Resolution Order (MRO) allows game files to selectively override engine behaviour without copying shared code.

When writing a new mechanic, ask: will this be reused by other games? If yes, it belongs in `src/`. If it is specific to one title, it belongs in `games/<game_id>/`.

***

## Run-file parameters

The `run.py` file controls how simulations are executed. The following parameters are passed to `create_books()`:

| Parameter       | Type             | Description                                                                              |
| --------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `num_threads`   | `int`            | Number of Python processes for parallel simulation                                       |
| `rust_threads`  | `int`            | Number of threads used by the Rust compiler                                              |
| `batching_size` | `int`            | Number of simulations executed per thread per batch                                      |
| `compression`   | `bool`           | `True` outputs `.json.zst`; `False` outputs `.json`                                      |
| `profiling`     | `bool`           | `True` generates a flame graph SVG (single-thread only)                                  |
| `num_sim_args`  | `dict[str, int]` | Keys must match bet mode names defined in `GameConfig`; values are the simulation counts |

```python theme={null}
if __name__ == "__main__":

    num_threads = 1
    rust_threads = 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)
```

***

## Config output files

After simulations complete, `generate_configs(gamestate)` writes three JSON files to `library/configs/`:

| File               | Consumer               | Contents                                                                 |
| ------------------ | ---------------------- | ------------------------------------------------------------------------ |
| `config_fe.json`   | Frontend               | Symbol definitions, paytable, betmode display info, reel layout          |
| `config.json`      | Backend / RGS          | File hash values, betmode costs, game metadata required for verification |
| `config_math.json` | Optimization algorithm | Parameters used when running the weight-optimization step                |

***

## Library folders

| Folder              | Contents                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `books/`            | Uncompressed JSONL simulation output (`.json`)                                                                      |
| `books_compressed/` | Compressed simulation output (`.json.zst`)                                                                          |
| `configs/`          | The three config JSON files described above                                                                         |
| `forces/`           | Force-record files used for PAR sheet generation and optimization; populated by `self.record()` calls in game logic |
| `lookup_tables/`    | CSV payout summary files, including segmented and criteria-mapping variants                                         |