Skip to main content

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.

The SDK ships with five fully implemented sample games in games/. Each game covers a distinct win type and set of mechanics, and all share the same file structure so you can use any of them as a template.

​
Included games

Game IDWin typeKey mechanics
0_0_linesLines20 paylines, wild multipliers (additive in freegame), separate freegame reelset
0_0_waysWays243 ways, wild multipliers (multiplicative in freegame), wilds excluded from reel 1
0_0_clusterClusterTumbling, grid position multipliers (up to 512×), global multiplier
0_0_scatterScatterPay-anywhere tumbling, persistent global multiplier, board multiplier symbols
0_0_expwildsLinesExpanding sticky wilds with random per-spin multipliers, superspin purchase mode

Lines game

3-row, 5-reel, 20 paylines. Wild multipliers add together in freegame. Separate freegame reelset.

Ways game

5-reel, 3-row, 243 ways. Wild multipliers compound multiplicatively in freegame.

Cluster game

7×7 tumbling board. Grid position multipliers activate and double on each win.

Scatter game

6-reel, 5-row pay-anywhere tumbling. Persistent global multiplier, board multiplier symbols.

​
Running a sample game

From the project root, use the make shortcut: 
make run GAME=0_0_lines
Or invoke the run script directly after activating your virtual environment: 
python3 games/0_0_lines/run.py
Replace 0_0_lines with any game ID from the table above.

​
Game file structure

Every game directory contains the same set of files: 
games/<game_id>/
├── game_config.py       # GameConfig — dimensions, paytable, reels, BetMode/Distribution setup
├── gamestate.py         # GameState — run_spin() and run_freespin() logic
├── game_executables.py  # GameExecutables — grouped helper functions
├── game_calculations.py # GameCalculations — win evaluation overrides
├── game_events.py       # Game-specific event emission functions
├── game_optimization.py # OptimizationSetup — PAR sheet keys and analysis config
├── game_override.py     # Inheritance chain connecting all layers
├── run.py               # Entry point: simulations, optimization, analysis
├── readme.txt           # Brief description of game rules
└── reels/               # Reelstrip CSV files (BR0.csv, FR0.csv, etc.)
FilePurpose
game_config.pyDefines all static game parameters: grid size, paytable, special symbols, freespin triggers, reelstrips, and BetMode/Distribution objects
gamestate.pyImplements run_spin() for basegame and run_freespin() for the feature. This is where game flow is controlled.
game_executables.pyGrouped helper methods used in gamestate.py (win evaluation, event dispatch, freespin management)
game_calculations.pyOptional overrides for win calculation functions from src/calculations/
game_events.pyGame-specific event builders not covered by the shared event library
run.pyTop-level script: sets simulation counts, threading, and which pipeline steps to run

​
Using the template to create a new game

games/template/ is a minimal skeleton with all required files stubbed out. Copy it to start a new game:
1

Copy the template

cp -r games/template games/my_game
2

Set your game ID

Open games/my_game/game_config.py and set self.game_id, self.win_type, self.num_reels, self.num_rows, and self.paytable.
3

Add reelstrips

Create a reels/ directory inside your game folder and add your reelstrip CSV files.
4

Implement game logic

Fill in run_spin() and run_freespin() in gamestate.py. Use the sample games as reference implementations.
5

Configure bet modes

Set up BetMode and Distribution objects in game_config.py to define simulation criteria.
6

Run your game

make run GAME=my_game
Start by running a small number of uncompressed simulations to verify your event output before scaling up. Set compression = False and "base": 100 in run.py for quick debugging.

​
Output files

All generated files are written into games/<game_id>/library/: 
library/
├── books/
│   └── books_<mode>.jsonl       # Simulation results (events + payoutMultiplier per round)
├── lookup_tables/
│   ├── lookUpTable_<mode>.csv   # id, weight, payoutMultiplier
│   ├── lookUpTableSegmented_<mode>.csv
│   └── lookUpTableIdToCriteria_<mode>.csv
├── forces/
│   └── force_record_<mode>.json
└── publish_files/               # Final files required for RGS publication
The library/publish_files/ directory contains the books, lookup tables, and index file required for publication to the Stake Engine RGS. These must be present regardless of whether this SDK is used to generate the math results.

Build docs developers (and LLMs) love

Get started for freeTalk to us