How stakeengine/math-sdk works
Project Type and Purpose
• This is a Python-based Software Development Kit (SDK) for defining slot-game rules, simulating outcomes, and optimizing win distributions.
• It also includes an optional Rust/Cargo “optimization_program” for performance-critical distribution optimization.
• Sample “games” folders act as plug-in definitions demonstrating SDK usage.
• Auxiliary components: AWS upload tools, utilities for analysis, and MkDocs-based documentation.
Top-Level Components
• CLI Orchestrator (Makefile / setup.py / run scripts)
• Core SDK (src/)
• config: bet modes, constants, paths
• calculations: board, cluster, lines, scatter, tumble, ways, statistics
• events: event definitions and logic
• executables: wrappers to generate game executables
• state: game-state modeling and simulation runner
• wins: win-manager and multiplier strategies
• write_data: output writing of configs, force files, simulation results
• Optimization Engine (optimization_program/)
• Rust-based binary invoked via run_script.py or cargo directly
• Game Definitions (games/)
• Multiple subfolders (cluster, expwilds, lines, scatter, ways) each implement a standardized interface (game_config, game_events, game_calculations, gamestate, run.py)
• AWS Upload Service (uploads/)
• AWS S3 uploader classes, constants, env config
• Utilities (utils/)
• Analysis, verification, decompress, game analytics
• Testing (tests/)
• Unit tests for win calculations and core logic
• Documentation (docs/, mkdocs.yml)
• MkDocs source, styling, and assets
Interactions and Data Flow
• Developer invokes CLI (Make targets or setup.py) → selects a game or generic simulation →
• SDK config module loads parameters → initial game state instantiated by state module →
• Event and calculations modules simulate spins, outcomes →
• wins module computes payouts →
• write_data module writes out JSON/CSV results and config files →
• optionally optimization_program (Rust) is called to refine distribution parameters →
• results can be uploaded via uploads module to AWS S3 →
• utilities can post-process or analyze results →
• tests validate core SDK logic in CI.
Architectural Patterns and Design Principles
• Layered modular architecture:
• Configuration Layer → Business Logic Layer (calculations & events) → State & Simulation Layer → Output/Persistence Layer → External Services
• Plugin-style game definitions decoupled from core SDK
• Separation of concerns: each folder/module has a single responsibility
• CLI as thin orchestration layer
• Use of an external high-performance Rust component for optimization