Load Config

config.loadConfig holds static data for your game client. Typical examples are a paytable, reel strips, or symbol names. The generator writes it into config.json at end(). The engine then returns it to the client in every loadConfig reply.

This page explains how to set loadConfig, where its keys appear in the reply, and which keys the engine itself reads. See SDK · Launch and loading for how the client fetches the reply.

Set loadConfig at end()

loadConfig is a field of IGameConfig. Its type is Record<string, unknown>, so it accepts any JSON object. Pass it inside config at end():

await generator.end({
  config: {
    gameCode: 'my-slot',
    rtp: 96.2,
    stakes: [10, 20, 50, 100],
    loadConfig: {
      paytable: {
        cherry: [0, 0, 5, 20, 50],
        bell: [0, 0, 10, 40, 100],
      },
      reels: [
        ['cherry', 'bell', 'wild'],
        ['bell', 'cherry', 'scatter'],
        ['cherry', 'wild', 'bell'],
      ],
      winlines: 20,
    },
  },
});

The generator copies config into config.json without changes. It adds only featureWeights when you do not set that field. The generator does not add, remove, or validate keys inside loadConfig.

Use only JSON values (objects, arrays, strings, numbers, booleans, null). The generator writes config.json with JSON.stringify. A function, a Map, or an undefined value does not survive this step.

Where the keys appear in the reply

The engine does not return a loadConfig object. It spreads the keys of loadConfig into the top level of the reply's config object. It then adds its own computed fields next to them.

The generator example above gives this client code:

import { loadConfig } from '@hizi.io/engine-sdk';

const loaded = await loadConfig({ backendURL, token });
if (!loaded.success) throw new Error(loaded.error.message);
const config = loaded.result.config;

config.paytable; // { cherry: [0, 0, 5, 20, 50], bell: [0, 0, 10, 40, 100] }
config.reels; // [['cherry', 'bell', 'wild'], ...]
config.winlines; // 20
config.rtp; // 96.2 (an engine field, not from loadConfig)
config.stakes; // Stakes after the currency multiplier (an engine field)

config.loadConfig; // undefined: the reply has no nested loadConfig object

The SDK types the reply as ILoadConfigConfig. That type has an index signature ([key: string]: unknown) for your own keys. Your custom keys are therefore unknown in TypeScript. Declare an interface for them and validate their shape before you use them.

Reserved key names

The engine writes its own fields after it spreads loadConfig. When a loadConfig key has the same name as an engine field, the engine value replaces your value. Do not use these names inside loadConfig:

Key	Engine behaviour
currencyMultiplier	Always set, from the session's token data
gameCode	Always set, to the game id of the session
gameType	Always set, from IGameConfig.gameType
rtp	Always set, from IGameConfig.rtp
version	Always set, to the engine version string
certifiedVersion	Always set, from IGameConfig.certifiedVersion
buyFeatures	Always written. The value is undefined when the game has no buy-features
maxWagerableWin	Always written. The value is undefined when the game has no wager features
minWagerableWin	Always written. The value is undefined when the game has no wager features
wagerFeatures	Always written. The value is undefined when the game has no wager features
wagerStakeFeatures	Always written. The value is undefined when the game has no wager-stake features
maxPayout	Set only when IGameConfig.maxPayout has a value
maxPayoutOdds	Set only when IGameConfig.maxPayoutOdds has a value
maxWin	Set only when IGameConfig.maxWin has a value
maxWinOdds	Set only when IGameConfig.maxWinOdds has a value
minStake	Set when the game config or the operator settings supply a minimum stake
maxStake	Set when the game config or the operator settings supply a maximum stake
calculatedMaxExposure	Set when the engine can calculate the maximum exposure
stakes	Set when the game has a stake list
ladderMultipliers	Set when the game enables the ladder gamble
ladderLives	Set when the game enables the ladder gamble
progressionCounters	Set when the game has progression counters
progressionCounterValues	Set when the game has progression counters

An undefined engine value also removes your key

The engine writes some fields even when they have no value (for example buyFeatures on a game without buy-features). The undefined value replaces your value. JSON serialization then drops the key. A loadConfig.buyFeatures key therefore never reaches the client, even on a game without buy-features.

The "Set only when" keys replace your value only in that condition. Do not depend on this. A later change to the game config can make the engine write the key.

Static data for each game version

The engine reads loadConfig from the published game config. It sends the same keys to every player and every session of that game version. The engine does not change loadConfig for a player, a currency, or a stake.

Do not put data for one player or one session into loadConfig. The engine supplies session data in other fields. For example, stakes, minStake, and maxStake already include the currency multiplier and the operator settings. See SDK · Stakes and money.

To change loadConfig, generate and publish a new game version.

Keys that the engine reads

For most slot games, the engine only forwards loadConfig to the client. Some game types are different. For these, the engine also reads keys from loadConfig to run the game logic. A missing or wrong key changes the outcome, or makes placeBet fail.

Game type	Keys the engine reads	Details
Any game with scenario compression	scenarioSchema, symbolMap	A numeric scenarioSchema turns on scenario minification for game types with a compression scheme. symbolMap maps each integer to a symbol name. See Scenario Compression
mines	gridSize	Board size for the mine reveal. A gridSize in the scenario has priority. The default is 25. See Mines
keno	gridSize, drawCount	Size of the number grid (default 40) and the count of drawn numbers (default 10). See Keno
roulette	The roulette ruleset (enabledBets, payouts, rtpMechanism, targetRTP, useTargetRTP)	The engine validates bets and settles them against this ruleset. See Roulette
bingo	The full bingo ruleset (rows, cols, gridSize, freeCells, columnRanges, drawCount, payMode, patterns, paytable, maxTickets)	The engine rejects an invalid ruleset at placeBet. See Bingo
blackjack	The blackjack rules	The engine applies these rules to each action. See Blackjack
crash	The crash configuration (ICrashLoadConfig)	The engine uses it for the curve and the drawn multiplier. See Crash
match	bets	The engine does not read this table. It sends it to the client without changes. See Match

The engine keeps these keys at the top level of the reply too. The client reads them from loaded.result.config, for example config.gridSize or config.payouts.

Scenario compression keys

The generator does not write scenarioSchema or symbolMap. The hizi pipeline sets them when it stores a game's scenarios minified. Do not add them to loadConfig by hand.