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

# Configuration (Convars)

> The authoritative reference for every atlasBridge convar — providers, UI, theme, death, debug, and Discord.

`atlasBridge` is designed to run with no configuration — it auto-detects your framework, inventory, and target system at startup. Every convar below is optional; set one only to force a choice or to enable an opt-in feature.

<Note>
  All convars use `setr` (replicated, readable client and server) **except the Discord secrets**, which use `set` so the token never reaches clients.
</Note>

## Quick reference

```cfg theme={null}
setr atlas:framework   "auto"     # auto | esx | qb | qbx | default | custom
setr atlas:inventory   "auto"     # auto | ox | qb | qs | esx | default | custom
setr atlas:ui          "own"      # own (default) | ox | framework | auto | custom
setr atlas:target      "auto"     # auto | ox | qb | own | custom
setr atlas:theme:color "#F487F4"  # any valid hex; live accent for UI + markers
setr atlas:debug       "false"    # true while testing only
# setr atlas:deathEvent "baseevents:onPlayerDied"   # only for custom death systems

# Discord (optional) — use `set`, NOT `setr`:
set atlas:discord:token "YOUR_BOT_TOKEN"
set atlas:discord:guild "YOUR_GUILD_ID"
```

## Providers

### Framework

<ParamField path="atlas:framework" default="auto" type="auto | esx | qb | qbx | default | custom">
  Selects the framework provider. `auto` detects in the order `qbx_core → es_extended → qb-core → default`. Set `custom` to load `editable/framework/{server,client}.lua`. See the [Providers](/atlas-bridge/providers) guide for detection rules and the [Custom Framework](/atlas-bridge/custom-framework) page for the adapter contract.
</ParamField>

| Value     | Resolves to                    |
| --------- | ------------------------------ |
| `auto`    | Detect automatically (default) |
| `esx`     | `es_extended`                  |
| `qb`      | `qb-core`                      |
| `qbx`     | `qbx_core`                     |
| `default` | Standalone / no framework      |
| `custom`  | Your editable adapter          |

### Inventory

<ParamField path="atlas:inventory" default="auto" type="auto | ox | qb | qs | esx | default | custom">
  Selects the inventory provider. `auto` detects in the order `ox_inventory → qb-inventory → qs-inventory → es_extended (legacy) → default`. Set `custom` to load `editable/inventory/{server,client}.lua`. See [Custom Inventory](/atlas-bridge/custom-inventory).
</ParamField>

| Value     | Resolves to                    |
| --------- | ------------------------------ |
| `auto`    | Detect automatically (default) |
| `ox`      | `ox_inventory`                 |
| `qb`      | `qb-inventory`                 |
| `qs`      | `qs-inventory`                 |
| `esx`     | ESX legacy inventory           |
| `default` | Bridge virtual inventory       |
| `custom`  | Your editable adapter          |

### Target / interaction

The target system has its **own** convar — `atlas:target`, **not** `atlas:ui:target`.

<ParamField path="atlas:target" default="auto" type="auto | ox | qb | own | custom">
  Selects the target / interaction provider. `auto` detects in the order `ox_target → qb-target → own` (the bridge's world-anchored prompts). Unlike framework/inventory, target resolves per call, so start order matters less.
</ParamField>

| Value    | Resolves to                      |
| -------- | -------------------------------- |
| `auto`   | Detect automatically (default)   |
| `ox`     | `ox_target`                      |
| `qb`     | `qb-target`                      |
| `own`    | Bridge-owned interaction prompts |
| `custom` | Your editable adapter            |

## UI

<ParamField path="atlas:ui" default="own" type="own | ox | framework | auto | custom">
  The global UI mode. The default is the bridge's **own** zero-dependency NUI — `ox_lib` is opt-in, not automatic. `ox` swaps every supported call site to `ox_lib` (which must be started); `framework` uses the framework's native notify (notifications only); `auto` resolves to `own` (kept for compatibility — it detects `ox_lib` started → `ox`, a non-default framework → `framework`, otherwise `own`). Anything a chosen provider does not implement falls back to the bridge's own NUI automatically.
</ParamField>

| Value       | Renderer                                           |
| ----------- | -------------------------------------------------- |
| `own`       | The bridge's own NUI — zero dependencies (default) |
| `ox`        | `ox_lib` (must be started)                         |
| `framework` | The framework's native notify (notifications only) |
| `auto`      | Resolves to `own`                                  |
| `custom`    | Your editable adapter (`editable/ui.lua`)          |

You can override any individual UI subsystem. A per-subsystem convar wins over the global `atlas:ui`; leaving it blank inherits `atlas:ui`. The full subsystem list is exactly:

```cfg theme={null}
setr atlas:ui:notify     "own"
setr atlas:ui:progress   "ox"
setr atlas:ui:menu       "own"
setr atlas:ui:textui     "own"
setr atlas:ui:context    "own"
setr atlas:ui:input      "own"
setr atlas:ui:skillcheck "own"
setr atlas:ui:confirm    "own"
```

| Subsystem convar      | Controls                |
| --------------------- | ----------------------- |
| `atlas:ui:notify`     | Notifications           |
| `atlas:ui:progress`   | Progress bars           |
| `atlas:ui:menu`       | List / side menus       |
| `atlas:ui:textui`     | Persistent text hint UI |
| `atlas:ui:context`    | Context menus           |
| `atlas:ui:input`      | Input dialogs           |
| `atlas:ui:skillcheck` | Skill checks            |
| `atlas:ui:confirm`    | Confirmation dialogs    |

<Note>
  The radial menu is always the bridge's own NUI and is not configurable.
</Note>

## Theme color

<ParamField path="atlas:theme:color" default="#F487F4" type="hex color">
  The accent color used across bridge UI and marker props. Accepts any valid hex string. The color is live — it follows marker-prop recolor at runtime. The true default is `#F487F4`.
</ParamField>

```cfg theme={null}
setr atlas:theme:color "#F487F4"
```

## Death detection

`atlasBridge` detects most player deaths automatically (via `CEventNetworkEntityDamage` and a health watcher). Only set this convar if your server uses a custom death/ambulance system and an Atlas resource fails to react when a player dies.

<ParamField path="atlas:deathEvent" type="event name">
  An extra death event to route through the bridge. Use the event name from your death/ambulance system. Leave it unset on a standard server.
</ParamField>

```cfg theme={null}
setr atlas:deathEvent "baseevents:onPlayerDied"
```

## Debug

<ParamField path="atlas:debug" default="false" type="true | false">
  Enables verbose detection and networking logs. Turn it on while diagnosing provider detection or net issues, then turn it off for production.
</ParamField>

```cfg theme={null}
setr atlas:debug "true"
```

## Discord

Discord is optional and disabled unless both values are set. Store these with `set`, **never** `setr`.

<ParamField path="atlas:discord:token" type="bot token (set)">
  Your Discord bot token. The bridge talks to the Discord REST API directly with no separate bot process. The token is only ever used in an `Authorization` header server-side.
</ParamField>

<ParamField path="atlas:discord:guild" type="guild id (set)">
  Your Discord server (guild) ID. Required for role and member lookups.
</ParamField>

```cfg theme={null}
set atlas:discord:token "YOUR_BOT_TOKEN"
set atlas:discord:guild "YOUR_GUILD_ID"
```

<Warning>
  Never use `setr` for the bot token. `setr` replicates values to clients, which would leak the token. Use `set` for server-only secrets. See [Permissions](/atlas-bridge/developer/permissions) for the API.
</Warning>