Types & Interfaces

Engine Types

The @hizi.io/engine-sdk package exports these types:

import type { IGameResult, IScenarioInfo, ISpinInfo, IBuyFeatureOption, ILoadConfigConfig, IProgressionEvent, TPlayerChoiceAward, TPlayerChoiceFeatureAward, TPlayerChoiceCashAward } from '@hizi.io/engine-sdk';

---

IGameResult

This is the primary game result object that placeBet returns. It contains scenario data, engine state, and win information.

interface IGameResult {
  scenario: Record<string, unknown>;
  engineData: {
    entryIndex?: number;
    scenarioInfo?: IScenarioInfo;
    spinInfo?: Array<ISpinInfo>;
    playerChoice?: TPlayerChoiceAward[];
    currentFeature?: string;
    nextFeature?: string;
    progressionCounters?: Record<string, number>;
    progressionEvents?: IProgressionEvent[];
    canCollect?: boolean;
    inProgress: boolean;
    bankedWin?: number;
    baseStake?: number;
    buyFeatureId?: string;
    version?: string;
    ladderState?: ILadderState;
  };
  totalWin: number;
}

Field	Type	Description
scenario	Record<string, unknown>	Game-specific scenario data. The hizi engine generator stores this data during generation.
engineData	object	Engine state tracking. See fields below
engineData.entryIndex	number	Index of the selected entry in the entries table. This field applies only to fixed-odds games. Rules-engine games (blackjack, crash) omit it.
engineData.scenarioInfo	IScenarioInfo	State of the progression through a multi-result scenario. This field applies only to fixed-odds games. Rules-engine games (blackjack, crash) omit it.
engineData.spinInfo	ISpinInfo[]	Total awarded and used spins per feature. Remaining = count - used.
engineData.playerChoice	TPlayerChoiceAward[]	Pending player choices. Each option is a TPlayerChoiceFeatureAward (spins) or TPlayerChoiceCashAward (win multiplier). Use the isFeatureChoice and isCashChoice type guards.
engineData.currentFeature	string	The feature that produced this result. Absent during base game spins
engineData.nextFeature	string	Name of the table the engine uses for the next spin. undefined when the round is ending
engineData.progressionCounters	Record<string, number>	Current progression counter values (0.0–1.0). See Progression Counters
engineData.progressionEvents	IProgressionEvent[]	Per-step counter increments and awards that resolved this step (cash wins, feature awards, player choice requests). Use this data to animate counter fills and award delivery.
engineData.canCollect	boolean	true when the player can call collect() to cash out. See Gamble Features
engineData.inProgress	boolean	true if the round needs more placeBet calls to complete
totalWin	number	Cumulative win amount as a multiplier of stake

---

ILadderState

interface ILadderState {
  baseWin: number;
  currentRungIndex: number;
  lives: number;
  previousRungIndex?: number;
}

baseWin is the accumulated win multiplier when the ladder starts. The configured rung multiplier acts on this value. See gamble.

The result's bankedWin is an unpaid protected multiplier. Its baseStake is the original selected monetary stake. These values survive continuations and recovery.

IScenarioInfo

Tracks progression through a multi-result scenario.

interface IScenarioInfo {
  scenarioIndex: number;
  currentScenarioIndex: number;
  inProgress: boolean;
}

Field	Type	Description
scenarioIndex	number	Which scenario was randomly selected from the entry's scenario pool
currentScenarioIndex	number	Current step in the scenario (0-based). Increments with each placeBet call
inProgress	boolean	true if the scenario has more steps to play

---

ISpinInfo

Tracks remaining spins for a feature (e.g., free spins).

interface ISpinInfo {
  feature: string;
  count: number;
  used: number;
}

Field	Type	Description
feature	string	Name of the table whose entries the engine uses
count	number	Total spins awarded for this feature, not remaining spins. This count grows on a retrigger or re-entry. Remaining spins = count - used
used	number	Spins already consumed, including the current spin

---

IBuyFeatureOption

Describes an available buy-feature.

interface IBuyFeatureOption {
  feature: string;
  price: number;
  featureRTP: number;
  initialSpins: number;
}

Field	Type	Description
feature	string	Name of the table whose entries the engine uses
price	number	Buy price as a multiplier of stake
featureRTP	number	Expected return percentage for this feature
initialSpins	number	Spins awarded on initial trigger

TIP

In ILoadConfigConfig.buyFeatures, each entry is IBuyFeatureOption & { id: string }. The config adds the id field. The base type does not include this field.

---

ILoadConfigConfig

Game configuration returned by loadConfig.

interface ILoadConfigConfig {
  gameCode: string;
  gameType?: string;
  symbolMap?: Record<string, string>;
  scenarioSchema?: number;
  stakes?: number[];
  minStake?: number;
  maxStake?: number;
  rtp: number;
  maxPayoutCap?: number;
  maxPayout?: number;
  maxPayoutOdds?: number;
  maxWin?: number;
  maxWinOdds?: number;
  maxWagerableWin?: number;
  minWagerableWin?: number;
  version: string;
  buyFeatures?: (IBuyFeatureOption & { id: string })[];
  wagerFeatures?: string[];
  wagerStakeFeatures?: string[];
  progressionCounters?: IProgressionCounterConfig[];
  progressionCounterValues?: Record<string, number>;
  ladderMultipliers?: number[];
  ladderLives?: number;
  calculatedMaxExposure?: number;
  [key: string]: unknown;
}

Field	Type	Description
gameCode	string	Unique game identifier
gameType	string	Current game vertical, including fixed-odds games. Older configurations can omit it.
stakes	number[]	Available stake amounts. This field is optional; some games use custom stakes that the operator defines.
rtp	number	Return to player percentage (e.g., 95)
maxPayoutCap	number	Maximum payout cap (optional). The engine does not set this field on a loadConfig reply. Read maxPayout for the game's own maximum payout.
maxPayout	number	Highest payout one round can accumulate, as a multiplier of stake (optional). Absent for a game with no entries table (blackjack, crash, bingo).
maxPayoutOdds	number	The "1 in N" denominator for maxPayout (optional). This field currently repeats maxWinOdds. See the warning below.
maxWin	number	Highest win one spin can pay, as a multiplier of stake (optional). This is not the round total. For that, read maxPayout.
maxWinOdds	number	The "1 in N" denominator for maxWin in ordinary play (optional). Absent when only a buy feature reaches the top prize.
maxWagerableWin	number	Maximum authoring amount eligible for wagering. The engine applies currency conversion during eligibility checks.
minWagerableWin	number	Minimum authoring amount eligible for wagering. Use the offered actions after engine checks.
minStake	number	Effective minimum stake in account units. The operator override replaces the game default. Otherwise, the engine converts the default. Optional when neither supplies a bound.
maxStake	number	Effective maximum stake in account units. The operator override replaces the game default. Otherwise, the engine converts the default. Optional when neither supplies a bound.
version	string	Engine version string
buyFeatures	(IBuyFeatureOption & { id: string })[]	Available buy-feature options (each with an added id field)
wagerFeatures	string[]	Names of wager features. For these features, the entry win is a relative multiplier on the at-risk win (for example, ["card_red", ...]).
wagerStakeFeatures	string[]	Names of wager-stake features. For these features, the entry win is an absolute cashout multiplier relative to stake (e.g., mines and frogger steps).
progressionCounters	IProgressionCounterConfig[]	Progression counter configs. See Progression Counters
progressionCounterValues	Record<string, number>	Current counter values from player data (0.0–1.0)
symbolMap	Record<string, string>	Integer-to-symbol name mapping used for scenario decompression. Present when scenarioSchema is set.
scenarioSchema	number	Schema version used to compress the scenario. When present, pass config to placeBet to decompress.

The index signature passes through additional fields from the engine's loadConfig.json.

maxPayout, maxPayoutOdds, maxWin and maxWinOdds are the four figures a certified game must state. The generator computes them and the game config carries them. Print them on the game's rules screen. A figure that a game does not have is absent from the reply. It never arrives as 0. Two cases produce an absent figure:

• The game has no entries table (blackjack, crash, bingo). It carries none of the four.
• Only a buy feature reaches the top prize. The game then carries maxWin with no maxWinOdds beside it, because an ordinary round never wins that prize.

maxPayoutOdds currently repeats maxWinOdds

The generator derives one odds value, from the chance that an ordinary round hits maxWin. It writes that same value to both fields. Nothing computes the chance of the accumulated max-payout route. For a game whose tables accumulate wins over a round, maxPayout is larger than maxWin, so maxPayoutOdds understates how rare the maximum payout is.

---

IProgressionCounterConfig

Configuration for a progression counter.

interface IProgressionCounterConfig {
  name: string;
  onComplete: TProgressionAwarded;
  stakeSpecific: boolean;
}

// Selection mode at the top level; each option is independently a feature
// spin or a cash payout. The two kinds may be mixed in the same array.
type TProgressionAwarded =
  | { type: 'playerChoice'; awards: TPlayerChoiceAward[] }
  | { type: 'randomChoice'; awards: TRandomChoiceAward[] };

type TPlayerChoiceAward =
  | TPlayerChoiceFeatureAward // { count, feature }
  | TPlayerChoiceCashAward;   // { winMultiplier }

type TRandomChoiceAward =
  | (TPlayerChoiceFeatureAward & { weighting?: number })
  | (TPlayerChoiceCashAward    & { weighting?: number });

Field	Type	Description
name	string	Counter identifier that matches keys in entry progressionAwards
onComplete	TProgressionAwarded	Award granted when the counter reaches 1.0. Each option in the awards array is independently a feature spin or cash payout.
stakeSpecific	boolean	If true, separate counter per stake level

The engine sends the playerChoice array back to the client in engineData.playerChoice. This array is typed as TPlayerChoiceAward[]. Use the isCashChoice and isFeatureChoice type guards exported from @hizi.io/engine-sdk to render each option correctly.

IProgressionEvent

Per-step progression activity in engineData.progressionEvents. One entry exists per counter that changed on the current scenario step. See Progression Counters.

interface IProgressionEvent {
  counter: string; // Counter name (matches progressionCounters)
  delta: number; // Increment applied on this step
  value: number; // Counter value after this step's delta and any reset
  cashWin?: number; // Cash awarded this step, in stake-multiplier units (already in totalWin)
  featureAwards?: TRandomChoiceFeatureAward[]; // Feature spins merged into spinInfo this step
  playerChoiceRequested?: boolean; // A completion on this step needs player input
}

Field	Type	Description
counter	string	Counter name, matching an entry in progressionCounters.
delta	number	Increment applied to the counter on this step.
value	number	Counter value after this step's increment and any reset.
cashWin	number	Present when a cash award resolves on this step. This value is in stake-multiplier units. totalWin already includes it.
featureAwards	TRandomChoiceFeatureAward[]	Present when the engine awards feature spins on this step. The engine merges these spins into spinInfo.
playerChoiceRequested	boolean	Present when a completion this step needs player input (options on engineData.playerChoice).

---

Response Types

These types come from @hizi.io/engine-sdk:

IPlaceBetReply

Response from placeBet():

interface IPlaceBetReply {
  result: IGameResult;
  tokenData: ITokenData;
  balance?: IBalanceReply;
  gameRoundInfo?: IGameRoundInfo;
  amountToCollect?: number;
}

Access the game result:

const gameResult = response.result.result; // IGameResult

Field	Type	Description
result	IGameResult	The game result with scenario data and engine state
tokenData	ITokenData	Updated token data
balance	IBalanceReply	Updated balance
gameRoundInfo	IGameRoundInfo	Gameround status (stake, open/closed)
amountToCollect	number	Uncollected amount from the round

---

ICollectReply

A successful collect can keep the round open. Read engine flags and round status. Reload outstanding amounts after partial banking.

Response from collect():

interface ICollectReply {
  amountCredited?: number;
  amountToCollect: number;
  balance?: IBalanceReply;
  tokenData: ITokenData;
  result?: IGameResult;
  gameRoundInfo?: IGameRoundInfo;
}

Field	Type	Description
amountCredited	number?	Actual wallet credit. Absent when a partial collect only banks winnings.
amountToCollect	number	Amount requested for collection

---

ILoadConfigReply

Response from loadConfig():

interface ILoadConfigReply {
  config: ILoadConfigConfig;
  tokenData: ITokenData;
  balance?: IBalanceReply;
  gameResult?: IGameResult;
  gameRoundInfo?: IGameRoundInfo;
  freePlaysAvailable?: IFreePlayInfo[];
  previousResults?: IGameResult[];
  amountToCollect?: number;
}

Field	Type	Description
config	ILoadConfigConfig	Game configuration
tokenData	ITokenData	Token data
balance	IBalanceReply	Player balance
gameResult	IGameResult	Last game result (for round resumption)
gameRoundInfo	IGameRoundInfo	Gameround info (for round resumption)
freePlaysAvailable	IFreePlayInfo[]	Available freeplays
previousResults	IGameResult[]	Previous game results
amountToCollect	number	Uncollected amount from an in-progress round

---

Network Types

From @hizi.io/engine-sdk:

TNetworkResponse<T>

type TNetworkResponse<T> = TNetworkSuccess<T> | TNetworkError;

TNetworkSuccess<T>

type TNetworkSuccess<T> = {
  result: T;
  success: true;
};

TNetworkError

type TNetworkError = {
  error: IErrorResponse;
  success: false;
};

IErrorResponse

interface IErrorResponse {
  code: string;   // stringified API_RETURNCODES value or engine-specific id
  message: string;
  passThroughData?: unknown;
}

Field	Type	Description
code	string	Machine-readable error code. Compare against API_RETURNCODES string values or recoverableErrorCodes.
message	string	Human-readable error message (may be localized)
passThroughData	unknown	Optional operator-specific data

---

Additional Reply Types

IConnectReply

login() and refresh() return the session identity in tokenData (playerId, operatorId, gameId, language, currency, currencyMultiplier, mode, gameRound). They copy eleven top-level keys and discard the rest of the raw reply. See what login() does not return.

Response from login() and refresh():

interface IConnectReply {
  token: string;
  backendURL: string;
  refreshURL: string;
  logoutURL: string;
  webSocketURL?: string;
  balance?: IBalanceReply;
  gameSettings?: IGameSettings;
  tokenData?: ITokenData;
  freePlaysAvailable?: IFreePlayInfo[];
  featuresAvailable?: { game: string; type: string; rtp: number; value: number; description?: string }[];
  operatorProtocol?: number;
}

Field	Type	Description
token	string	Session token for subsequent API calls
backendURL	string	URL for game API calls
refreshURL	string	URL for refreshing the session token
logoutURL	string	URL for logging out
webSocketURL	string	WebSocket URL (optional)
balance	IBalanceReply	Player balance
gameSettings	IGameSettings	Platform game settings
tokenData	ITokenData	Token metadata
freePlaysAvailable	IFreePlayInfo[]	Available freeplays
featuresAvailable	{ game: string; type: string; rtp: number; value: number; description?: string }[]	Purchasable feature packages available to the player (distinct from per-game buyFeatures)

---

Supporting Types

IBalanceReply

interface IBalanceReply {
  totalBalance: number;
  mode: string;
  currency: string;
  balances: IBalanceEntry[];
  discountInfo?: IDiscountInfo;
}

IBalanceEntry

interface IBalanceEntry {
  type: string;
  currency: string;
  amount: number;
}

---

IDiscountInfo and IDiscountEntry

These exported types describe balance.discountInfo. See discounts for fields and presentation requirements.

IGameSettings

See the settings reference for units, runtime variants, defaults, and required behavior. The SDK interface declares required fields, but runtime settings can be partial.

Platform-level game settings that the operator provides:

interface IGameSettings {
  autoplayEnabled: boolean;
  autoplayLossLimitRequired: boolean;
  displayCoins: boolean;
  displayJackpotOdds: boolean;
  displayRTP: boolean;
  displayXRTP: boolean;
  forceOrientation: ForcedOrientation;
  gambleEnabled: boolean;
  historyURL: string;
  homeURL: string;
  loadMsg: string;
  maxExposure: number;
  maxStake: number;
  maxPackageStake: number;
  minStake: number;
  minLoadTime: number;
  minSpinTime: number;
  multipleInstancesAllowed: boolean;
  rcDisplayWinLoss: boolean;
  rcEnabled: boolean;
  rcInterval: number;
  stopEnabled: boolean;
  topupURL: string;
  turboEnabled: boolean;
  homeEnabled: boolean;
  dynamicMinSpinTime: boolean;
  redirectTarget: 'self' | 'parent' | 'top';
  packageBuyEnabled: boolean;
  defaultStakeIndex: number;
  operatorHandlesErrors: boolean;
  displayClock: boolean;
  isSocial: boolean;
  displayCurrency: boolean;
  customStakes: number[];
  lossLimitURL: string;
  partialCollectEnabled: boolean;
  hideCompanyLogo: boolean;
  abbreviateAmounts: boolean;
  showExactRTP: boolean;
  jurisdiction: string;
  forceDefaultStake: boolean;
  disableFullScreenMobile: boolean;
  displayPaytableOnEnterGame: boolean;
  doNotStoreSettings: string[];
  sessionTimeoutInSeconds: number;
  displayNetPosition: boolean;
  hideDemoBalance: boolean;
  preventRedirect: boolean;
  refreshDisabled: boolean;
  displayWinOdds: DisplayWinOdds[];
  displaySessionTimer: boolean | string;
  skipWinsEqualToOrLessThanStake: boolean;
  reportAnimationEnd: boolean;
  launcherType: 'reelLink' | 'online';
  autoplayShowTotalStake: boolean;
  translateErrors: boolean;
  currencyToDisplay: string;
  [key: string]: unknown;
}

Additional fields

Operators may provide additional settings fields beyond those listed above. The index signature [key: string]: unknown allows any extra properties. Inspect the gameSettings object at runtime to see all available fields for your operator.

---

IGameRoundInfo

On a bought round stake carries the full purchase debit. baseStake records the underlying stake. Use IGameResult.engineData.baseStake for win multipliers. See stakes and money.

interface IGameRoundInfo {
  hash: string;
  status: string;
  stake: number;
  baseStake: number;
  mode: string;
  currency: string;
  game: string;
  currencyMultiplier?: number;
  commonRoundHash?: string;
}

---

IGameState

interface IGameState {
  hash: string;
  type: string;
  processedOn?: string;
  result?: {
    winAmount?: number;
    info: Record<string, unknown>;
  };
  amountWagered?: number;
  collected?: number;
  reason?: string;
}

---

ITokenData

Opaque token metadata. Structure varies by operator.

interface ITokenData {
  [key: string]: unknown;
}

---

IFreePlayInfo

See Freeplays for how to read, choose and spend these.

interface IFreePlayInfo {
  currency: string;
  stake: number;
  count: number;
  feature?: string;
}

Field	Type	Description
currency	string	Currency code for the freeplay
stake	number	Stake amount for the freeplay
count	number	Number of freeplays available
feature	string	Feature type for the freeplay (optional)

---

TPlayerChoiceFeatureAward

Describes one option in a player choice prompt:

type TPlayerChoiceFeatureAward = {
  count: number;
  feature: string;
};

Field	Type	Description
count	number	Number of spins awarded
feature	string	Target feature for the awarded spins

---

WebSocketHandler

Returned by enableWebSockets():

interface WebSocketHandler {
  close(): void;
  isConnected(): boolean;
}

Method	Description
close()	Close the WebSocket connection. All API calls revert to HTTP.
isConnected()	Check if the WebSocket is currently open

A dropped connection does not revert the SDK to HTTP. The next API call reopens the socket automatically (SDK 0.2.3 or later). Only close() switches back to HTTP. See WebSocket Support.

---

Request Option Types

ILoginOptions

Options for login():

interface ILoginOptions {
  loginURL: string;
  launchToken: string;
}

Field	Type	Description
loginURL	string	The operator-provided login endpoint URL
launchToken	string	Short-lived token from the launch URL query

---

ISessionOptions

Base options for authenticated requests (loadConfig, reportAnimationEnd, updateBalance):

interface ISessionOptions {
  backendURL: string;
  token: string;
}

Field	Type	Description
backendURL	string	Backend URL from login response
token	string	Session token

---

IPlaceBetOptions

Options for placeBet(). Extends ISessionOptions:

interface IPlaceBetOptions extends ISessionOptions {
  config?: ILoadConfigConfig;
  stake?: number;
  useTicket?: boolean;
  useTicketFeatureType?: string;
  featureToBuy?: string;
  playerChoiceIndex?: number;
  additionalData?: Record<string, unknown>;
}

Field	Type	Description
config	ILoadConfigConfig	Config from loadConfig(). Required to decompress the scenario field.
stake	number	Stake amount. Required for the first call of a gameround.
useTicket	boolean	Use a freeplay ticket
useTicketFeatureType	string	Feature type of the ticket
featureToBuy	string	Feature to buy (e.g., 'freespin'). Engine derives the price from the stake.
playerChoiceIndex	number	Index of the selected option when engineData.playerChoice is set
additionalData	Record<string, unknown>	Additional game-specific parameters

---

ICollectOptions

Options for collect(). Extends ISessionOptions:

interface ICollectOptions extends ISessionOptions {
  amount?: number;
  additionalData?: Record<string, unknown>;
}

Field	Type	Description
amount	number	Amount to collect. If you omit this field, the SDK collects the full available amount
additionalData	Record<string, unknown>	Additional game-specific parameters (e.g. crash betHash via crashCollectData())