Types & Interfaces

Engine Types

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

typescript

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.

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?: TPlayerChoiceAward[];
    currentFeature?: string;
    nextFeature?: string;
    progressionCounters?: Record<string, number>;
    progressionEvents?: IProgressionEvent[];
    canCollect?: boolean;
    inProgress: boolean;
  };
  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[]`	Remaining spins per feature (free spins, bonus rounds)
`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`	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.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

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

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 config adds the id field. The base type does not include this field.

`ILoadConfigConfig`

Game configuration returned by loadConfig.

typescript

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

Field	Type	Description
`gameCode`	`string`	Unique game identifier
`gameType`	`string`	Game type for rules-engine games (e.g. `'mines'`, `'crash'`, `'keno'`, `'roulette'`). Absent for fixed-odds slot or plinko games.
`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)
`maxWagerableWin`	`number`	Maximum win amount eligible for wagering (optional)
`minWagerableWin`	`number`	Minimum win amount eligible for wagering (optional)
`minStake`	`number`	Minimum stake that the game enforces. This field is optional and differs from `gameSettings.minStake`.
`maxStake`	`number`	Maximum stake that the game enforces. This field is optional and differs from `gameSettings.maxStake`.
`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 accumulated totalWin (e.g., `["color-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.

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

typescript

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

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`	Gameround 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 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`	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>`

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

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[];
  featuresAvailable?: { game: string; type: string; rtp: number; value: number; description?: string }[];
}

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`

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 that the operator provides:

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`

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

typescript

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:

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

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

typescript

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

Types & Interfaces ​

Engine Types ​

IGameResult ​

IScenarioInfo ​

ISpinInfo ​

IBuyFeatureOption ​

ILoadConfigConfig ​

IProgressionCounterConfig ​

IProgressionEvent ​

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`

`IProgressionEvent`

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`