Wager Stake Features

While building the mines game I ran into compounding rounding issues with regular wager features. Each step in a wager chain truncates to the nearest cent, and across 24 steps (or 50 in frogger) these small losses add up to a significant RTP shortfall. To solve this I added a new engine feature called "Wager Stake" features. They work like regular wager features in that losing means you lose everything in the game round. The difference is how winning works. Instead of multiplying the accumulated totalWin by a relative multiplier, the entry's win value is an absolute cashout multiplier applied directly to the original stake. This avoids any chained multiplication and eliminates the compounding rounding problem entirely.

The problem with regular wager features

Regular wager features multiply the accumulated totalWin at each step. The engine truncates to the nearest cent after every multiplication. For a card gamble this is fine because there are only a few steps. But mines can have up to 24 steps and frogger can have up to 50. Each truncation loses up to 1 cent, and these losses compound through the chain.

With regular wager features on a 1 mine game at 98% target RTP, the simulator measured 91.55% actual RTP across 43 million rounds. That is a 6.45% loss entirely from compounding rounding.

How wager stake features fix this

Instead of storing a relative multiplier at each step (like 1.04x meaning "multiply your current winnings by 1.04"), wager stake features store the absolute cashout multiplier (like 1.225x meaning "your cashout is 1.225 times your original stake").

The engine does not multiply anything. It just replaces totalWin with the entry's win value. There is no compounding because there is no chain of multiplications. The payout at any step is simply floor(entry.win * stake), which is a single rounding operation.

Example

Player bets 100 on a 1 mine game (5x5 grid, 98% RTP).

Basegame result: safe. Entry win = 1.0208. The player can collect floor(1.0208 * 100) = 102.

Pick 1 result: safe. Entry win = 1.0652. The player can collect floor(1.0652 * 100) = 106.

Pick 2 result: safe. Entry win = 1.1136. The player can collect floor(1.1136 * 100) = 111.

Pick 3 result: safe. Entry win = 1.1666. The player can collect floor(1.1666 * 100) = 116.

Pick 4 result: safe. Entry win = 1.225. The player can collect floor(1.225 * 100) = 122.

If the player hits a mine at any step, the entry win is 0 and they lose their stake.

Notice that each entry's win is the cashout multiplier for that step, not a ratio between consecutive steps. The engine just sets totalWin to the entry's win value and moves on.

With regular wager features the same sequence would give amountToCollect = 120 instead of 122 due to compounding floor operations at each step.

How to use it

In config.json, list the step features under wagerStakeFeatures instead of wagerFeatures.

wagerStakeFeatures: ["mines_1_pick_1", "mines_1_pick_2", ...]

In the builder's dbWorker, set each wager entry's win to the absolute cashout multiplier (cashoutMult at that step) instead of the relative wager multiplier (ratio between consecutive cashouts).

Both types can coexist in the same game. For example, a mines game could use wagerStakeFeatures for the mine picking progression and regular wagerFeatures for an optional card gamble on top. The mine picks use absolute multipliers with no compounding loss, and the card gamble multiplies the final cashout value as usual.

What changed

hizi-engine: added wagerStakeFeatures to IGameConfig, updated placeBet continuation logic, simulator, and loadConfig hizi-engine-creator: mines and frogger builders now emit absolute cashout multipliers and list step features under wagerStakeFeatures hizi-engine-generator: updated JSDoc on KPI functions to clarify both wager types should be included in the wager set hizi-engine-docs: updated SDK types, gamble features guide, frogger game guide, endpoints, and game flow docs