> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementlabs.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration files

> How product configuration files are written, read and preserved across updates.

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:

```text theme={null}
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.

```jsonc theme={null}
{
  "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](#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:

```text theme={null}
[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:

```jsonc theme={null}
{
  "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.

<Warning>
  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.
</Warning>

### 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.

<Warning>
  Put nothing confidential in a `client` or `shared` namespace. Those values reach every player who
  connects.
</Warning>

## Example

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

```jsonc theme={null}
{
  "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

```jsonc theme={null}
{
  "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:

```text theme={null}
[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.

```text theme={null}
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

<Warning>
  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.
</Warning>

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](/getting-started/updating) 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:

```text theme={null}
[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:

```text theme={null}
[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.

## Related

* [Languages and text](/sdk/localization): the locale files, which follow the same rules
* [Update a product or the SDK](/getting-started/updating)
* [Configuration changes have no effect](/support/configuration-not-applied)
* [What is inside a product resource](/concepts/resources)