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

# How configuration works

> Edit a product's settings files, what happens to the keys you leave out, and the mistakes that fail silently.

Every product keeps its settings in `.jsonc` files in its `configs` folder, one file per area of the
product. This page covers the rules every one of those files follows. What each setting does is on
the product's own **Configuration** pages, one page per file.

## Before you start

* The product is installed. See [Install a product](https://docs.elementlabs.net/get-started/install.md).
* A text editor that shows syntax errors in JSON, such as Visual Studio Code. Most mistakes on this
  page are visible there before the server ever reads the file.

## Steps

**1. Open the file for the area you want to change**

For example `resources/[element]/element_3d_pausemenu/configs/menu.jsonc`. The product's
configuration overview lists every file and what it controls.

**2. Change the value under values**

Keep the key names and the nesting exactly as they are. Change only the value.

**3. Restart the resource**

```text theme={null}
restart element_3d_pausemenu
```

Settings are read when the resource starts and at no other time. A full server restart works too.
A product page says so when one of its settings applies without a restart.

## Check that it worked

* The console shows no `Config file for "…" missing or invalid` line for that file.
* What you changed is different in game.

Both checks matter. A misspelled key produces a clean console and no change.

## What a file looks like

```jsonc theme={null}
{
  "namespace": "menu",
  "configVersion": 1,
  "scope": "client",
  "values": {
    // The key that opens the menu for a player who has not chosen their own.
    "open": { "key": "ESCAPE" },
    "startTab": "map",
    "blur": { "enabled": true, "fadeMs": 250 }
  }
}
```

| Field | What it is | Edit it |
| - | - | - |
| `values` | The settings. | Yes. This is the only part you change. |
| `namespace` | The file's name without `.jsonc`. | No. The file is found by its name; changing this field changes nothing and prints a warning. |
| `configVersion` | Which layout of the file this is. The product uses it to convert a file from an older release. | No. |
| `scope` | Who receives these settings. See [Settings players can read](#settings-players-can-read). | No. The release decides it; changing this field changes nothing and prints a warning. |

Comments are allowed, both `// a line` and `/* a block */`.

## Keep only the keys you change

Any key you leave out keeps the value the release shipped. That holds at every level, so a file can
be as short as this:

```jsonc theme={null}
{
  "namespace": "menu",
  "configVersion": 1,
  "scope": "client",
  "values": {
    "blur": { "enabled": false }
  }
}
```

Every other `menu` setting, including `blur.fadeMs`, keeps its shipped value. A short file is also
easier to carry across an update, because it only holds your decisions.

Two exceptions:

* **A list replaces the shipped list.** A value in square brackets is not merged with the shipped
  one: the whole list is yours. To add one entry, copy the shipped list and add to it.
* **`null` means "use the shipped value".** To turn a feature off, set it to `false`, not `null`.

## Mistakes that fail without a message

| Mistake | What happens |
| - | - |
| A misspelled key, or one in the wrong place in the nesting | Ignored. The shipped value stays in effect. |
| A key that a newer release renamed | Ignored, the same way. The patch notes list every rename under **Action required**. |
| A value of the wrong type, such as `"50"` where `50` belongs | Passed to the product as written. Values are not checked, so the result is wrong behaviour later, not an error. Use the accepted values on the product's page. |
| A setting placed in a different file | Ignored. Each file holds only the settings of its own area. |

## Mistakes the console reports

A syntax error makes the whole file unreadable. Not a part of it: **every** setting in that file goes
back to its shipped value, and the console says so once at start:

```text theme={null}
[WARN ] [    Config] Config file for "menu" missing or invalid.
```

The usual causes are a comma after the last value, a missing bracket or quote, or a missing comma
between two values. This file is broken by the comma after `"map"`:

```jsonc theme={null}
{
  "values": {
    "open": { "key": "ESCAPE" },
    "startTab": "map",
  }
}
```

Every message about configuration files, and what to do about each, is in
[Console messages](https://docs.elementlabs.net/troubleshooting/console-messages.md#configuration-and-language-files).

## Settings players can read

`scope` tells you who receives the settings in a file:

| `scope` | Meaning |
| - | - |
| `client` | Sent to every player who connects, and used in their game. |
| `shared` | Used on the server and sent to every player. |
| `server` | Stays on the server. Never sent to players. |

> [!WARNING]
>
> Put nothing private, such as a webhook address or a password, in a `client` or `shared` file. Every
> player who connects receives it.

## Updates replace your files

An update replaces the whole product folder, `configs` included. Keep a copy of every file you edit
and follow [Update a product](https://docs.elementlabs.net/get-started/update.md). When a release changes the layout of a file,
your older copy is converted automatically when the product starts, and the console says so.

## Recover from a broken file

Put back the file from the release, restart and confirm the warning is gone. Then add your changes
back one at a time, restarting after each. The first one that brings the warning back is the
problem.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.