Roulette Game Responses

This guide explains how to send a roulette round to placeBet. It also explains how to read the enriched scenario object that the engine returns. Use the loadConfig ruleset to render payouts and validate bets on the client side.

Overview

Roulette is a wager game that resolves in a single placeBet call. The wheel is a European single-zero wheel with 37 pockets (0 to 36). The player places one or more bets. Each bet has its own type, selection, and stake. The engine draws a pocket. The engine settles every bet. The engine returns the result in a single response. The round has no continuation, no playerChoice step, and no collect step.

• One round = one placeBet call.
• Round stake is the sum of every bet's stake. Pass that sum as the top-level stake field. The engine validates that the two values match.
• The engine returns settlement per bet in scenario.settlement[]. It also returns enriched pocket metadata (color, odd/even, dozen, column).

Bet Types

Type	Selection shape	Winning pockets	Standard payout (total return)
straight	number (0–36)	1	36
split	[number, number]	2	18
street	number (1–12, street index)	3	12
corner	[number, number, number, number]	4	9
six_line	number (1–11, six-line index)	6	6
red	null / omit	18	2
black	null / omit	18	2
odd	null / omit	18	2
even	null / omit	18	2
low_18	null / omit (covers 1–18)	18	2
high_18	null / omit (covers 19–36)	18	2
dozen	1 (1–12), 2 (13–24), 3 (25–36)	12	3
column	1 (column 1,4,7…), 2, 3	12	3

TIP

The engine returns actual payouts in loadConfig.payouts. These may differ from the standard table. See How RTP Works below.

Selection Conventions

• Splits must be adjacent on the layout. The engine accepts [a, b] where a and b share a row or column edge. This includes the 0-row splits [0, 1], [0, 2], and [0, 3]. Order does not matter.
• Streets are indexed 1–12: street s covers pockets {3s−2, 3s−1, 3s}. Street 1 = {1, 2, 3}, street 12 = {34, 35, 36}.
• Corners are 4-pocket squares anchored at the top-left pocket. The engine validates that the four pockets form a legal 2×2 block (not column 3, not crossing the table edge).
• Six-lines are indexed 1–11: six-line s covers two adjacent streets, pockets {3s−2 … 3s+3}.

The Roulette Scenario

When placeBet returns a roulette result, gameResult.scenario contains:

interface IRouletteScenario {
  pocket: number;                     // Drawn pocket: 0–36
  color: 'red' | 'black' | 'green';   // green = pocket 0
  oddEven: 'odd' | 'even' | null;     // null when pocket = 0
  highLow: 'low_18' | 'high_18' | null;
  dozen: 1 | 2 | 3 | null;
  column: 1 | 2 | 3 | null;
  settlement: IRouletteBetSettlement[];
  totalStake: number;                 // Sum of bet stakes
  totalWin: number;                   // Sum of all winAmounts (capped by maxRoundWin)
}

interface IRouletteBetSettlement {
  type: TRouletteBetType;
  selection?: number | [number, number] | [number, number, number, number] | 1 | 2 | 3 | null;
  stake: number;
  won: boolean;
  payout: number;     // total return multiplier - stake × payout gives the full amount credited on a win
  winAmount: number;  // stake × payout on a win, 0 on a loss
}

Reading winAmount

winAmount is the total amount credited on a win: stake × payout. A won: true straight bet of 10 chips at standard payout 36 returns winAmount = 10 × 36 = 360. A losing bet has winAmount = 0. The engine does not return the stake separately, because it already debited the stake at placeBet time.

Sum across the array: scenario.totalWin === settlement.reduce((s, b) => s + b.winAmount, 0) (capped if maxRoundWin > 0).

gameResult.totalWin

gameResult.totalWin is a stake-relative multiplier, not an amount. The engine credits gameResult.totalWin × stake to the player. For roulette specifically:

gameResult.totalWin = scenario.totalWin / scenario.totalStake

Use scenario.totalWin for display. Use gameResult.totalWin only when you compute the credited amount yourself.

Game Flow

Single-Step: Place All Bets and Spin

import { placeBet, rouletteAdditionalData, type IRouletteBet } from '@hizi.io/engine-sdk';

const bets: IRouletteBet[] = [
  { type: 'straight', selection: 17, stake: 5 },
  { type: 'red',                     stake: 20 },
  { type: 'dozen', selection: 2,     stake: 10 },
];

const totalStake = bets.reduce((s, b) => s + b.stake, 0); // 35

const response = await placeBet({
  backendURL,
  token,
  stake: totalStake,
  additionalData: rouletteAdditionalData(bets), // { bets }
});

if (response.success) {
  const scenario = response.result.result.scenario as IRouletteScenario;

  console.log(`Pocket ${scenario.pocket} (${scenario.color})`);
  for (const s of scenario.settlement) {
    console.log(`  ${s.type}${s.selection != null ? ` ${JSON.stringify(s.selection)}` : ''} - ${s.won ? `won ${s.winAmount}` : 'lost'}`);
  }
  console.log(`Total: staked ${scenario.totalStake}, won ${scenario.totalWin}`);
}

The helper rouletteAdditionalData(bets) returns { bets }. You may build that object inline instead.

WARNING

The top-level stake must equal the sum of bets[].stake. If the values do not match, the engine returns INVALIDPARAMETER with "Declared stake does not match bet total."

TIP

The round resolves instantly. It needs no collect step, no playerChoice step, and no follow-up calls. One request produces one fully settled result.

Loading Game Config

loadConfig.config for a roulette game carries the ruleset:

interface IRouletteLoadConfig {
  wheelVariant: 'european';
  rtpMechanism: 'adjust_payouts' | 'adjust_odds';
  targetRTP: number;                            // e.g. 0.98
  enabledBets: Record<TRouletteBetType, boolean>;
  payouts: Record<TRouletteBetType, number>;    // total return multipliers (stake × payout = win amount)
  maxRoundStake: number;
  maxRoundWin: number;                          // 0 = uncapped
}

Using the Config Client-Side

const config = configResponse.result.config as IRouletteLoadConfig;

// Render only the bet types this ruleset enables
for (const type of Object.keys(config.enabledBets) as TRouletteBetType[]) {
  if (!config.enabledBets[type]) continue;
  const payout = config.payouts[type];
  console.log(`${type}: ${payout.toFixed(3)}×`);
}

// Pre-validate the round stake before calling placeBet
if (totalStake > config.maxRoundStake) {
  throw new Error(`Stake ${totalStake} exceeds maxRoundStake ${config.maxRoundStake}`);
}

How RTP Works

The builder can reach the target RTP in two ways. RTP means return to player: the percentage of wagered money that the game returns to players over time. The rtpMechanism setting controls which way the builder uses.

adjust_payouts (default)

Pocket weights stay uniform, at 1/37 each. The engine increases each bet type's payout so the RTP equals the target on every bet:

payout = (targetRTP × 37) / winningPockets

For 98% RTP:

Bet type	Winning pockets	Payout (total return)	EV
straight	1	36.260	0.98
split	2	18.130	0.98
street	3	12.087	0.98
corner	4	9.065	0.98
six_line	6	6.043	0.98
red/black	18	2.014	0.98
dozen/col	12	3.022	0.98

These payouts are slightly below the textbook values. This difference shows the house edge.

adjust_odds

Payouts stay at the textbook values (36 / 18 / 12 / 9 / 6 / 3 / 2). The engine reduces the pocket-0 weight so non-zero pockets cover targetRTP of the total weight:

weight(0)     = round(10000 × (1 − targetRTP))
weight(1..36) = round(10000 × targetRTP / 36)

Even-money, dozen, and column bets never include 0. These bets hit the textbook RTP exactly. Inside bets that include 0 (for example, straight on 0, or split [0,1]) have RTP below the target. This happens because the engine down-weights their winning pocket. The builder warns when this happens. The headline RTP shown in the previewer assumes a bet that does not include zero.

Validation Rules

The engine enforces the following at placeBet time. Any failure returns INVALIDPARAMETER:

• bets is a non-empty array.
• Every bet's type must be a member of enabledBets. Its value must be true.
• Every bet's stake must be finite. It must be greater than 0.
• Every bet's selection is shape-valid for its type. The engine checks splits and corners for adjacency.
• sum(bets[].stake) ≤ maxRoundStake.
• Top-level stake === sum(bets[].stake) (within 1e-9).

maxRoundWin > 0 caps scenario.totalWin to that value. This cap is silent. The engine does not report it as an error.

Pocket Color Reference

const RED_POCKETS = new Set([
  1, 3, 5, 7, 9, 12, 14, 16, 18,
  19, 21, 23, 25, 27, 30, 32, 34, 36,
]);
// Black = 1..36 minus RED_POCKETS. Green = 0.

Each spin also provides the same metadata via scenario.color, scenario.oddEven, scenario.dozen, and scenario.column. Prefer these fields when you react to a result. Do not recompute them on the client.

Complete Example

import {
  login, loadConfig, placeBet,
  rouletteAdditionalData,
  type IRouletteBet,
  type IRouletteScenario,
  type IRouletteLoadConfig,
} from '@hizi.io/engine-sdk';

// After login...
const cfgResp = await loadConfig({ backendURL, token });
const config = cfgResp.result.config as IRouletteLoadConfig;

// Player composes a round
const bets: IRouletteBet[] = [
  { type: 'straight', selection: 17, stake: 5  },
  { type: 'split',    selection: [4, 5], stake: 5 },
  { type: 'corner',   selection: [10, 11, 13, 14], stake: 5 },
  { type: 'red',                          stake: 20 },
  { type: 'dozen',    selection: 2,      stake: 10 },
];
const totalStake = bets.reduce((s, b) => s + b.stake, 0);

if (totalStake > config.maxRoundStake) throw new Error('Round stake too large');

const resp = await placeBet({
  backendURL,
  token,
  stake: totalStake,
  additionalData: rouletteAdditionalData(bets),
});

if (resp.success) {
  const scenario = resp.result.result.scenario as IRouletteScenario;

  console.log(`Wheel landed on ${scenario.pocket} (${scenario.color})`);
  for (const s of scenario.settlement) {
    if (s.won) {
      console.log(`  ✓ ${s.type} - won ${s.winAmount} at ${s.payout}×`);
    } else {
      console.log(`  ✗ ${s.type} - lost ${s.stake}`);
    }
  }
  console.log(`Net: ${scenario.totalWin - scenario.totalStake}`);
}

Provably Fair Verification

Roulette is one-shot. One weighted-index draw lands the pocket. A deterministic settlement step then pays out each bet. Use pfVerify to replay the pocket draw and the settlement from the round's seeds.

Request

Pass the round's stake and the exact bets array that the player submitted on the opening placeBet call. Both the pocket and the per-bet payouts are functions of those bets.

import { pfVerify } from '@hizi.io/engine-sdk';

const reply = await pfVerify({
  backendURL,
  token,
  serverSeed: pf.revealedServerSeed,
  clientSeed: pf.clientSeed,
  stake: 200,                     // total wagered (sum of bet stakes)
  bets: [
    { type: 'straight', selection: 17, stake: 100 },
    { type: 'red', stake: 100 },
  ],
});

Reading the response

This is a one-shot check. steps has one entry.

• rngData: one int row (the weighted pocket draw). Compare it element by element against the live pf.rngData.
• steps[0].scenario.pocket: equals the live pocket.
• steps[0].scenario.settlement: matches the live per-bet won, payout, and winAmount values, element by element.
• steps[0].totalWin: equals the live total.

if (!reply.success) return;
const { steps } = reply.result;
const pocketOk = steps[0].scenario.pocket === liveScenario.pocket;
const settleOk = deepEqual(steps[0].scenario.settlement, liveScenario.settlement);

Next Steps

• Response Handling: the IGameResult structure and engineData fields.
• Over/Under Responses: another single-call wager game.
• Hi/Lo Responses: a multi-step playerChoice game with cashout.