# hizi engine

> hizi engine is a system for building and serving pre-computed game outcomes for fixed-odds games - slots, instant wins, scratch cards, plinko, mines, blackjack, crash, and more. Game outcomes are simulated offline, the generator writes compact JSONL files (`entries`, `scenarios`, `config`, `buyfeatures`), and the hizi RGS platform serves them to players at runtime through the `@hizi.io/engine-sdk`.

The docs cover three audiences:

- **Game-engine authors** use `@hizi.io/engine-generator` (TypeScript) or `hizi-engine-generator` (Python) to convert simulation results into entries/scenarios/config files. Start with [Core Concepts](https://docs.hizi.io/engine/core-concepts) and the [Generator section](https://docs.hizi.io/engine/generator/).
- **Frontend authors** use `@hizi.io/engine-sdk` to drive the four-call game lifecycle (`login`, `loadConfig`, `placeBet`, `collect`) against a running engine. Start with the [SDK section](https://docs.hizi.io/engine/sdk/).
- **Per-game integrators** read the [Games guides](https://docs.hizi.io/engine/games/) for the `scenario` shape, `additionalData` requirements, and round flow specific to each supported game type.

Docs live at https://docs.hizi.io/engine.

## hizi engine

- [What is hizi engine?](https://docs.hizi.io/engine/what-is-hizi-engine): One-page system overview - generate -> deploy -> play, and what the engine handles vs. what you build.
- [Core Concepts](https://docs.hizi.io/engine/core-concepts): Entries, weights, scenarios (single-result vs multi-result), meta tags, features, feature awards (random/player choice), buy-features, and progression counters.
- [Getting Started](https://docs.hizi.io/engine/getting-started): Choose your path - generator workflow (offline simulation) or SDK workflow (frontend integration).
- [Provably Fair](https://docs.hizi.io/engine/provably-fair): SHA-256/HMAC-SHA512 RNG protocol - server-seed commitments, client seeds, nonces, per-vertical reveal timing, audit-trail wire shape, and `pfVerify` for server-side replay.

## Generator (offline)

- [Generator Overview](https://docs.hizi.io/engine/generator/): TypeScript (`@hizi.io/engine-generator`) and Python (`hizi-engine-generator`) packages - entry merging, scenario limiting, streaming JSONL output, dual Node/browser support.
- [Getting Started](https://docs.hizi.io/engine/generator/getting-started): Install from the private registry (TS) or pip (Py), instantiate `HiziEngineGenerator`, call `start` / `addResult` / `end`.
- [Output Format](https://docs.hizi.io/engine/generator/output-format): Brotli-compressed JSONL output - `entries.jsonl.br`, `scenarios.jsonl.br`, `config.json`, optional `buyfeatures.jsonl.br`. Field-by-field shape and how to read it back.
- [Browser Usage](https://docs.hizi.io/engine/generator/browser): Running the generator in a dedicated Web Worker against OPFS, with COOP/COEP cross-origin isolation, and `brotli-wasm` for compressing downloads.
- [Buy-Features](https://docs.hizi.io/engine/generator/buy-features): Building selection pools from recorded entries - `entrypool` vs `stakeboost` strategies, `weightOverrides`, pricing config (`IBuyFeatureConfig`), and the synthetic `bf_<id>` feature wiring.
- [API Reference](https://docs.hizi.io/engine/generator/api): Full surface of `HiziEngineGenerator` - constructor options, `start`, `addResult`, `end`, `buildBuyFeatures`, `featureTotalWeights`, `loadEntries`.
- [Types](https://docs.hizi.io/engine/generator/types): Exported interfaces - `IEntryConfig`, `IAddResultOptions`, `IEndOptions`, `IFeatureAward`, `TFeaturesAwarded`, `IBuyFeatureDefinition/Entry/Config`, `IGameConfig`, `IProgressionCounterConfig`.
- [KPI Math](https://docs.hizi.io/engine/generator/kpi-math): Pure functions for RTP, volatility, hit rate, win distribution, win odds, meta-tag KPIs, and feature breakdowns - also exposed via `@hizi.io/engine-generator/math`.
- [Slot Game Example](https://docs.hizi.io/engine/generator/examples/slot-game): End-to-end TypeScript/Python example - 3x3 slot with scatter-triggered freespins, meta-tagging, and feature awards.

## SDK (frontend runtime)

- [SDK Overview](https://docs.hizi.io/engine/sdk/): All `@hizi.io/engine-sdk` exports - core calls, session management, free-play helpers, response/error types, reply types, request option types, and re-exported engine result types.
- [Getting Started](https://docs.hizi.io/engine/sdk/getting-started): Install from the private registry, read launch params from the URL, and walk through the four essential calls (`login`, `loadConfig`, `placeBet`, `collect`).
- [Game Flow](https://docs.hizi.io/engine/sdk/game-flow): Complete lifecycle implementation - class skeleton, login + session bring-up, config load, spin loop, multi-step continuations, and animation reporting.
- [Response Handling](https://docs.hizi.io/engine/sdk/response-handling): The `IGameResult` shape - `scenario`, `engineData` (`entryIndex`, `scenarioInfo`, `spinInfo`, `playerChoice`, `progressionCounters`, `canCollect`, `currentFeature`, `nextFeature`), and win/balance fields.
- [Error Handling](https://docs.hizi.io/engine/sdk/error-handling): The `TNetworkResponse<T>` discriminated union, `API_RETURNCODES`, `recoverableErrorCodes`, and the always-check-`success`-first pattern.
- [Buy Features](https://docs.hizi.io/engine/sdk/buy-features): Discover via `loadConfig.config.buyFeatures`, pass `featureToBuy` to `placeBet`, and the `IBuyFeatureOption` shape with engine-calculated `price` and `featureRTP`.
- [Gamble Features](https://docs.hizi.io/engine/sdk/gamble-features): Two wager modes - `wagerFeatures` (relative multiplier on accumulated win, best for short card/ladder gambles) and `wagerStakeFeatures` (absolute cashout multiplier on original stake, best for long multi-step games like mines and frogger).
- [Endpoints](https://docs.hizi.io/engine/sdk/endpoints): Request/response shapes for `login`, `loadConfig`, `placeBet`, `collect`, `pfVerify`, `reportAnimationEnd`, `updateBalance` - and the operator `gameSettings` the frontend must honour.
- [Types](https://docs.hizi.io/engine/sdk/types): Engine result types re-exported from the SDK - `IGameResult`, `IScenarioInfo`, `ISpinInfo`, `IBuyFeatureOption`, `ILoadConfigConfig`, `IProgressionCounterConfig`.
- [Progression Counters](https://docs.hizi.io/engine/sdk/progression-counters): Per-player counters that accumulate toward 1.0 - `randomChoice`/`playerChoice` selection, mixed feature-spin and cash-multiplier awards, stake-specific persistence.
- [Demo](https://docs.hizi.io/engine/sdk/demo): Link to the live "Fruits 95" reference game on the hizi staging environment.

## Games

- [Games Overview](https://docs.hizi.io/engine/games/): Index of per-game integration guides - each one explains the `scenario` shape returned by `placeBet`, any `additionalData` the round needs, and the collect-or-continue flow.
- [Slot Games](https://docs.hizi.io/engine/games/slot): `IResult` from `@hizi.io/slot-types` - boards, wins, cascades, hold & win, sticky symbols, multiplier collection, wheel features.
- [Plinko](https://docs.hizi.io/engine/games/plinko): Bucket-index scenario, row/risk selection via buy-features, multiplier lookup from `loadConfig`, ball-drop animation.
- [Frogger](https://docs.hizi.io/engine/games/frogger): Multi-step wager-stake flow, risk selection via buy-features, cashout multiplier ladder from `loadConfig`, collect-or-continue loop.
- [Hi/Lo](https://docs.hizi.io/engine/games/hilo): `playerChoice`-driven higher/lower/skip flow, dynamic card odds, skip re-deal within the round, multiplier rounding, collect-or-continue loop.
- [Mines](https://docs.hizi.io/engine/games/mines): Pick positions sent via `additionalData`, the `board` tile-state array, mine-count selection via buy-features, cashout multiplier progression, collect-or-continue loop.
- [Keno](https://docs.hizi.io/engine/games/keno): Player numbers via `additionalData` (or auto-pick), enriched `playerNumbers`/`drawnNumbers`, pick-count and risk selection via buy-features, pay-table rendering.
- [Over/Under](https://docs.hizi.io/engine/games/overunder): Single-roll instant resolution, threshold/direction selection via buy-features, multiplier lookup, win calculation.
- [Roulette](https://docs.hizi.io/engine/games/roulette): Multi-bet rounds composed via `additionalData`, polymorphic `selection` per bet type, per-bet `settlement[]` (`won`/`payout`/`winAmount`), enriched scenario fields (`color`, `oddEven`, `dozen`, `column`), and the two RTP mechanisms.
- [Blackjack](https://docs.hizi.io/engine/games/blackjack): Initial deal with optional side bets, multi-step action flow (`playerChoice`: hit/stand/double/split/insurance/evenMoney), final `IBlackjackScenario` with dealer, hands, side-bet results, and insurance payouts.
- [Crash](https://docs.hizi.io/engine/games/crash): Open a round via `crashPlaceBetData`, listen to the server-driven curve over websocket events (`roundStarted`/`roundTick`/`betCashedOut`/`roundEnded`/`balanceUpdated`), trigger manual cashouts via `collect` + `crashCollectData`.

## Optional

- [Wager Stake Features (engineering note)](https://docs.hizi.io/engine/wager-stake-features): Background on why `wagerStakeFeatures` was added - compounding rounding losses across many wager steps (mines, frogger) and how the absolute-multiplier model fixes them.