Types & Interfaces

All types are exported from the main package:

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

---

IEntryConfig

This interface represents a single unique outcome group in the output file.

interface IEntryConfig {
  win?: number;
  weight: number;
  metaTags?: string[];
  featureAwards?: TFeaturesAwarded;
  progressionAwards?: Record<string, Record<number, number>>;
  progressionInfo?: IProgressionInfo;
  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	Configuration of the feature award (player choice or random choice)
progressionAwards	Record<string, Record<number, number>>	Increments for progression counters, keyed by counter name → 0-based scenario step index → fractional increment (e.g. {"scatter-collection": {"2": 0.2}}). The step index matches the engine's currentScenarioIndex. The generator attributes counter changes to the scenario step that produced them. It omits steps with no increment. See Progression Counters.
progressionInfo	IProgressionInfo	Explicit feature-run boundaries plus the flat per-step counter increments for this entry. See IProgressionInfo.
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. This is the return type of loadEntries().

type TEntries = IEntryConfig[];

---

TEntryMetadata

Entry metadata without scenario data. loadEntryMetadata() returns this type for lazy-loading patterns.

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

Field	Type	Description
entryId	number	Entry ID. Use it to correlate with the entryId field in scenarios.jsonl
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	Configuration of the feature award
progressionAwards?	Record<string, Record<number, number>>	Increments for progression counters (counter → step index → increment)
progressionInfo?	IProgressionInfo	Feature-run boundaries and flat per-step counter increments. See IProgressionInfo

---

IProgressionInfo

Explicit progression metadata baked into an entry at generation time. The runtime and the analytic RTP model then never have to derive feature-run boundaries from the scenario steps. Pass it through addResult().

interface IProgressionInfo {
  featureEnds: { name: string; scenarioIndex: number }[];
  progressionEvents: { counter: string; increment: number; scenarioIndex: number }[];
}

Field	Type	Description
featureEnds	{ name: string; scenarioIndex: number }[]	The end step of every feature run in this entry. One contiguous run of steps that share a feature produces exactly one element, at its last step. Sorted by scenarioIndex. A counter whose resetOnFeatureEnd lists name resets to 0 at this step, after the step's own increments apply.
progressionEvents	{ counter: string; increment: number; scenarioIndex: number }[]	The flat form of progressionAwards: one element per counter and step with a non-zero increment. Sorted by scenarioIndex, then by counter.

In both arrays, scenarioIndex is the 0-based step index within this entry's scenario array. It uses the same indexing as the inner keys of progressionAwards.

See Progression Counters for when to bake this field.

---

IFeatureAward

Base interface for a feature award.

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.

type TPlayerChoiceFeatureAward = IFeatureAward;

---

TRandomChoiceFeatureAward

A feature award option that the engine chooses randomly, with optional weighting.

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

Field	Type	Description
weighting	number	Relative weight for random selection. Higher values increase the chance that the engine chooses this option.

---

TFeatureAward

Union of all feature award types:

type TFeatureAward = TPlayerChoiceFeatureAward | TRandomChoiceFeatureAward;

---

IFeaturesAwardedPlayerChoice

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

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

---

IFeaturesAwardedRandomChoice

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

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

---

TFeaturesAwarded

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

type TFeaturesAwarded = IFeaturesAwardedPlayerChoice | IFeaturesAwardedRandomChoice;

---

IHiziEngineGeneratorCoreOptions

Constructor options for HiziEngineGenerator.

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

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 about 60% of volume. The generator allocates a larger budget to them for more variety. Since 0.3.0.
looseScenarioCap	boolean	false	When set to true, the generator pools the scenario cap per feature + win + featureAwards + progressionAwards + progressionInfo bucket, instead of per unique entry. This shares the budget across outcomes that differ only in incidental metaTags. Entries and weights stay unchanged. Every entry keeps at least 1 scenario. Since 0.3.0.
maxTotalScenarioRows	number	10_000_000	Hard cap on the total number of scenario rows across all features. addResult() throws when a new row would pass it.
maxEntriesPerGame	number	500_000	Hard cap on the number of unique entries across all features of the game. addResult() throws when a new entry would pass it.

---

IAddResultOptions

Options for the addResult() method.

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

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 that this outcome triggers
progressionAwards?	Record<string, Record<number, number>>	-	Increments for progression counters, keyed by counter name → 0-based scenario step index → fractional increment (e.g. { "scatter-collection": { "2": 0.2 } }). See Progression Counters.
progressionInfo?	IProgressionInfo	-	Feature-run boundaries and flat per-step counter increments for this entry. See IProgressionInfo.
weight?	number	1	Weight for this occurrence. Use this field when you import pre-aggregated data.
forced?	boolean	false	Marks this result as a forced (authored) outcome instead of a natural simulation hit. end() folds the forced weight in as max(natural, forced). A forced scenario bypasses the scenario cap, so the authored board stays replayable. The written rows carry no trace of the forcing.

---

IEndOptions

Options for the end() method. Pass these to write config and buy features alongside entries and scenarios. In Node.js, the generator automatically brotli-compresses JSONL files to .br. It then removes the raw files.

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

Field	Type	Default	Description
config?	IGameConfig	-	Game configuration to write as config.json. The generator auto-populates featureWeights if you do not set it.
buyFeatures?	IBuyFeatureEntry[]	-	Pre-resolved buy-feature pools. The generator materialises them into entries.jsonl as bf_<id> features.
buyFeatureDefinitions?	IBuyFeatureDefinition[]	-	Buy-feature definitions to auto-resolve from entry metaTags. The generator merges resolved pools with buyFeatures (if provided).

---

IBuyFeatureDefinition

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

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: the generator includes only entries with at least one matching metaTag.
metaTags	string[]	-	Meta tag names to match against entry metaTags.
metaTagWeights?	Record<string, number>	-	Tag → weighting multiplier that the generator applies to tagged entry weights. An entry that matches several tags uses the highest value. Unlisted tags default to 1.
weightOverrides?	Record<string, number>	-	Optional entry ID → weight overrides that the generator applies to tagged entries. These overrides take precedence over computed base weights.

---

IBuyFeatureEntry

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

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

Field	Type	Description
name	string	Unique buy-feature identifier (e.g. "buy-freespin"). The generator uses this identifier as the key when a player purchases the feature.
entries	{ feature: string; id: number; weight: number }[]	Weighted entry references that form 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.

---

IGameConfig

The generator writes this full game configuration to config.json. The hizi engine consumes it.

interface IGameConfig {
  gameCode: string;
  gameType?: string;
  rtp?: number;
  rng?: TRngMode;
  featureWeights?: Record<string, number>;
  minStake?: number;
  maxStake?: number;
  stakes?: number[];
  maxWagerableWin?: number;
  minWagerableWin?: number;
  features?: string[];
  buyFeatures?: IBuyFeatureConfig[];
  loadConfig?: Record<string, unknown>;
  wagerFeatures?: string[];
  wagerStakeFeatures?: string[];
  wagerChoices?: TPlayerChoiceFeatureAward[];
  enableCardGamble?: boolean;
  enableLadderGamble?: boolean;
  ladderMultipliers?: number[];
  ladderLives?: number;
  progressionCounters?: IProgressionCounterConfig[];
  maxPayout?: number;
  maxPayoutRoute?: IMaxPayoutRouteStep[];
  maxWin?: number;
  maxPayoutOdds?: number;
  maxWinOdds?: number;
  certifiedVersion?: number;
}

type TRngMode = 'fortuna' | 'pf';

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 (return to player) as a percentage (e.g. 95.97)
rng?	TRngMode	RNG (random number generator) mode. 'fortuna' (the default when you omit the field) asks the rng-fortuna service for each value. 'pf' is provably-fair mode: the engine commits a hash of its server seed up front, derives every value locally, and reveals the seed at round close so the player can re-derive it
featureWeights?	Record<string, number>	Feature name → total weight map. Use featureTotalWeights after end()
minStake?	number	Minimum allowed stake value, in base units, before the currency multiplier applies
maxStake?	number	Maximum allowed stake value, in base units, before the currency multiplier applies
stakes?	number[]	Available stake values
maxWagerableWin?	number	Maximum win amount that wager features allow
minWagerableWin?	number	Minimum win amount that the game requires before it offers 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 that the loadConfig response returns (e.g. paytable, reels)
wagerFeatures?	string[]	Feature names where entry win is a relative multiplier that applies 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 that the game offers as a playerChoice after any winning result
enableCardGamble?	boolean	Enables the built-in card gamble. hizi-engine synthesizes the wager features (card_red, card_black, card_<suit>), their wagerChoices, and every outcome at runtime, with fixed odds (red or black 2×, single suit 4×) over a fair 52-card deck. The generator does not bake them into the output files
enableLadderGamble?	boolean	Enables the built-in ladder gamble. hizi-engine synthesizes one wager feature per climbable step (ladder_1, and so on). It resolves each rung's win or bust from the fair odds that ladderMultipliers implies
ladderMultipliers?	number[]	Ladder rung win multipliers, from bottom to top. The ratio of two consecutive multipliers defines that step's payout and its fair win probability. Required when you set enableLadderGamble
ladderLives?	number	Starting lives in the ladder minigame. Cosmetic only: the engine forwards it to the client
progressionCounters?	IProgressionCounterConfig[]	Configurations for progression counters. See Progression Counters
maxPayout?	number	Maximum theoretical payout as a multiplier of stake, computed at generation time. See computeMaxPayout()
maxPayoutRoute?	IMaxPayoutRouteStep[]	Step-by-step route through the game graph that reaches maxPayout
maxWin?	number	Highest win on a single spin as a multiplier of stake (the maximum entry win across all pools), computed at generation time
maxPayoutOdds?	number	The "1 in N" denominator for the per-round probability of reaching maxPayout, computed at generation time
maxWinOdds?	number	The "1 in N" denominator for the per-round probability of reaching maxWin, computed at generation time
certifiedVersion?	number	Version of hizi-engine's certified logic that this game's data was certified against. See the note below

certifiedVersion

certifiedVersion states which version of hizi-engine's certified logic (RNG outcome selection and paytable resolution) the game's numbers were signed off against. Omit it, or set it to 0, for the baseline. The baseline is the certified logic that has been live since hizi-engine's initial certification, and it is currently the only version there is.

The hizi-engine maintainers raise the number to 1, 2, and so on each time the certified logic changes after a certification. A config therefore always states which behaviour it was certified against. hizi-engine can refuse to run a version that it does not implement.

---

IBuyFeatureConfig

Configuration for a purchasable buy-feature entry.

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

Field	Type	Description
id	string	Buy feature identifier
feature	string	Which feature database to select from
initialSpins?	number	Number of spins the game initially awards 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)
maxPayout?	number	Maximum theoretical payout as a multiplier of stake when a player buys this feature, computed at generation time

---

IProgressionCounterConfig

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

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

// 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 that matches keys in entry progressionAwards
onComplete	TProgressionAwarded	-	Award that the generator grants when the counter reaches 1.0. Each option in awards carries either { count, feature } or { winMultiplier } (cash, × stake).
stakeSpecific?	boolean	-	If true, the game maintains a separate counter per stake level. If false, the game shares one counter across all stakes
resetOnFeatureEnd?	string[]	-	Feature names whose run end would reset this counter to 0. Not enforced by the current runtime: the analytic RTP model uses this field only. See Progression Counters · resetOnFeatureEnd.

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

See Progression Counters for how you set these fields at generation time and how they interact with progressionAwards.