Types & Interfaces

All types are exported from the main package:

typescript

import type {
  IEntryConfig,
  TEntryMetadata,
  TEntries,
  IAddResultOptions,
  IEndOptions,
  IBuyFeatureEntry,
  IBuyFeatureDefinition,
  IFeatureAward,
  TPlayerChoiceFeatureAward,
  TRandomChoiceFeatureAward,
  TFeatureAward,
  IFeaturesAwardedPlayerChoice,
  IFeaturesAwardedRandomChoice,
  TFeaturesAwarded,
  IHiziEngineGeneratorCoreOptions,
  IGameConfig,
  IBuyFeatureConfig,
  IProgressionCounterConfig,
} from '@hizi.io/engine-generator';

`IEntryConfig`

Represents a single unique outcome group in the output file.

typescript

interface IEntryConfig {
  win?: number;
  weight: number;
  metaTags?: string[];
  featureAwards?: TFeaturesAwarded;
  progressionAwards?: Record<string, number>;
  scenarios: Record<string, unknown>[][];
}

Field	Type	Description
`win`	`number`	Payout amount for this outcome
`weight`	`number`	How many times this outcome occurred in the simulation
`metaTags`	`string[]`	Classification labels (e.g. `'big-win'`, `'no-win'`)
`featureAwards`	`TFeaturesAwarded`	Feature award configuration (player choice or random choice)
`progressionAwards`	`Record<string, number>`	Progression counter increments (e.g. `{"scatter-collection": 0.01}`). See Progression Counters.
`scenarios`	`Record<string, unknown>[][]`	Array of scenario result arrays. Each scenario is itself an array of records - a single-element array for normal spins, or multiple elements for multi-result features (e.g. sticky symbols). See Scenarios.

`TEntries`

An array of IEntryConfig. Used by in-memory accumulation mode.

typescript

type TEntries = IEntryConfig[];

`TEntryMetadata`

Entry metadata without scenario data. Returned by loadEntryMetadata() for lazy-loading patterns.

typescript

type TEntryMetadata = Omit<IEntryConfig, 'scenarios'> & {
  entryId: number;
  scenarioCount: number;
};

Field	Type	Description
`entryId`	`number`	Entry ID, used with `loadScenariosForEntry()` or `indexScenarios()`
`weight`	`number`	How many times this outcome occurred
`win?`	`number`	Payout amount
`metaTags?`	`string[]`	Classification labels
`scenarioCount`	`number`	Number of stored scenarios for this entry
`featureAwards?`	`TFeaturesAwarded`	Feature award configuration
`progressionAwards?`	`Record<string, number>`	Progression counter increments

`IFeatureAward`

Base interface for a feature award.

typescript

interface IFeatureAward {
  count: number;
  feature: string;
}

Field	Type	Description
`count`	`number`	Number of spins to award
`feature`	`string`	The feature name identifying which tables to use for these spins (e.g. `'freespin'`).

`TPlayerChoiceFeatureAward`

A feature award option the player can choose.

typescript

type TPlayerChoiceFeatureAward = IFeatureAward;

`TRandomChoiceFeatureAward`

A feature award option chosen randomly by the engine, with optional weighting.

typescript

type TRandomChoiceFeatureAward = IFeatureAward & {
  weighting?: number;
};

Field	Type	Description
`weighting`	`number`	Relative weight for random selection. Higher values mean more likely to be chosen.

`TFeatureAward`

Union of all feature award types:

typescript

type TFeatureAward = TPlayerChoiceFeatureAward | TRandomChoiceFeatureAward;

`IFeaturesAwardedPlayerChoice`

Wrapper for player-choice feature awards. The player selects which bonus to play.

typescript

interface IFeaturesAwardedPlayerChoice {
  type: 'playerChoice';
  awards: TPlayerChoiceFeatureAward[];
}

`IFeaturesAwardedRandomChoice`

Wrapper for random-choice feature awards. The engine picks the bonus option randomly.

typescript

interface IFeaturesAwardedRandomChoice {
  type: 'randomChoice';
  awards: TRandomChoiceFeatureAward[];
}

`TFeaturesAwarded`

Union of feature award wrapper types. Use the type discriminator to narrow:

typescript

type TFeaturesAwarded = IFeaturesAwardedPlayerChoice | IFeaturesAwardedRandomChoice;

`IHiziEngineGeneratorCoreOptions`

Constructor options for HiziEngineGenerator.

typescript

interface IHiziEngineGeneratorCoreOptions {
  maxScenariosPerEntry?: number;
  maxScenariosPerZeroWinEntry?: number; // since 0.3.0
  looseScenarioCap?: boolean; // since 0.3.0
}

Field	Type	Default	Description
`maxScenariosPerEntry`	`number`	`1000`	Maximum scenario snapshots per entry
`maxScenariosPerZeroWinEntry`	`number`	`2000`	Maximum scenario snapshots for zero-win (dead-spin) entries. Dead spins are ~60% of volume, so they get a larger budget for more variety. Since 0.3.0.
`looseScenarioCap`	`boolean`	`false`	Pool the scenario cap per `win + featureAwards + progressionAwards` bucket instead of per unique entry, sharing the budget across outcomes that differ only in incidental metaTags. Entries and weights are unchanged; every entry keeps ≥1 scenario. Since 0.3.0.

`IAddResultOptions`

Options for the addResult() method.

typescript

interface IAddResultOptions {
  feature?: string;
  win?: number;
  metaTags?: string[];
  featureAwards?: TFeaturesAwarded;
  progressionAwards?: Record<string, number>;
  weight?: number;
}

Field	Type	Default	Description
`feature?`	`string`	`'basegame'`	Feature name for table selection (e.g. `'basegame'`, `'freespin'`)
`win?`	`number`	-	The win amount for this outcome
`metaTags?`	`string[]`	-	Classification labels for this outcome
`featureAwards?`	`TFeaturesAwarded`	-	Feature awards triggered by this outcome
`progressionAwards?`	`Record<string, number>`	-	Progression counter increments keyed by counter name. See Progression Counters.
`weight?`	`number`	`1`	Weight for this occurrence. Useful when importing pre-aggregated data.

`IEndOptions`

Options for the end() method. Pass these to write config and buy features alongside entries and scenarios. JSONL files are automatically brotli-compressed to .br and raw files removed (Node.js).

typescript

interface IEndOptions {
  config?: IGameConfig;
  buyFeatures?: IBuyFeatureEntry[];
  buyFeatureDefinitions?: IBuyFeatureDefinition[];
}

Field	Type	Default	Description
`config?`	`IGameConfig`	-	Game configuration to write as `config.json`. `featureWeights` is auto-populated if not set.
`buyFeatures?`	`IBuyFeatureEntry[]`	-	Pre-resolved buy-feature pools, materialised into `entries.jsonl` as `bf_<id>` features.
`buyFeatureDefinitions?`	`IBuyFeatureDefinition[]`	-	Buy-feature definitions to auto-resolve from entry metaTags. Resolved pools are merged with `buyFeatures` (if provided).

`IBuyFeatureDefinition`

Definition for auto-resolving a buy-feature from entry metaTags. Pass to buildBuyFeatures() or end({ buyFeatureDefinitions }).

typescript

interface IBuyFeatureDefinition {
  id: string;
  type: 'entrypool';
  metaTags: string[];
  metaTagWeights?: Record<string, number>;
  weightOverrides?: Record<string, number>;
}

Field	Type	Default	Description
`id`	`string`	-	Buy feature identifier (e.g. `"buy-freespin"`).
`type`	`'entrypool'`	-	Resolution strategy. `entrypool`: only entries with at least one matching metaTag are included.
`metaTags`	`string[]`	-	Meta tag names to match against entry metaTags.
`metaTagWeights?`	`Record<string, number>`	-	Tag → weighting multiplier applied to tagged entry weights. An entry matching several tags uses the highest; unlisted tags default to `1`.
`weightOverrides?`	`Record<string, number>`	-	Optional entry ID → weight overrides applied to tagged entries. Takes precedence over computed base weights.

`IBuyFeatureEntry`

A purchasable buy-feature mapped to a weighted subset of entries. Materialised into entries.jsonl as a bf_<name> feature pool by end().

typescript

interface IBuyFeatureEntry {
  name: string;
  entries: { feature: string; id: number; weight: number }[];
}

Field	Type	Description
`name`	`string`	Unique buy-feature identifier (e.g. `"buy-freespin"`). Used as the key when a player purchases.
`entries`	`{ feature: string; id: number; weight: number }[]`	Weighted entry references forming this buy-feature's selection pool.

Each object in entries:

Field	Type	Description
`feature`	`string`	Feature name the entry belongs to (e.g. `"freespin"`).
`id`	`number`	Row ID of the entry in the feature's entries JSONL.
`weight`	`number`	Selection weight — higher values make this entry more likely when the buy-feature triggers.

Full game configuration written to config.json and consumed by the hizi engine.

typescript

interface IGameConfig {
  gameCode: string;
  gameType?: string;
  rtp?: number;
  featureWeights?: Record<string, number>;
  stakes?: number[];
  maxWagerableWin?: number;
  minWagerableWin?: number;
  features?: string[];
  buyFeatures?: IBuyFeatureConfig[];
  loadConfig?: Record<string, unknown>;
  wagerFeatures?: string[];
  wagerStakeFeatures?: string[];
  wagerChoices?: TPlayerChoiceFeatureAward[];
  progressionCounters?: IProgressionCounterConfig[];
}

Field	Type	Description
`gameCode`	`string`	Unique game identifier
`gameType?`	`string`	Game type identifier (e.g. `'slot'`, `'mines'`, `'crash'`, `'keno'`, `'plinko'`, `'hilo'`, `'dice'`)
`rtp?`	`number`	Game RTP as a percentage (e.g. `95.97`)
`featureWeights?`	`Record<string, number>`	Feature name → total weight map. Use `featureTotalWeights` after `end()`
`stakes?`	`number[]`	Available stake values
`maxWagerableWin?`	`number`	Maximum win amount allowed through wager features
`minWagerableWin?`	`number`	Minimum win amount required to offer a wager
`features?`	`string[]`	Extra feature names beyond basegame. Order determines play priority
`buyFeatures?`	`IBuyFeatureConfig[]`	Purchasable buy-feature configurations
`loadConfig?`	`Record<string, unknown>`	Static data returned in the `loadConfig` response (e.g. paytable, reels)
`wagerFeatures?`	`string[]`	Feature names where entry win is a relative multiplier applied to accumulated `totalWin`
`wagerStakeFeatures?`	`string[]`	Feature names where entry win is an absolute cashout multiplier relative to stake. Use for multi-step wager chains (e.g. mines picks). See Wager Stake Features
`wagerChoices?`	`TPlayerChoiceFeatureAward[]`	Wager options offered as a playerChoice after any winning result
`progressionCounters?`	`IProgressionCounterConfig[]`	Progression counter configurations. See Progression Counters

`IBuyFeatureConfig`

Configuration for a purchasable buy-feature entry.

typescript

interface IBuyFeatureConfig {
  id: string;
  feature: string;
  initialSpins?: number;
  targetRtp: number;
  targetPrice: number;
}

Field	Type	Description
`id`	`string`	Buy feature identifier
`feature`	`string`	Which feature DB to select from
`initialSpins?`	`number`	Number of spins initially awarded on the feature
`targetRtp`	`number`	Expected return percentage when buying this feature
`targetPrice`	`number`	Price as a multiplier of stake (e.g. `100` = 100× stake)

`IProgressionCounterConfig`

Configuration for a progression counter that triggers awards when it reaches 1.0.

typescript

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

// Selection mode (`playerChoice` or `randomChoice`) is at the top level;
// each option in `awards` 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 = IFeatureAward | ICashAward;
//                                   { count, feature } | { winMultiplier }

type TRandomChoiceAward = TPlayerChoiceAward & { weighting?: number };

Field	Type	Default	Description
`name`	`string`	-	Counter name — matches keys in entry `progressionAwards`
`onComplete`	`TProgressionAwarded`	-	Award granted when the counter reaches 1.0. Each option in `awards` carries either `{ count, feature }` or `{ winMultiplier }` (cash, × stake).
`stakeSpecific?`	`boolean`	-	If `true`, maintain a separate counter per stake level. If `false`, counter is shared across all stakes

Use the isCashAward / isFeatureAward type guards (exported from @hizi.io/engine-generator) to discriminate a single option at runtime.

Types & Interfaces ​

IEntryConfig ​

TEntries ​

TEntryMetadata ​

IFeatureAward ​

TPlayerChoiceFeatureAward ​

TRandomChoiceFeatureAward ​

TFeatureAward ​

IFeaturesAwardedPlayerChoice ​

IFeaturesAwardedRandomChoice ​

TFeaturesAwarded ​

IHiziEngineGeneratorCoreOptions ​

IAddResultOptions ​

IEndOptions ​

IBuyFeatureDefinition ​

IBuyFeatureEntry ​

IBuyFeatureConfig ​

IProgressionCounterConfig ​

Types & Interfaces

`IEntryConfig`

`TEntries`

`TEntryMetadata`

`IFeatureAward`

`TPlayerChoiceFeatureAward`

`TRandomChoiceFeatureAward`

`TFeatureAward`

`IFeaturesAwardedPlayerChoice`

`IFeaturesAwardedRandomChoice`

`TFeaturesAwarded`

`IHiziEngineGeneratorCoreOptions`

`IAddResultOptions`

`IEndOptions`

`IBuyFeatureDefinition`

`IBuyFeatureEntry`

`IBuyFeatureConfig`

`IProgressionCounterConfig`