Cheating (Rigging RNG for Testing)

You can tell hizi engine to draw a specific outcome instead of a real random one. The engine uses this same mechanism internally for tests. QA, certification, and demonstrations also use this mechanism. This process is called rigging or cheating. It works in two places: at game launch, where it fixes the first draw, and mid-session, where it fixes a later draw on an already-running round.

Authorization lives outside the engine

You can rig a bet only when the session is authorized to use the cheat tool. hizi-engine does not authorize sessions. It only queues the expectedRNGResult value that game-api hands back on the token. See Authorizing a session below.

How it works

A game makes several decisions with an RNG (Random Number Generator). These decisions include which entry to pay out, which stored scenario to replay for that entry, which card to deal, and which pocket the roulette ball lands in. Fortuna (or PF, see Provably Fair) normally draws these values. A rig is a queue of numbers. The game consumes these numbers in place of real draws, in the exact order that the game's handler makes them:

[[24753536], [0]]

A plain slot spin uses two draws. The first number picks the entry (see Core Concepts § Entries). The engine walks the weighted table until it reaches the cumulative weight. The second number picks which of that entry's stored scenarios to replay (0 means the first one recorded). Multi-step verticals (game types with more than one draw per round), such as mines picks, blackjack hits, and hi/lo calls, queue one pair (or more) per step. Each step makes its own draw.

Finding a rig

From the backoffice

1. Go to Games and find your game. Open it and check the hizi engine configs tab. This tab shows which config each environment (staging or production) currently runs.

2. Open that config and select the Edit tab. Filter or sort the list to find the win that you want to force. Note its Cum. Weight value.

The engine draws a value uniformly from [1, totalWeight]. The engine resolves the first entry whose own Cum. Weight is >= the draw. An entry with weight w owns the w draw values immediately below and including its own Cum. Weight. You can use the Cum. Weight value shown in the Edit tab directly as the rig's first number. You do not need to adjust this value.

From the Math Doc

Export tab → Math Doc downloads the certification math document (HTML) for that config version. Scroll to the bottom of the document to find ready-made example rigs for each entry. The document generates these rigs from the same weighting logic as the Edit tab. You can copy and paste them directly.

Not every vertical has Math Doc rigs

Math Doc rigs work only for verticals that use an entry or pool table, such as slot, keno, and roulette pockets. Blackjack and crash resolve their RNG draws into cards or multipliers elsewhere in the stack. For these verticals, the document has no [[cumWeight],[scenario]]-shaped rig to read. Instead, queue raw draws to rig them (see Multi-step and non-slot verticals).

Authorizing a session

Rigging takes effect only when the session is authorized to use the cheat tool. Otherwise, the engine silently ignores expectedRNGResult, and the bet resolves normally (see Gotchas below).

Local RGS: In the hizi.io backoffice, open the relevant Identity. Go to Settings. Turn on Enable cheat tool. Select Save, then select Publish to sync the change to your local RGS.

Hosted environments (sandbox or production): game-api decides authorization. It checks canUseCheatTool on the operator, or allows a demo session on the test operator. There is no per-request opt-in beyond this.

Using a rig

At launch

Append expectedRNGResult as a query parameter to the game's demo or launch URL:

https://<env>.hizi.work/demo/<game-code>?expectedRNGResult=[[24753536],[0]]

This rigs the first draw or draws of the round. Use it to demonstrate a specific outcome from a cold launch.

Mid-session

Pass expectedRNGResult (a JSON-encoded number[][] string) through additionalData on any placeBet call. Send it the same way as other per-bet fields, such as pickPosition and bets:

await placeBet({
  backendURL,
  token,
  stake,
  additionalData: { expectedRNGResult: '[[24753536],[0]]' },
});

hizi-engine forwards this value to game-api's /setDebugData before it dispatches the bet. It then continues with whatever tokenData game-api returns. Queue several […] pairs to rig several consecutive draws from one call. The handler consumes one queued entry per RNG call, in order. This lets you rig a multi-step round, such as mines pick after pick or blackjack hit after hit, draw-by-draw across its whole sequence in a single expectedRNGResult.

Multi-step and non-slot verticals

For verticals without a Math Doc rig (blackjack, crash), or for multi-step verticals where you want to rig more than the opening draw, queue the raw draws that the handler itself would make. Use this instead of an entry/scenario pair. Check the vertical's guide under Games to see what each step draws. hizi-engine-tester's cheat-rig input box wires this exact additionalData field into every placeBet call it sends. Use it as a working reference to test rigs before you script your own.

Gotchas

• Silent no-op when unauthorized. An expectedRNGResult on an unauthorized session does not cause an error. The engine simply drops it, and the bet resolves as a normal, unrigged draw. If a rig does not work, check the cheat-tool authorization of the identity or operator before you assume the rig value is wrong.
• Not every vertical maps onto a Math Doc rig. See the tip under From the Math Doc.
• Local RGS needs an explicit publish. Turning on Enable cheat tool in Identity Settings does nothing until you select Save and then Publish to sync the change to your local RGS.