Skip to content

Home

Jump to bottom
Richard Fu edited this page Jan 16, 2026 · 2 revisions

Stake Engine Math SDK Documentation

Welcome to the Stake Engine Math SDK wiki! This Python-based framework is designed for defining slot game rules, simulating outcomes at scale, and optimizing win distributions.

📚 Quick Navigation

Getting Started

Core Concepts

Advanced Topics

Reference

🎉 Recent Improvements (v2.0.0 - January 2026)

The SDK underwent a comprehensive refactoring and optimization:

Architecture Refactoring

  • 67% reduction in inheritance complexity (6 → 2 layers)
  • 75% reduction in files per game (4 → 1 file)
  • 180+ type hints with comprehensive docstrings
  • Custom exception hierarchy and standardized constants

Output Optimization

  • 35-40% smaller files via compression + event filtering
  • 13% faster generation with compact mode
  • Fully backward compatible, RGS verified

Performance Optimization

  • 35-47% simulation speedup via paytable caching
  • 287 sims/sec average (up from 204 sims/sec)
  • Built-in profiling tools

🚀 Quick Start

Installation

# Clone repository
git clone https://github.com/Raw-Fun-Gaming/stake-engine-math.git
cd stake-engine-math

# Setup environment
make setup
source env/bin/activate

Run Your First Simulation

# Run a sample game
make run GAME=template_cluster

# Books files generated in:
# games/template_cluster/build/books/

📖 Key Concepts

Books

Simulation results stored as JSON/JSONL files containing:

  • board - The reel strip result (symbol grid)
  • events - Game events (wins, triggers, multipliers)
  • payout_multiplier - Total win amount

BetModes

Games have different modes (base/bonus) with their own:

  • Reel strips and distributions
  • Win calculation logic
  • Probability weights

Events

Event-driven architecture using EventConstants:

  • WIN, REVEAL, TRIGGER_FREE_SPINS, etc.
  • Standardized types prevent errors
  • Event filtering for size optimization

Optimization

Rust genetic algorithm adjusts distributions to meet:

  • RTP (Return to Player) targets
  • Hit Rate (win frequency) goals
  • Average Win constraints
  • Custom search conditions

📦 Project Structure

stake-engine-math/
├── docs/              # Documentation (this wiki)
├── games/             # Individual game implementations
├── src/               # Core SDK modules
│   ├── calculations/  # Win algorithms (cluster/lines/ways/scatter)
│   ├── config/        # Configuration system
│   ├── events/        # Event system with filtering
│   ├── output/        # Output optimization
│   └── state/         # Core state machine
├── optimization_program/  # Rust optimization engine
├── tests/             # 54 tests (all passing)
└── scripts/           # Helper tools

🛠️ Common Tasks

Running Simulations

make run GAME=tower_treasures

Enable Output Optimization

In game_config.py:

from src.output.output_formatter import OutputMode

config.output_mode = OutputMode.COMPACT  # 27.9% smaller
config.skip_derived_wins = True          # Additional 10-15% reduction

Running Tests

make unit-test GAME=tower_treasures  # Game-specific
make test                             # Full SDK tests
make coverage                         # Coverage report

Performance Profiling

make profile GAME=tower_treasures
make benchmark GAME=template_lines

📚 Documentation Paths

For New Users

  1. Running Games
  2. Game Structure
  3. Testing

For Game Developers

  1. Game Structure
  2. Event System
  3. Testing Guide

For Optimization Engineers

  1. Optimization Guide
  2. Performance Analysis
  3. Compression Benchmarks

🔗 External Links

ℹ️ Version

Current: v2.0.0 (January 2026)

See the Migration History page for complete refactoring details.

Ready to get started? Jump to Running Games to run your first simulation! 🎰

Clone this wiki locally