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

# Configuration

# Configuration

All settings live in `config.lua`. Reload with `restart awoken_spawn` after edits.

## General

```lua theme={"dark"}
Config.debug     = false                 -- verbose logs + /spawnselect command
Config.locale    = 'en'                  -- locales/<code>.lua
Config.framework = 'auto'                -- 'auto' | 'qbox' | 'qbcore' | 'esx' | 'standalone'
```

## Brand

```lua theme={"dark"}
Config.brand = {
    serverName   = 'Awoken Roleplay',
    tagline      = 'CHOOSE YOUR ORIGIN',
    logo         = 'assets/logo.png',   -- relative to html/ OR a full URL
    primaryColor = '#00E5FF',           -- retints every accent in the UI
    darkBackdrop = false,               -- true = solid dark bg, false = see game world behind
}
```

## Open behaviour

```lua theme={"dark"}
Config.open = {
    autoOpenOnFrameworkLoad = true,
    skipForNewCharacter     = true,     -- new characters go through clothing first
    multichar               = {},       -- extra events, see Installation
    hideCharacter           = true,     -- fade the ped while the menu is open
    blurBackground          = false,    -- pause-menu blur (some servers dislike it)
    disableControls         = true,     -- lock movement + weapon input
    fadeMs                  = 400,      -- open/close/spawn fade duration

    awokenMultichar = {
        enabled             = true,
        awaitIntroCinematic = true,
        introMaxWaitMs      = 30000,
    },
}
```

## Spawn behaviour

```lua theme={"dark"}
Config.spawn = {
    setPvpDefault    = true,
    healOnSpawn      = true,
    clearWantedLevel = true,
    ownFadeIn        = true,            -- we handle DoScreenFadeIn (leave true unless another script does)
    fallbackCoords   = vec4(-269.4, -955.3, 31.2, 208.0),
}
```

## Locations

Each card supports:

| Field          | What it does                                       |
| -------------- | -------------------------------------------------- |
| `id`           | Unique key (required)                              |
| `label`        | Card title                                         |
| `sublabel`     | Short line under the title                         |
| `area`         | Region tag shown in the sidebar eyebrow            |
| `description`  | Long description in the sidebar card               |
| `coords`       | `vec4(x, y, z, heading)`                           |
| `job` / `gang` | Restrict — string or list                          |
| `ace`          | Restrict to an ACE permission                      |
| `pin`          | Manual `{ x, y }` percent override for the map pin |

```lua theme={"dark"}
Config.locations = {
    {
        id = 'legion', area = 'Los Santos',
        label = 'Legion Square', sublabel = 'Downtown Los Santos',
        description = 'The beating heart of the city.',
        coords = vec4(198.45, -809.40, 31.08, 121.63),
    },
    -- Job-locked example:
    {
        id = 'mrpd', area = 'LSPD', label = 'Mission Row PD',
        coords = vec4(441.4, -979.1, 30.7, 90.0),
        job    = { 'police', 'sheriff' },
    },
}
```

Restrictions are enforced server-side — restricted cards never reach the client.

Pins auto-project from `coords` via `Config.map.worldBounds`. If a specific pin needs manual placement, add `pin = { x = 50, y = 40 }` (percent).

## Map atlas

See the [Map](map.mdx) page for the full atlas + calibration workflow.

```lua theme={"dark"}
Config.map = {
    image       = 'assets/map.png',
    aspectRatio = { width = 1600, height = 2400 },
    worldBounds = { minX = -4279, maxX = 4966, minY = -5173, maxY = 8456 },
}
```

## Housing

Owned properties show up as spawn cards. Picking one drops the player at the property + hands off to the housing script's enter flow.

```lua theme={"dark"}
Config.housing = {
    enabled = true,
    detect  = {
        'qbx_properties',
        'qbx_apartments',
        'ps-housing',
        'qb-apartments',
        'nolag_properties',
        'awoken_apartments',
        'bcs_housing',
        'snipe-motel',
    },
}
```

Order = priority. First adapter that reports the player has properties wins.

## Discord webhook

Off when `webhook = ''`.

```lua theme={"dark"}
Config.discord = {
    webhook  = '',
    color    = 65535,           -- decimal
    username = 'Awoken Spawn',
    avatar   = '',
}
```

Posts are non-blocking — if Discord is down, spawns still complete.

## Database

Auto-migrated on start. Turn off to disable last-location persistence.

```lua theme={"dark"}
Config.database = {
    enabled = true,
    table   = 'awoken_spawn_lastchoice',
}
```