Config and flags
Config values, config tables and feature flags let you change how your game behaves without shipping a build. All of them are per environment: a value you change in test is not seen in production until you promote it there, now or in a release. See Environments and releases.
Switch the Config and Feature flags services on for your project in the console. Until you do, their routes answer service-disabled.
Config values
A config value is a key with one typed value, edited on the environment's Config page.
| Part | Rules |
|---|---|
| Key | 1 to 120 characters: letters, digits and . _ : -. Unique within the environment |
| Group | Optional, up to 120 characters. Lets a client fetch related values together |
| Type | string, int, float or bool |
| Value | Of that type. A string is at most 10,000 characters |
Saving a key that exists replaces its value and type. Deleting a key removes it from what clients read; saving the same key again brings it back.
Reading config
curl https://api.greenmindmedia.com/api/platform/v1/config/values \
-H "Authorization: Bearer $ACCESS_TOKEN"
curl "https://api.greenmindmedia.com/api/platform/v1/config/values?groupName=combat" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Either credential works: a player's access token from the client, or a server key from your server. Without groupName you get every value in the environment; with it, only that group's. A group name is 1 to 120 characters, the same as the console takes; an empty groupName= is refused with invalid-request.
The answer is a page of rows ordered by key, up to 50 unless you ask for up to 200 with limit; next is the cursor of the page after, or null on the last:
{
"next": null,
"items": [
{
"key": "maxPartySize",
"groupName": null,
"type": "int",
"valueStr": null,
"valueInt": 4,
"valueFloat": null,
"valueBool": null,
"valueJson": null
},
{
"key": "motd",
"groupName": "lobby",
"type": "string",
"valueStr": "Double XP this weekend",
"valueInt": null,
"valueFloat": null,
"valueBool": null,
"valueJson": null
}
]
}
type says which value field holds the value; the others are null. An object value is a JSON object, in valueJson, already parsed: one setting with fields of its own, such as a spawner's tuning, read whole. A weighted curve, or a grid of rows that share columns, is a config table (below), not a value. Ignore a type your client does not recognise rather than failing.
A typed reader in TypeScript:
interface ConfigRow {
key: string
groupName: string | null
type: string
valueStr: string | null
valueInt: number | null
valueFloat: number | null
valueBool: boolean | null
valueJson: { [key: string]: unknown } | null
}
function valueOf(row: ConfigRow): string | number | boolean | object | null {
switch (row.type) {
case 'string':
return row.valueStr
case 'int':
return row.valueInt
case 'float':
return row.valueFloat
case 'bool':
return row.valueBool
case 'object':
return row.valueJson
default:
return null
}
}
/** Every row, page by page. */
async function readConfig(accessToken: string): Promise<ConfigRow[]> {
const rows: ConfigRow[] = []
let cursor: string | null = null
do {
const query = cursor ? `?limit=200&cursor=${cursor}` : '?limit=200'
const response = await fetch(
`https://api.greenmindmedia.com/api/platform/v1/config/values${query}`,
{ headers: { Authorization: `Bearer ${accessToken}` } },
)
const page = (await response.json()) as { items: ConfigRow[]; next: string | null }
rows.push(...page.items)
cursor = page.next
} while (cursor)
return rows
}
const config = new Map((await readConfig(accessToken)).map((row) => [row.key, valueOf(row)]))
Values that affect a match
If every player in a match must see the same values (anything that seeds a map, sets damage, or decides a rule both sides check), have your match server read config once at the start of the match and send it to the clients. Clients that each fetch on their own can straddle a change and disagree.
Config tables
A config table is config as a grid: named rows across typed columns, for anything that is one value per row per column. Drop weights by chest level, stats by rarity, prices by region. You shape it on the environment's Config tables page: add, rename, reorder and remove rows and columns, and fill the cells in.
| Part | Rules |
|---|---|
| Key | Of the table, a row or a column: 1 to 200 characters, with no spaces, /, \, ? or %. Unique within its table |
| Column | A key, a label for people, a type (below) and any rules. Up to 64 columns |
| Row | A key and one cell per column. Up to 1,000 rows |
| Cell | A value of its column's type, or empty. A text cell is at most 2,000 characters, a JSON cell 20,000 |
Saving replaces the whole table. A row you remove stops reaching your game; one that other config still points at cannot be removed. Renaming a row keeps it the same row. A table's key is fixed once it is saved: make a new table to change it.
Column types
| Type | A cell holds |
|---|---|
string |
Text |
int |
A whole number |
float |
A number |
bool |
true or false |
enum |
One of the names the column lists, as text: rare, say |
reference |
The key of a row in another config table of the same environment, which the column names |
json |
A JSON document, as JSON text: parse the cell to read it |
Every cell your game reads is still a string, a number, a boolean or null: an enum's name, a referenced row's key and a JSON document all arrive as strings.
Column rules
Each column has a Rules drawer in the table editor. Every rule is optional, and the column's header shows which are set:
| Rule | What it does |
|---|---|
| What it is for | A description, shown beside the column in the editor and to AI assistants |
| Every row must fill it | Saving refuses a row that leaves it empty, unless the column has a default |
| When a row leaves it empty, it reads as | A default: your game reads it for every row that leaves the cell unset |
| At least, at most | Bounds for an int or float column, inclusive |
| Names it may hold | The names of an enum column |
| Table it names a row of | The table a reference column points into |
| Each environment keeps its own value | The cell is never compared or promoted between environments, as a feature flag's switch is not. Not for a reference column |
Saving checks every rule and marks the cells and columns that break one. A table saved before rules existed means what it meant: a column without rules behaves as columns always have.
Reading tables
curl https://api.greenmindmedia.com/api/platform/v1/config/tables \
-H "Authorization: Bearer $ACCESS_TOKEN"
curl https://api.greenmindmedia.com/api/platform/v1/config/tables/chest.drops \
-H "Authorization: Bearer $ACCESS_TOKEN"
Either credential works, and both need the Config service. The first lists the environment's tables a page at a time, ordered by key, as { "items": [...], "next": ... }; the second answers one table, or 404 with not-found.
{
"key": "chest.drops",
"name": "Chest drops",
"description": "What a chest holds, by chest tier",
"groupName": null,
"columns": [
{ "key": "weight", "label": "Weight", "type": "int" },
{ "key": "rare", "label": "Rare", "type": "bool" }
],
"rows": [
{ "key": "gold", "sortOrder": 0, "cells": { "weight": 10, "rare": false } },
{ "key": "gem", "sortOrder": 1, "cells": { "weight": 1, "rare": true } }
]
}
Rows come in the order they have in the editor. An empty cell is either null or missing from cells: read both as "no value", and fall back to your own default. A column added after a row was saved has no cell in that row until somebody fills it in, unless the column has a default, which every row that leaves the cell unset reads as. A column each environment keeps for itself answers with this environment's value.
A column carries its rules beside its key, label and type (description, required, default, min, max, values, table, local), each only when it is set. Read the ones you need and ignore the rest, and treat a column type your client does not know as text rather than failing: new types are added beside the old ones.
A typed reader in TypeScript:
type Cell = string | number | boolean | null
interface ConfigTable {
key: string
name: string
description: string | null
groupName: string | null
columns: {
key: string
label: string
type: string // 'string' | 'int' | 'float' | 'bool' | 'enum' | 'reference' | 'json'
description?: string
required?: boolean
default?: string | number | boolean
min?: number
max?: number
values?: string[] // an enum column's names
table?: string // the table a reference column points into
local?: boolean // each environment keeps its own value
}[]
rows: { key: string; sortOrder: number; cells: Record<string, Cell> }[]
}
const response = await fetch(
'https://api.greenmindmedia.com/api/platform/v1/config/tables/chest.drops',
{ headers: { Authorization: `Bearer ${accessToken}` } },
)
const table = (await response.json()) as ConfigTable
const weightOf = (row: string) => {
const cell = table.rows.find((each) => each.key === row)?.cells.weight
return typeof cell === 'number' ? cell : 0
}
Weighted rolls
A table whose rows are the things to roll and whose columns are weights (one per tier, level or zone) tunes a weighted roll without a build: pick the column for the roll, then draw a row with probability proportional to its cell. The editor can show each number's share of its column, which is the chance a roll in that column lands on the row.
Feature flags
A feature flag is a name that is on or off, managed on the environment's Flags page.
curl https://api.greenmindmedia.com/api/platform/v1/flags \
-H "Authorization: Bearer $ACCESS_TOKEN"
{
"items": [
{ "name": "new-shop", "isEnabled": false },
{ "name": "winter-event", "isEnabled": true }
],
"next": null
}
Either credential works. Treat a flag your client knows about but does not find as off.
Caching
Read config, tables and flags when the game starts or a match begins, not on every frame or request. Values change only when somebody edits them in the console.
Each of these answers carries an ETag. To check for a change cheaply, send it back as If-None-Match: the answer is 304 Not Modified, with no body, until something changes. A change saved, promoted or released in the console reaches the API at once; one made any other way, within 15 seconds.
curl -i https://api.greenmindmedia.com/api/platform/v1/flags \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'If-None-Match: "3x0Qj7Yk..."'
Moving config between environments
The project's Config pages compare two environments and move what you choose: promoted now from Compare, or queued in a release that goes out in one step, with a review of anything that changed in the meantime and a roll back. History shows every change applied to an environment. See Environments and releases.
A new key and a new build
Config reaches production when somebody promotes or releases it, which is not when you ship a build. So a build that reads a new key has to work before the key arrives, and after:
- Give every key your code reads a default in code, used until the key is there. Treat a missing flag as off, and a missing table row or cell as your default.
- Put the new key in a release of
production, and name the build on the release, so it goes out with the build that needs it. - Add a new key or column beside an old one rather than changing what an old one means: builds already in players' hands still read it.
Config your backend keeps
Config your own backend keeps in its own tables (anything you would rather hold beside your game's data) can still be compared, promoted and released from the console. Your backend serves them through a config connector, and the console calls it, signed. See Config connectors.