iGaming Codex

stake-engine-math-sdk

время чтения ~5 мин.

Stake Engine math-sdk

TL;DR

Open-source Python SDK от Stake.com для математики слотов по discrete-outcomes парадигме: оффлайн-симуляция → книги (books_<mode>.jsonl.zst) + lookup-table (lookUpTable_<mode>_0.csv) + index → публикация на Stake RGS, который на каждый /play просто сэмплит готовый раунд по весам. Включает Rust-оптимизатор весов под таргетную RTP.

Для нас полезен как методологический референс — мы не публикуем на Stake, а пишем real-time бэк на JS (см. slot backend architecture). Но идиомы Stake — BetMode + Distribution, criteria/quotas, force-records, repeat-cycle, multilayer wallet — мы заимствуем 1:1.

Назначение

  • Описание правил слота (paytable, reels, special symbols, freegame triggers, win-mechanics) на Python.
  • Симуляция миллионов раундов с детерминированным RNG-seed = simulation_id.
  • Сегментация выборки по criteria (wincap, freegame, 0, basegame) с quotas и force-флагами.
  • Подбор весов lookup-table к таргетной RTP (Rust-оптимизатор).
  • Генерация publish-артефактов в строгом формате Stake RGS.

Use case

КейсСтоит брать?
Публикуем игру на Stake.comДа — это официальный путь.
Прототипируем math для своего real-time бэкаДа, как референс. Гоняем на нём sample-игры, читаем код, заимствуем идиомы — но не используем артефакты на проде.
Делаем live progressive jackpot или tournament-poolНет — модель не поддерживает persistent state.
Хочется быстро итерировать math на проде (A/B math-конфигов)Нет — каждый патч = full re-publish.
Нужна минимальная скорость прода без CPU на спинДа (precomputed approach даёт это автоматически).

Сильные стороны

  • Полный pipeline «описал правила → получил cert-ready артефакты». Минимальный glue.
  • Идеальный replay (id → книга), удобный для cert и dispute resolution.
  • Dev-experience: compression=False → human-readable JSON-книги для прокликивания фронта на любом scenario.
  • Multithreading + Rust optimizer — миллионы симуляций реалистично за минуты.
  • Sample-games (0_0_lines, 0_0_ways, 0_0_cluster, 0_0_scatter, 0_0_expwilds) — рабочий референс по основным win-механикам.
  • Открытая лицензия (MIT).

Ограничения

  • Vendor-lock на Stake RGS-формат: index.json + jsonl.zst + uint64-CSV — это контракт Stake. Свой RGS под этот формат можно сделать, но если возьмём другой — нужны конвертеры.
  • Только stateless-раунды: persistent meta-state между раундами не вписывается. Прогрессии, jackpots, мульти-сессионные миссии — нет.
  • Каждый math-патч → full re-publish (десятки MB на mode).
  • Python: для нашего JS-стека — отдельный runtime. Гоняем как референс CLI, не интегрируем в прод-сервис.
  • Discrete probability quantization (uint64 веса): для очень редких событий вынуждены большие N симуляций.
  • Возможность повторов раундов: при N симуляций каждый исход в среднем встречается раз в N/weight раундов. SDK борется через quotas, но «полностью уникальный опыт» как у real-time не получить.

Лицензия и стоимость

  • Лицензия: MIT.
  • Стоимость: бесплатно. Сам RGS Stake — коммерческий, доступ через partnership с Stake.com.

Установка и базовый запуск

Требования: Python ≥3.12, pip; Rust + Cargo (для оптимизатора).

git clone https://github.com/StakeEngine/math-sdk.git
cd math-sdk
make setup           # создаёт venv, ставит deps, editable install пакета
make run GAME=0_0_lines

После запуска — артефакты в games/0_0_lines/library/:

library/
├── books/               # human-readable JSON (compression=False)
├── books_compressed/    # .jsonl.zst для prod-publish
├── configs/             # config_math.json, config_fe.json, config.json
├── forces/              # force_record_<mode>.json (анализ редких событий)
├── lookup_tables/       # lookUpTable_<mode>.csv + IdToCriteria, Segmented
└── publish_files/       # index.json + final compressed books + optimized lookUpTable

Параметры в games/<id>/run.py: num_threads, batching_size, compression, num_sim_args (число симуляций per mode), флаги run_sims/run_optimization/run_analysis.

Структура репо

math-sdk/
├── src/
│   ├── calculations/    # board, lines, ways, cluster, scatter, tumble, statistics
│   ├── config/          # Config, BetMode, Distribution, output_filenames
│   ├── events/          # event_constants, events.py (reusable event emitters)
│   ├── executables/     # GameExecutables (draw_board, run_freespin_from_base, emit_*)
│   ├── state/           # GeneralGameState, run_sims, books, state_conditions
│   ├── wins/            # WinManager (multilayer wallet), multiplier_strategy
│   └── write_data/      # write_configs, write_data, force.py
├── games/
│   ├── 0_0_lines/       # sample lines-game (5x3, 20 paylines)
│   ├── 0_0_ways/        # sample ways-game (5x3, 243 ways)
│   ├── 0_0_cluster/     # sample cluster-game (cascading)
│   ├── 0_0_scatter/     # sample scatter-pays (cascading)
│   ├── 0_0_expwilds/    # sample expanding-wilds + superspin mode
│   └── template/        # пустой скелет для нового game
├── optimization_program/ # Rust-оптимизатор весов lookup-table
├── docs/                # mkdocs-сайт
├── tests/               # pytest для win-калькуляций
└── utils/               # game_analytics (PAR sheet), rgs_verification (format checks)

Подробное руководство по архитектуре, win-механикам, optimization-алгоритму и заметки по портированию идиом на TypeScript/Node — в research-документе.

Что мы заимствуем как методологию

  • BetMode + Distribution: см. BetMode + Distribution.
  • Criteria + quota + repeat-cycle для устойчивых статистик: см. simulation methodology.
  • Multilayer WalletManager с инвариантом: см. wallet manager pattern.
  • Events как stream с типизированными dispatcher-функциями: см. events as stream.
  • Force-records как аналитический хук: см. simulation methodology.
  • Lookup-table optimization как опция для buy-bonus / superspin режимов: см. lookup-table optimization.
  • Алгоритмы win-evaluation:
    • Paylines — LineWins с wild override и multiplier-strategies.
    • Ways — WaysWins с мультипликативным wild-multiplier.
    • Cluster — ClusterWins с BFS по 4-связной сетке.
    • Scatter — ScatterWins (pay-anywhere).
    • Tumble — Tumble с сохранением top-symbol.

Альтернативы

  • slot-math-engine (C#/.NET, commercial) — Monte Carlo + analytical RTP.
  • Slot Designer (commercial GUI) — для math-prototypers без кода.
  • Своя кодовая база на JS/TS — наш выбор, см. slot backend architecture.

Опыт использования

  • 2026-05-13: репо склонирован в ~/work/sandbox/math-sdk, проанализирован по docs и sample 0_0_lines. Артефакты не запускались (Python ≥3.12 + Rust setup пока не делали — нужны для запуска make setup/make run).

Связанные

Вид графа