# Configuration (/docs/concepts/configuration)

Profiles, settings paths, environment overrides and safe config workflows.

## Profiles [#profiles]

CHUDCS2 serializes `OverlayConfig` as JSON. The baseline is `assets/config/default.json`. User profiles are discovered from the `configs/` directory beside the executable when it can be created and written. If that is not possible, the application uses the user configuration directory.

The active file can be overridden with `CHUDCS2_CONFIG`:

```bash
CHUDCS2_CONFIG=/tmp/chudcs2-debug.json ./build/chudcs2
```

Use `CHUDCS2_CONFIG_DIR` to override the directory used for profile discovery and menu settings:

```bash
CHUDCS2_CONFIG_DIR=/tmp/chudcs2-configs ./build/chudcs2
```

## Settings files [#settings-files]

| File                         | Purpose                                                                                       |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| `assets/config/default.json` | Immutable baseline copied with the build assets.                                              |
| `configs/default.json`       | Fallback profile, used unless another startup profile or file is selected.                    |
| `configs/_settings.json`     | Default profile selection and menu appearance preferences.                                    |
| `offsets.json`               | Live-reader addresses and schema fields. It is refreshed from the running game when possible. |
| `imgui.ini`                  | Dear ImGui window state.                                                                      |

Profile names are sanitized before they become filenames. Reserved stems such as `_settings` and `offsets` are not treated as user profiles.

The settings menu exposes the persisted fields in feature groups, but the docs do not duplicate all individual ranges and colors. Use `src/config.hpp` for the complete `CONFIG_FIELDS` declaration and `assets/config/default.json` for the serialized baseline.

Follow [Manage profiles](/docs/guides/profiles) for creation, selection, unsaved changes, deletion and backup steps.

## Safe workflows [#safe-workflows]

Validate `default.json` or the file selected through `CHUDCS2_CONFIG` before starting the overlay:

```bash
./build/chudcs2 --validate-config
```

Refresh offsets without launching the overlay:

```bash
sudo ./build/chudcs2 --update-offsets
```

The offset refresh keeps the existing file when the live process is unavailable or a required value cannot be resolved. Keep a copy of working profiles and `offsets.json` before changing them.

Validate a different profile by passing its file path after `--validate-config`. See [Keybinds](/docs/guides/keybinds) for profile bindings and [Game assets](/docs/guides/game-assets) for the `vpk_path` field.

Without a file argument, validation does not follow the startup profile selected in `_settings.json`. Pass that profile's path explicitly.