Tables Config Format

Overview

Tables, combined with modes, make working with user statistics flexible and precise. A table is a time-bounded container for statistics, for example:

global – statistics that accumulate indefinitely
season – statistics that reset each season
week – statistics that reset each week
day – statistics that reset each day

Each table contains all game modes, each holding its own set of user statistics. You can use table statistics independently for leaderboards or unlocks.

To learn how the game interacts with the statistics server, see the .

Adding Tables Config

To use tables, you need to:

Add table descriptions to the tables config.
Deploy configs to services.

The config supports up to 100 tables.

Warning

When a table’s time period ends, all statistics in that table are cleared. In the next time period, statistics start accumulating from zero.

Table Description Format

{
  "name": "season",
  "leaderboard": "SIMPLE",
  "public": false,
  "period": "6w",
  "indexOffset": 3,
  "timeline": [{"start": "2020-01-01T00:00:00Z", "end": "2030-01-01T00:00:00Z"}],
  "slave": {"duration": "1d", "master": "season", "timeOffset": "2w"},
  "autoSlaves": [{"weekly": { "period": "1w", "name": "week", "persistent": false }}]
}

Fields

name string required 

Name of the table. Must be unique.

leaderboard string optional 

Type of leaderboard generated for this table. Defaults to NONE.

Possible values:

NONE – no leaderboard is generated.
SIMPLE – generates a flat leaderboard without groups.
GROUPING – generates a leaderboard with groups. Use this to implement leagues or buckets. See Leaderboard Group.

public bool optional 

If true, statistics for this table are visible to other users. Defaults to false.

Note

This only applies to stats with showForAll = true and public modes. To request another user’s statistics, use the action.

period string optional 

Repeating period of the table. After each period, a new table cycle starts automatically. Only used together with timeline.

Format: a number (1–16 digits) followed by a unit suffix: h (hours), d (days), w (weeks). Example: 1w, 12h.

indexOffset positive int optional 

Offset added to the table index. Useful when removing old timeline entries – set indexOffset to the number of removed entries to keep the current season’s index unchanged. Only used together with timeline. Example.

Warning

Each table can use only one of the following parameters: timeline, autoSlaves, slave.

timeline array optional 

Array of time periods for the table, defined manually. Examples.

Each entry is an object with the following fields:

start string required : Start date of the period. Format: YYYY-MM-DDTHH:MM:SSZ. Example: 2020-05-15T11:00:00Z.
end string optional : End date of the period. If not set, the table exists indefinitely.

slave JSON object optional 

Creates a dependent table whose timeline is derived from a master table. When a new period is added to the master, the slave updates automatically. Examples.

Each entry is an object with the following fields:

master string required : Name of the master table.
duration string required : Duration of each slave period (end - start). Same format as period.
timeOffset string optional : Offset of the slave’s start time from the master’s start time. Same format as period.

autoSlaves array optional 

Array of table generators. Each element generates a sequence of tables based on a master table’s timeline. Examples.

Each element is a key-value pair where the key is the generator name and the value is an object with the following fields:

period string required : Period of each generated table. Same format as period.
name string required : Name prefix for generated tables. An index is appended automatically: week → week1, week2, etc.
persistent bool optional : If true, each generated table’s end matches the master table’s end. Otherwise end = start + period.

personalUnlockGenerators object optional 

Defines generators for personal unlocks within this table. Each key is a generator name, and the value is a generator config object with the following fields:

type string required : Type of unlocks this generator produces. Must match the personal field of the corresponding unlocks.
count positive int required : Number of unlocks to show to the player at once.
generateCount positive int required : Total number of unlocks to generate for the player to choose from.
requirement string optional : Condition that must be met to use this generator.
endsWith string optional : Name of the unlock that ends the generator sequence.
unlimited bool optional : If true, the generator can be used without limit.

"personalUnlockGenerators": {
  "common_gen": {
    "type": "common",
    "count": 1,
    "generateCount": 3
  }
}

rerolling object optional 

Configures rerolling of personal unlock choices within this table.

free positive int required : Number of free rerolls available.
addFreeForNComplete positive int optional : Grants an additional free reroll after every N completions.
rewardsSelecting positive int optional : Number of rewards the player can select during rerolling.

"rerolling": {
  "free": 1
}

statsHistory object optional 

Enables tracking of historical stat values within this table.

stat string required : Name of the stat to track.
mode string required : Name of the mode in which the stat is tracked.
deep positive int required : Number of historical records to keep.

"statsHistory": {
  "stat": "playerRating",
  "mode": "default",
  "deep": 10
}

freezeOffsetFromEnd string optional : Duration before the table’s end at which statistics become frozen. Same format as period. Example: 1h freezes stats 1 hour before the table ends.

Table Examples

Global Tables

A global table has no timeline and exists indefinitely.

global – no leaderboard, not public:

{
  "name": "global"
}

global_lb – with leaderboard and public:

{
  "name": "global_lb",
  "leaderboard": "SIMPLE",
  "public": true
}

Season Tables

season – four seasons defined manually. The fourth season is currently active (index = 4).

{
  "name": "season",
  "timeline": [
    {
      "start": "2022-10-01T00:00:00Z",
      "end": "2022-12-31T00:00:00Z"
    },
    {
      "start": "2022-12-31T00:00:00Z",
      "end": "2023-02-10T00:00:00Z"
    },
    {
      "start": "2023-03-10T00:00:00Z",
      "end": "2023-04-15T00:00:00Z"
    },
    {
      "start": "2023-05-01T00:00:00Z",
      "end": "2030-01-01T00:00:00Z"
    }
  ]
}

Index Offset

If the history of old seasons is no longer needed, remove the old entries and use indexOffset to keep the current season’s index unchanged.

season – first two seasons removed, indexOffset: 2. Active season still has index = 4.

{
  "name": "season",
  "indexOffset": 2,
  "timeline": [
    {
      "start": "2023-03-10T00:00:00Z",
      "end": "2023-04-15T00:00:00Z"
    },
    {
      "start": "2023-05-01T00:00:00Z",
      "end": "2030-01-01T00:00:00Z"
    }
  ]
}

Periodic Tables

week – repeats every week starting from 2022-10-17T00:00:00Z:

{
  "name": "week",
  "period": "1w",
  "timeline": [
    {
      "start": "2022-10-17T00:00:00Z"
    }
  ]
}

day – repeats every day starting from 2022-10-17T00:00:00Z:

{
  "name": "day",
  "period": "1d",
  "timeline": [
    {
      "start": "2022-10-17T00:00:00Z"
    }
  ]
}

Slave Tables

Slave tables are useful for tracking statistics over a specific portion of a master table’s period.

first_3_days_of_season – tracks statistics during the first 3 days of each season:

{
  "name": "first_3_days_of_season",
  "slave": {
    "master": "season",
    "duration": "3d"
  }
}

after_first_3_days – tracks statistics starting 3 days after the season begins. The slave’s timeline starts at season.start + 3d and lasts until the season ends:

{
  "name": "after_first_3_days",
  "slave": {
    "master": "season",
    "duration": "3d",
    "timeOffset": "3d"
  }
}

When a new season period is added, all slave tables update automatically.

Auto Slave Tables

tournament – generates daily tables for a 10-day tournament:

{
  "name": "tournament",
  "timeline": [
    {
      "start": "2023-05-01T12:00:00Z",
      "end": "2023-05-10T23:00:00Z"
    }
  ],
  "autoSlaves": [
    {
      "daily": { "period": "1d", "name": "tournament_day", "persistent": false }
    }
  ]
}

Generates 10 tables:

[
  {
    "name": "tournament_day1",
    "timeline": [{"start": "2023-05-01T12:00:00Z", "end": "2023-05-02T12:00:00Z"}]
  },
  {
    "name": "tournament_day2",
    "timeline": [{"start": "2023-05-02T12:00:00Z", "end": "2023-05-03T12:00:00Z"}]
  },
  {
    "name": "tournament_day10",
    "timeline": [{"start": "2023-05-10T12:00:00Z", "end": "2023-05-10T23:00:00Z"}]
  }
]