Configuration files - Element Labs

Every Element Labs product exposes the behaviour you can change as configuration files inside its own resource directory. This page describes the rules that apply to all of them. The meaning of each key belongs to the product that ships it, and is documented on that product’s configuration pages.

Purpose

Configuration lets you change how a product behaves without altering the product itself. A product reads its configuration once, when the resource starts, and uses those values until it is restarted. Configuration files live in the configs directory of the product’s resource:

resources/[element]/element_map/
  configs/
    blips.jsonc
    camera.jsonc
    controls.jsonc
    ...

One file per namespace: a named group of related settings. The file is named after the namespace it holds. A product’s configuration pages are organised the same way, one page per file.

Options

File format

Files use the .jsonc extension: JSON that also accepts comments. Both comment styles work.

{
  "namespace": "controls",
  "configVersion": 1,
  "scope": "client",
  "values": {
    // The key a player gets before they choose their own.
    "defaultKey": "M"
  }
}

The four top-level fields are part of the file as shipped. You edit values; leave the other three as they are. scope records which side of the server the settings belong to and is explained under Client and server settings. None of the three is a switch. The file is found by its filename, and the release decides which side owns the namespace, so changing namespace or scope moves nothing. Because that would otherwise be a change with no effect and no sign of it, either one produces a warning naming the file:

[WARN ] [    Config] Config file for "controls" declares scope "server" but the release owns it as "client"; the scope cannot be changed by editing the file.

You only need the keys you change

Any key you leave out keeps the value the product shipped. This applies at every level, so you can remove a whole section and keep only the setting you care about:

{
  "namespace": "blips",
  "configVersion": 1,
  "scope": "client",
  "values": {
    "hoverScale": 1.3
  }
}

That file is complete as written. Every other blips setting keeps its shipped value. Two consequences worth knowing:

A key set to null is treated as if it were absent, so the shipped value is used. To turn a feature off, set it to false rather than null.
A key the product does not recognise is ignored. A misspelled key name produces no error and no effect: the product goes on using the shipped value. If an edit appears to do nothing, check the spelling against the product’s configuration page first.

Both cases are silent. Nothing in the console tells you that a key was skipped, so an edit that appears to do nothing is usually one of these two.

Values are not checked

Your values are passed to the product as you wrote them. There is no check that a number is within a sensible range, or that a value has the type the product expects. A string where a number belongs does not produce a startup error; it produces incorrect behaviour later, in the part of the product that reads it. Each product’s configuration pages list the accepted values and the bounds worth respecting for every key. Stay inside them.

Client and server settings

Each namespace belongs to one side of the server. The release decides which; the file’s scope field records it so you can see it without looking anything up:

`scope`	Meaning
`client`	The settings are sent to every connected player and applied in their game.
`shared`	The settings are used on both sides.
`server`	The settings stay on the server and are never sent to players.

You edit all three the same way. The distinction matters when a setting holds something private.

Put nothing confidential in a client or shared namespace. Those values reach every player who connects.

Example

A complete edited file, with a comment recording why the change was made:

{
  "namespace": "controls",
  "configVersion": 1,
  "scope": "client",
  "values": {
    // Switched from the default so it does not collide with our pause menu.
    "defaultKey": "M",
    "dragSensitivity": 1.4
  }
}

A file that does not work

{
  "namespace": "controls",
  "configVersion": 1,
  "scope": "client",
  "values": {
    "defaultKey": "M",
    "dragSensitivity": 1.4,
  }
}

The trailing comma after the last value makes the file unreadable. The result is not a partial load: the whole namespace falls back to the values the product shipped, and the console reports it once at start:

[WARN ] [    Config] Config file for "controls" missing or invalid.

Every edit in the file is lost until the syntax is corrected. The same applies to a missing bracket, an unquoted key or a missing comma between two values.

Applying changes

Configuration is read when the resource starts. An edit takes effect at the next start of that resource, and at no other moment. Nothing reloads on its own.

restart element_map

Restarting the server applies the change as well. If a product supports reloading a specific setting while it runs, that product’s own configuration page says so; assume a restart is needed otherwise.

Safety

Your edits are replaced by an update

Configuration files ship inside the release. Installing an update replaces the resource directory, including configs, with the files from the new release. Nothing preserves your edits for you.

Keep your edited files somewhere outside the resource directory (ideally in your own version control) and put them back after each update. Update a product or the SDK describes the procedure step by step.

An older file is upgraded at start

configVersion records the shape of a namespace. When a product release changes that shape, it raises the number and carries the instructions to convert an older file. If you restore a configuration file from a previous version of the product, it is converted in memory at start and the conversion is reported:

[INFO ] [    Config] [controls] migrated config v1 → v2.

The file on disk is not rewritten. Two cases are reported as errors instead, and both fall back to the values the new release shipped:

[ERROR] [    Config] [controls] missing migration step from v1 → v2; falling back to defaults.
[ERROR] [    Config] [controls] config file from newer version (3 > 2); some keys may be ignored.

The second appears when a configuration file is newer than the product reading it, usually a file restored from a later release, or a resource that was rolled back without rolling back its configuration.

Recovering from a broken file

Restore the file from the release, restart, confirm the warning is gone, then reapply your changes one key at a time. Restarting after each key tells you which one caused the problem.

Languages and text: the locale files, which follow the same rules
Update a product or the SDK
Configuration changes have no effect
What is inside a product resource

​Purpose

​Options

​File format

​You only need the keys you change

​Values are not checked

​Client and server settings

​Example

​A file that does not work

​Applying changes

​Safety

​Your edits are replaced by an update

​An older file is upgraded at start

​Recovering from a broken file

​Related

Purpose

Options

File format

You only need the keys you change

Values are not checked

Client and server settings

Example

A file that does not work

Applying changes

Safety

Your edits are replaced by an update

An older file is upgraded at start

Recovering from a broken file

Related