What format and files are required for math?

Each game mode requires a minimum of 3 files to be published successfully. The RGS performs verification checks on upload to ensure all files are correctly formatted and consistent.

Required files

1. Index file (`index.json`)

A JSON file that declares all game modes. It must be named exactly index.json and follow this structure:

{
  "modes": [
    {
      "name": "<mode_name>",
      "cost": 1.0,
      "events": "<logic_file>.jsonl.zst",
      "weights": "<lookup_table>.csv"
    }
  ]
}

Each mode entry specifies:

name - The mode identifier (e.g. "base", "bonus")
cost - The cost multiplier for this mode
events - Filename of the compressed game logic file
weights - Filename of the CSV lookup table

Example for a game with 2 modes:

{
  "modes": [
    {
      "name": "base",
      "cost": 1.0,
      "events": "books_base.jsonl.zst",
      "weights": "lookUpTable_base_0.csv"
    },
    {
      "name": "bonus",
      "cost": 100.0,
      "events": "books_bonus.jsonl.zst",
      "weights": "lookUpTable_bonus_0.csv"
    }
  ]
}

2. Lookup table (CSV)

A CSV file where each row contains three uint64 values:

simulation_number, round_probability, payout_multiplier

For example:

1,199895486317,0
2,25668581149,20
3,126752606,140

All values must be unsigned integers. This avoids misinterpretation from rounding or floating-point errors. The payout_multiplier values must exactly match those in the game logic file - they are extracted and hashed for verification.

3. Game logic (`.jsonl.zst`)

A zStandard-compressed JSON-lines file where each line represents one simulation outcome. Every line must contain these required fields:

{
  "id": 1,
  "events": [{}, ...],
  "payoutMultiplier": 1150
}

id - The simulation number
events - Array of game events for this round (the data your frontend consumes)
payoutMultiplier - The payout as an integer multiplier (e.g. 1150 = 11.5x for a mode with cost 1.0)

Verification

On upload, the RGS will:

Parse the index.json to discover all modes
Extract payoutMultiplier values from both the CSV and game logic files
Hash and compare them to ensure they match exactly

If there is any mismatch between the CSV and game logic payout multipliers, the upload will fail.

For more details, see the Math File Format documentation.