Types & Interfaces

Engine Types

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

typescript

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

`IGameResult`

The primary game result object returned by placeBet. Contains scenario data, engine state, and win information.

typescript

interface IGameResult {
  scenario: Record<string, unknown>;
  engineData: {
    // Fixed-odds (entries-DB) games only — omitted by rules-engine games
    // such as blackjack and crash.
    entryIndex?: number;
    scenarioInfo?: IScenarioInfo;
    spinInfo?: ISpinInfo[];
    playerChoice?: TPlayerChoiceFeatureAward[];
    currentFeature?: string;
    nextFeature?: string;
    progressionCounters?: Record<string, number>;
    canCollect?: boolean;
    inProgress: boolean;
  };
  totalWin: number;
}

Field	Type	Description
`scenario`	`Record<string, unknown>`	Your game-specific scenario data - whatever was stored during generation with hizi engine generator
`engineData`	`object`	Engine state tracking. See fields below
`engineData.entryIndex`	`number`	Index of the selected entry in the entries table. Fixed-odds games only — omitted by rules-engine games (blackjack, crash)
`engineData.scenarioInfo`	`IScenarioInfo`	Multi-result scenario progression state. Fixed-odds games only — omitted by rules-engine games (blackjack, crash)
`engineData.spinInfo`	`ISpinInfo[]`	Remaining spins per feature (free spins, bonus rounds)
`engineData.playerChoice`	`TPlayerChoiceFeatureAward[]`	Pending player choices, if any
`engineData.currentFeature`	`string`	The feature that produced this result. Absent during base game spins
`engineData.nextFeature`	`string`	Feature name for the next spin's entries. `undefined` when the round is ending
`engineData.progressionCounters`	`Record<string, number>`	Current progression counter values (0.0–1.0). See Progression Counters
`engineData.canCollect`	`boolean`	`true` when the player can call `collect()` to cash out. See Gamble Features
`engineData.inProgress`	`boolean`	`true` if more `placeBet` calls are needed to complete the round
`totalWin`	`number`	Cumulative win amount as a multiplier of stake

`IScenarioInfo`

Tracks progression through a multi-result scenario.

typescript

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).

typescript

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

Field	Type	Description
`feature`	`string`	Feature name identifying which feature entries to use
`count`	`number`	Total spins awarded for this feature (not remaining); grows on retrigger/re-entry. Remaining = `count - used`
`used`	`number`	Spins already consumed, including the current spin

`IBuyFeatureOption`

Describes an available buy-feature.

typescript

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

Field	Type	Description
`feature`	`string`	Feature name referencing the feature entries
`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 id field is added by the config, not the base type.

`ILoadConfigConfig`

Game configuration returned by loadConfig.

typescript

interface ILoadConfigConfig {
  gameCode: string;
  stakes?: number[];
  rtp: number;
  maxPayoutCap?: number;
  maxWagerableWin?: number;
  minWagerableWin?: number;
  version: string;
  buyFeatures?: (IBuyFeatureOption & { id: string })[];
  wagerFeatures?: string[];
  wagerStakeFeatures?: string[];
  progressionCounters?: IProgressionCounterConfig[];
  progressionCounterValues?: Record<string, number>;
  [key: string]: unknown;
}

Field	Type	Description
`gameCode`	`string`	Unique game identifier
`stakes`	`number[]`	Available stake amounts (optional — some games use operator-defined custom stakes)
`rtp`	`number`	Return to player percentage (e.g., `95`)
`maxPayoutCap`	`number`	Maximum payout cap (optional)
`maxWagerableWin`	`number`	Maximum win amount eligible for wagering (optional)
`minWagerableWin`	`number`	Minimum win amount eligible for wagering (optional)
`version`	`string`	Engine version string
`buyFeatures`	`(IBuyFeatureOption & { id: string })[]`	Available buy-feature options (each with an added `id` field)
`wagerFeatures`	`string[]`	Wager feature names where entry win is a relative multiplier on accumulated totalWin (e.g., `["color-red", ...]`)
`wagerStakeFeatures`	`string[]`	Wager feature names where entry win is an absolute cashout multiplier relative to stake (e.g., mines/frogger steps)
`progressionCounters`	`IProgressionCounterConfig[]`	Progression counter configs. See Progression Counters
`progressionCounterValues`	`Record<string, number>`	Current counter values from player data (0.0–1.0)

Additional fields from the engine's loadConfig.json are passed through via the index signature.

`IProgressionCounterConfig`

Configuration for a progression counter.

typescript

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 - 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 playerChoice array passed back to the client in engineData.playerChoice is typed as TPlayerChoiceAward[]. Use the isCashChoice / isFeatureChoice type guards exported from @hizi.io/engine-sdk to render each option correctly.

Response Types

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

`IPlaceBetReply`

Response from placeBet():

typescript

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

Access the game result:

typescript

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`	Game round status (stake, open/closed)
`amountToCollect`	`number`	Uncollected amount from the round

`ICollectReply`

Response from collect():

typescript

interface ICollectReply {
  amountCredited: number;
  amountToCollect: number;
  balance?: IBalanceReply;
  tokenData: ITokenData;
}

Field	Type	Description
`amountCredited`	`number`	Amount credited to the player's balance
`amountToCollect`	`number`	Amount that was requested for collection

`ILoadConfigReply`

Response from loadConfig():

typescript

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`	Game round info (for round resumption)
`freePlaysAvailable`	`IFreePlayInfo[]`	Available free plays
`previousResults`	`IGameResult[]`	Previous game results
`amountToCollect`	`number`	Uncollected amount from an in-progress round

Network Types

From @hizi.io/engine-sdk:

`TNetworkResponse<T>`

typescript

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

`TNetworkSuccess<T>`

typescript

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

`TNetworkError`

typescript

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

`IErrorResponse`

typescript

interface IErrorResponse {
  code: API_RETURNCODES;
  message: string;
  passThroughData?: unknown;
}

Field	Type	Description
`code`	`API_RETURNCODES`	Error code enum value
`message`	`string`	Human-readable error message (may be localized)
`passThroughData`	`unknown`	Optional operator-specific data

Additional Reply Types

`IConnectReply`

Response from login() and refresh():

typescript

interface IConnectReply {
  token: string;
  backendURL: string;
  refreshURL: string;
  logoutURL: string;
  webSocketURL?: string;
  balance?: IBalanceReply;
  gameSettings?: IGameSettings;
  tokenData?: ITokenData;
  freePlaysAvailable?: IFreePlayInfo[];
}

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 free plays

Supporting Types

`IBalanceReply`

typescript

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

`IBalanceEntry`

typescript

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

`IGameSettings`

Platform-level game settings provided by the operator:

typescript

interface IGameSettings {
  autoplayEnabled: boolean;
  autoplayLossLimitRequired: boolean;
  displayCoins: boolean;                // deprecated
  displayJackpotOdds: boolean;
  displayRTP: boolean;
  displayXRTP: boolean;
  forceOrientation: ForcedOrientation;  // 0 = none, 1 = landscape, 2 = portrait
  gambleEnabled: boolean;
  historyURL: string;
  homeURL: string;
  homeEnabled: boolean;
  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;
  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`

typescript

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

`IGameState`

typescript

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.

typescript

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

`IFreePlayInfo`

typescript

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

Field	Type	Description
`currency`	`string`	Currency code for the free play
`stake`	`number`	Stake amount for the free play
`count`	`number`	Number of free plays available
`feature`	`string`	Feature type for the free play (optional)

`TPlayerChoiceFeatureAward`

Describes one option in a player choice prompt:

typescript

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():

typescript

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

Method	Description
`close()`	Close the WebSocket connection and revert all API calls 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). Only close() switches back to HTTP. See WebSocket Support.

Request Option Types

`ILoginOptions`

Options for login():

typescript

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):

typescript

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:

typescript

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

Field	Type	Description
`stake`	`number`	Stake amount. Required for the first call of a game round.
`useTicket`	`boolean`	Use a free play 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:

typescript

interface ICollectOptions extends ISessionOptions {
  amount?: number;
}

Field	Type	Description
`amount`	`number`	Amount to collect. If omitted, collects the full available amount

Types & Interfaces ​

Engine Types ​

IGameResult ​

IScenarioInfo ​

ISpinInfo ​

IBuyFeatureOption ​

ILoadConfigConfig ​

IProgressionCounterConfig ​

Response Types ​

IPlaceBetReply ​

ICollectReply ​

ILoadConfigReply ​

Network Types ​

TNetworkResponse<T> ​

TNetworkSuccess<T> ​

TNetworkError ​

IErrorResponse ​

Additional Reply Types ​

IConnectReply ​

Supporting Types ​

IBalanceReply ​

IBalanceEntry ​

IGameSettings ​

IGameRoundInfo ​

IGameState ​

ITokenData ​

IFreePlayInfo ​

TPlayerChoiceFeatureAward ​

WebSocketHandler ​

Request Option Types ​

ILoginOptions ​

ISessionOptions ​

IPlaceBetOptions ​

ICollectOptions ​

Types & Interfaces

Engine Types

`IGameResult`

`IScenarioInfo`

`ISpinInfo`

`IBuyFeatureOption`

`ILoadConfigConfig`

`IProgressionCounterConfig`

Response Types

`IPlaceBetReply`

`ICollectReply`

`ILoadConfigReply`

Network Types

`TNetworkResponse<T>`

`TNetworkSuccess<T>`

`TNetworkError`

`IErrorResponse`

Additional Reply Types

`IConnectReply`

Supporting Types

`IBalanceReply`

`IBalanceEntry`

`IGameSettings`

`IGameRoundInfo`

`IGameState`

`ITokenData`

`IFreePlayInfo`

`TPlayerChoiceFeatureAward`

`WebSocketHandler`

Request Option Types

`ILoginOptions`

`ISessionOptions`

`IPlaceBetOptions`

`ICollectOptions`