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.
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
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 |
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 |
