#Slot Math Production Pipeline

Статус: робочий процес команди Оновлено: 2026-08-23 Призначення: створення, інтеграція, дотюнення, фіксація та сертифікаційна підготовка математичної моделі слота.

Основна мова math tooling: Go. Reference model, exact calculator, Monte Carlo simulator, report generator і CLI збираються в один відтворюваний Go toolchain без Python runtime.

Жоден open-source інструмент не замінює незалежну перевірку математики, перевірку RNG та сертифікацію в лабораторії для цільового ринку.

#Основний принцип

Єдиним джерелом істини є версіонований набір:

GDD version
Math Spec version
Reference model version
Game build version
Configuration hash
Exact calculation report
Simulation report
Parity/regression report

Зміни reel strips, paytable, weights, evaluation order або feature logic не вносяться без нової версії math configuration і повторної перевірки.

#Pipeline

flowchart TD
    A["Product brief"] --> B["Target math profile"]
    B --> C["Mechanics + state model"]
    C --> C1{"Unique player-visible mechanic?"}
    C1 -- "No" --> D["Draft Math v0.x"]
    C1 -- "Yes" --> C2["Presentation module + state flow + Visual Refs"]
    C2 --> C3{"Unique mechanic gate passed?"}
    C3 -- "No" --> C2
    C3 -- "Yes" --> D
    D --> E["Draft Preview: exact if cheap, otherwise MC ≤10M"]
    E --> F{"Preview gate passed?"}
    F -- "No" --> D
    F -- "Yes" --> G["Version + protocol + deterministic seeds"]
    G --> H["DEV prototype integration"]
    H --> I["Reference ↔ engine parity tests"]
    I --> J{"Parity passed?"}
    J -- "Implementation defect" --> H
    J -- "Design/math change" --> K["Tuning request"]
    J -- "Yes" --> L["Gameplay + distribution review"]
    K --> M["Math tuning v0.x"]
    M --> E
    L --> N{"Product + math targets passed?"}
    N -- "No" --> K
    N -- "Yes" --> O["Final evidence: full exact/MC + review"]
    O --> U{"Freeze gate passed?"}
    U -- "No" --> K
    U -- "Yes" --> V["Math Freeze v1.0"]
    V --> P["Final GDD + Math Spec"]
    P --> Q["Independent math/RNG review"]
    Q --> R{"Certification gate passed?"}
    R -- "No" --> K
    R -- "Yes" --> S["Certification build"]
    S --> T["External test laboratory"]

#Етапи та acceptance gates

#Draft Preview

Draft Preview потрібний, щоб якнайшвидше дати механіку на DEV, побачити її в реальній грі й лише потім витрачати час на tuning та великий evidence-прогін. Він придатний для інтеграції, але має маркування DEV ONLY · UNBALANCED · NOT FOR CERTIFICATION.

GDD
→ rough math/config
→ exact enumeration, якщо простір дешевий; інакше seeded MC ≤10M
→ version + config hash + wire protocol + deterministic DEV seeds
→ DEV playtest
→ tuning iterations
→ final full-size evidence
→ Math Freeze

Для малих enumerable ігор exact calculation має пріоритет над Monte Carlo. Наприклад, для простої 3×3 моделі повний перебір може бути швидшим і сильнішим доказом, ніж 10M випадкових раундів.

На Draft Preview не запускаємо 100M лише заради переходу на DEV. Виняток можливий тільки якщо рідкісна механіка не піддається exact/conditional analysis і без великої вибірки неможливо навіть оцінити безпечність прототипу.

Обов'язкові поля:

• math/config version і checksum;
• target та current RTP;
• base/feature RTP split;
• reel strips або symbol weights;
• paytable і payout units;
• evaluation order, rounding і win-cap rules;
• feature state model;
• hit, profitable-hit, trigger і retrigger frequencies;
• volatility/standard deviation;
• max-win derivation і приблизна частота;
• exact method або simulation seed, sample size (не більше потрібного для рішення) та confidence interval;
• список open і locked tuning parameters;
• відомі обмеження.

Рекомендовані preview-допуски визначає math owner до початку роботи. Вони навмисно ширші за freeze. Приклад:

Draft Preview gate перевіряє не фінальне балансування, а мінімальну безпечність прототипу:

• payout не від'ємний, cap і termination працюють;
• wager/debit/credit і replay ідемпотентні;
• reference/runtime збігаються на ключових deterministic scenarios;
• відомий приблизний RTP і немає очевидної катастрофи на кшталт 20% або 200%;
• усі неточні метрики явно позначені як draft;
• DEV не може бути помилково прийнятий за frozen/certification build.

#Unique Mechanic Presentation Gate

Після state model кожна player-visible механіка класифікується як standard або unique. Стандартна механіка може посилатися на затверджений спільний flow. Унікальна механіка не переходить до DEV handoff, доки для неї не створено окремий presentation module.

Механіка вважається унікальною, якщо вона вводить хоча б одну нестандартну поведінку, наприклад:

• новий тип трансформації, переміщення, lock, expansion, collection або refill;
• власний feature loop, counter, reset, retrigger чи terminal state;
• особливий handover між base game, Free Spins та вкладеним bonus;
• нове anticipation або символи, поведінка яких до/після trigger не покрита спільним стандартом;
• новий порядок презентації wins, modifiers, totals або jackpot awards.

Обов'язковий пакет для унікальної механіки:

• game-specific state/flow diagram;
• окремий module на базі templates/slot-presentation-flow-template.md;
• Visual Ref ID і пряме посилання на storyboard, GIF, video або implementation capture для кожного унікального player-visible state;
• animation trigger, ordering, minimum hold, skip/finalize і required terminal pose;
• failure, cancel, reconnect та stale-continuation правила;
• authoritative backend fields, якими керується кожен перехід;
• deterministic DEV scenario/seed для trigger, звичайного loop, terminal, retrigger і failure/recovery, якщо відповідна гілка існує.

Статичний скриншот не закриває gate, якщо істотними є рух, timing або порядок. Placeholder Visual Ref дозволений під час раннього Draft, але до frontend implementation він мусить бути замінений на approved moving reference. Якщо поведінка не унікальна, документ явно посилається на стандартний state замість створення дубліката.

#Developer handoff і DEV protocol

Мінімальний Draft Preview пакет:

math/
├── draft-math-spec-v0.3.md
├── paytable-v0.3.csv
├── reels-v0.3.json
├── feature-config-v0.3.json
├── preview-report-v0.3.json
├── test-vectors-v0.3.json
├── dev-scenarios-v0.3.json
├── presentation-flow-v0.3.md
├── presentation/
│   └── unique-mechanic-flow-v0.3.md  # only when the game has a unique mechanic
├── manifest-v0.3.json
└── CHANGELOG.md

manifest повинен зв'язувати GDD, math config, reference model і test vectors через версії та SHA-256 hashes.

Test vectors повинні покривати:

• no-win, single-win і simultaneous-win screens;
• wild substitution та винятки;
• scatter/bonus trigger;
• multipliers і порядок їх застосування;
• cascade/respin termination;
• retrigger;
• rounding;
• max win і win cap;
• interrupted-round recovery;
• кожний player choice, якщо він змінює математичний результат.

DEV handoff додатково повинен містити:

• Game ID, config version і SHA-256;
• точний player wire protocol та приклади response;
• deterministic force_seed/mock scenarios для ключових win/feature/max-win шляхів;
• current draft metrics і sample size/method;
• список відомих math, runtime і presentation gaps;
• game-specific presentation flow на базі templates/slot-presentation-flow-template.md;
• для кожної унікальної механіки — пройдений Unique Mechanic Presentation Gate, approved Visual Refs і deterministic DEV scenarios;
• явне повідомлення, що tuning і final evidence ще не завершені.

DEV playtest перевіряє presentation, pacing, feature flow, reconnect, replay та контракт. Він не сертифікує RTP і не закриває Math Freeze.

#Tuning loop

Кожна зміна починається з tuning request:

ID: MATH-017
Problem metric: median bonus win = 8x
Target: median bonus win >= 12x
Allowed changes: free-spin weights, initial multiplier weights
Locked: total RTP, base hit rate, max win, evaluation order
Baseline config: v0.3 + SHA-256
Candidate config: v0.4 + SHA-256

Послідовність:

1. Зафіксувати baseline і вимірювану проблему.
2. Вибрати мінімальний набір параметрів для зміни.
3. Створити нову, а не перезаписати стару конфігурацію.
4. Повторити exact calculation для доступного простору станів.
5. Повторити seeded Monte Carlo для stateful features.
6. Побудувати delta report: RTP contribution, hit distribution, volatility, bonus і tail wins.
7. Повторити reference-to-engine parity та regression tests.
8. Оновити manifest, changelog і handoff package.

Під час tuning використовуємо найменшу вибірку, достатню для поточного рішення: зазвичай exact для enumerable частини або 1–10M seeded rounds для напрямку зміни. Повний великий прогін повторюється лише після погодження механіки й candidate-конфіга, а не після кожного руху weight.

Суб'єктивний feedback на кшталт “bonus weak” перетворюється на метрики: median/quantiles, частку бонусів нижче 5x, retrigger frequency, average duration і концентрацію RTP у top 1% результатів.

#Final evidence gate

Перед Math Freeze запускається окремий прогін на зафіксованій tree/config identity без паралельного навантаження, що спотворює час або результат. Для складної stateful гри типовий фінальний Monte Carlo може становити 100M раундів; це не універсальний мінімум і не заміна exact calculation.

Фінальний gate включає:

• exact calculation усіх доступних просторів;
• достатній Monte Carlo для stateful/rare-event частини;
• RTP split, hit rate, volatility, feature/jackpot frequency і tail distribution;
• witnessed або конструктивно доведений max win та cap;
• reference ↔ runtime parity;
• deterministic replay/idempotency vectors;
• config hash, source tree/commit, RNG identity та immutable reports;
• незалежний correctness review.

#Math Freeze

Після v1.0 заблоковані reels/weights, paytable, feature probabilities, evaluation order, RTP split, rounding, max win, win cap і bet-dependent behavior.

Версіонування:

• v1.0.1 — лише документаційне виправлення, math hash не змінюється;
• v1.1 — зміна math/config, потрібні full regression і нові reports;
• v2.0 — зміна механіки або state model, потрібен повторний design/math cycle.

#GitHub-інструменти

#Кандидати для пілота

#Допоміжний стек

#Рекомендований варіант впровадження

Не будувати production pipeline навколо одного стороннього slot engine. Використати двоконтурну перевірку:

1. Власний мінімальний Go reference model — єдині правила, exact enumeration там, де це можливо, seeded simulation для stateful features, worker pool із локальними accumulators та deterministic merge.
2. Незалежний cross-check — спершу slotopol/server для reel-based math; pokie як швидкий JS/TS prototype, якщо його evaluator відповідає потрібній механіці.
3. Game engine parity — engine отримує ті самі configs і deterministic inputs, але не копіює результати reference model.
4. Окремий RNG track — statistical screening плюс зовнішня перевірка за вимогами юрисдикції.

Це знижує ризик common-mode error, коли симуляція та production engine використовують один і той самий помилковий evaluator.

#Go-структура math tooling

cmd/slotmath/          CLI: exact, simulate, report, verify
internal/config/       versioned JSON/YAML parsing and validation
internal/game/         immutable game definition and state model
internal/evaluator/    lines/ways/clusters and payout aggregation
internal/exact/        deterministic enumeration
internal/sim/          seeded parallel Monte Carlo
internal/metrics/      RTP, variance, hit rates, buckets, quantiles
internal/parity/       test-vector and engine-output comparison
internal/report/       JSON, CSV and self-contained HTML reports
testdata/              configs, golden vectors and regression fixtures

Паралельна симуляція не повинна залежати від scheduler order. Кожен worker отримує визначений seed/stream і локальні integer counters; результати зливаються у фіксованому порядку. Грошові значення зберігаються як цілі credits/мікроодиниці, а не float64; floating point використовується тільки для фінальних статистичних ratios і reports.

#Tool-adoption spike

До вибору бібліотеки провести однаковий тест для pokie, slot-engine і slotopol/server:

1. Реалізувати просту модель 5x3, 20 paylines, wild і scatter.
2. Порахувати base RTP точним власним перебором.
3. Запустити seeded simulation не менше ніж у двох кандидатах.
4. Порівняти RTP, hit rate, win buckets і конкретні test vectors.
5. Перевірити license, активність, releases, dependency/security alerts і можливість pin/fork.
6. Обрати інструмент лише після числової parity та code review.

Acceptance criteria для spike:

• exact RTP збігається з нашим calculator до машинної/погодженої точності;
• усі deterministic test vectors збігаються;
• Monte Carlo target входить у розрахований confidence interval;
• є фіксована версія dependency і відтворюваний build;
• команда може додати власну feature без форкування значної частини engine.

#Джерела

• slotopol/server: reel scanner та mathematics output
• POKIE: slot logic, simulation та seeded replay
• Slot Engine: TypeScript core, panel та optimizer
• Math Simulator: Excel-based навчальний simulator
• UKGC RTS 7: acceptably random outcomes
• UKGC testing strategy: RNG, mapping, rules і expected RTP
• GLI-19 v3.0: Interactive Gaming Systems