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

> Every option in config.lua, config_slots.lua and config_scenecreator.lua explained.

## Framework

```lua config.lua theme={"dark"}
Config.Framework = 'auto'
```

`'auto'` detects frameworks in this order: `qbx_core` → `qb-core` → `es_extended`.
Set it explicitly to skip detection:

| Value    | Framework             |
| -------- | --------------------- |
| `'auto'` | Auto-detects as above |
| `'qbx'`  | QBX (qbx\_core)       |
| `'qb'`   | QBCore (qb-core)      |
| `'esx'`  | ESX (es\_extended)    |

***

## Branding

```lua config.lua theme={"dark"}
Config.ServerName = 'San Andreas'
Config.ServerTag  = 'ROLEPLAY'
Config.LogoImage  = 'img/logo.png'  -- relative to html/ - leave blank to use text fallback
```

Drop your logo into `html/img/` and point `LogoImage` at it. If left blank, the selector
displays `ServerName` and `ServerTag` as text instead.

```lua config.lua theme={"dark"}
Config.LogoTransition = true   -- show the logo during scene-fade transitions (false = plain black fade)
Config.LogoGlow       = true   -- glow effect behind the logo during transitions
Config.Warp3D         = true   -- tilt the select panels into a subtle 3D warp (false = flat UI)
```

***

## Primary colour

```lua config.lua theme={"dark"}
Config.PrimaryColor = '#00E5FF'
```

Hex colour used as the UI accent. Can also be set server-wide via convar so all Awoken resources
share one colour:

```cfg server.cfg theme={"dark"}
setr awoken:primaryColor "#00E5FF"
```

The convar takes priority over the value in `config.lua` if both are set.

***

## Slots

```lua config.lua theme={"dark"}
Config.DefaultSlots = 6   -- every player starts with this many
Config.MaxSlots     = 7   -- hard cap, Discord roles cannot exceed this
```

Individual players can be granted extra slots through Discord roles or per-license overrides
in `config_slots.lua`. See [Slot system](#slot-system) below.

***

## Appearance resource

```lua config.lua theme={"dark"}
Config.AppearanceResource = 'illenium-appearance'
```

Controls which appearance resource is used to apply saved skins to the preview ped and to
open the clothing editor for new characters.

| Value                   | Skin apply method                                                            | First character editor                                                                             |
| ----------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `'illenium-appearance'` | `setPlayerAppearance` export                                                 | `esx_skin:openSaveableMenu` (ESX) / `Config.FirstCharacterEvent` (QB)                              |
| `'fivem-appearance'`    | `setPedAppearance` export                                                    | `fivem-appearance:openMenu`                                                                        |
| `'ox_appearance'`       | `setPedAppearance` export                                                    | `Config.FirstCharacterEvent`                                                                       |
| `'sn_appearance'`       | `setAppearance` export (skins fetched via its server `getAppearance` export) | `esx_skin:resetFirstSpawn` + `esx_skin:playerRegistered` (ESX) / `Config.FirstCharacterEvent` (QB) |
| anything else / blank   | `skinchanger:loadSkin` event                                                 | `esx_skin:openSaveableMenu` if running, else `Config.FirstCharacterEvent`                          |

***

## First character event (QB / QBX)

```lua config.lua theme={"dark"}
Config.FirstCharacterEvent = 'qb-clothes:client:CreateFirstCharacter'
```

Client event fired to open the clothing editor when a brand-new character spawns for the first
time. Only used when `Config.StartingApartment = false`.

| Appearance resource   | Event                                                                         |
| --------------------- | ----------------------------------------------------------------------------- |
| `illenium-appearance` | `qb-clothes:client:CreateFirstCharacter`                                      |
| `fivem-appearance`    | `fivem-appearance:openMenu`                                                   |
| `ox_appearance`       | your resource's event                                                         |
| `sn_appearance`       | `qb-clothes:client:CreateFirstCharacter` (handled natively by sn\_appearance) |

***

## Spawn resource

```lua config.lua theme={"dark"}
Config.SpawnResource = 'auto'
```

Controls where returning characters spawn after selecting a character. New characters always
use `Config.NewPlayerNoApartmentStartCoords` or the apartment resource - this setting does
not affect them.

<Tabs>
  <Tab title="QBX / QBCore">
    | Value         | Behaviour                                                                 |
    | ------------- | ------------------------------------------------------------------------- |
    | `'qbx_spawn'` | Opens the qbx\_spawn selector                                             |
    | `'qb-spawn'`  | Opens the qb-spawn selector                                               |
    | `'um-spawn'`  | Opens the um-spawn selector                                               |
    | `'none'`      | Spawns at last saved position                                             |
    | `'auto'`      | Detects `qbx_spawn`, `qb-spawn`, `um-spawn`, or `esx-spawn` in that order |
    | `'custom'`    | Calls `Config.CustomSpawnHandler(citizenid)`                              |
  </Tab>

  <Tab title="ESX">
    | Value         | Behaviour                                                             |
    | ------------- | --------------------------------------------------------------------- |
    | `'none'`      | Spawns at last saved position (recommended for most ESX servers)      |
    | `'esx-spawn'` | Opens the esx-spawn selector                                          |
    | `'um-spawn'`  | Opens the um-spawn selector                                           |
    | `'auto'`      | Detects `um-spawn` or `esx-spawn` in that order, falls back to `none` |
    | `'custom'`    | Calls `Config.CustomSpawnHandler(citizenid)`                          |
  </Tab>
</Tabs>

To add support for a spawn resource not listed above, edit `client/spawn.lua` - it contains
instructions at the top and is the only file you need to change.

### Custom spawn handler

```lua config.lua theme={"dark"}
Config.CustomSpawnHandler = function(citizenid)
    TriggerEvent('my-spawn:client:openUI', citizenid)
end
```

Only called when `Config.SpawnResource = 'custom'`.

***

## Logout command

```lua config.lua theme={"dark"}
Config.EnableLogoutCommand = true
```

`/logout` returns a player to the character select screen. Set `false` to disable the
command for everyone.

***

## Cinematic intro

```lua config.lua theme={"dark"}
Config.CinematicIntro = {
    Enabled   = true,          -- master switch
    AllowSkip = true,          -- let the player skip with Backspace/Esc
    Weather   = 'EXTRASUNNY',  -- weather forced during the cutscene
    CutAtMs   = 16000,         -- cutscene playback time (ms) to cut at
}
```

GTA-Online-style intro for brand-new characters: after the clothing editor, the genuine
`MP_INTRO_CONCAT` cutscene plays (the plane landing) using the player's own appearance,
then hands off to the spawn script. Only runs when `Config.StartingApartment = false`.

***

## Starter items

```lua config.lua theme={"dark"}
Config.StarterItems = {
    -- { name = 'phone',   amount = 1 },
    -- { name = 'id_card', amount = 1 },
}
```

Items given to a brand-new character once, on creation. Leave empty to disable. Works with
`ox_inventory` or the framework's native inventory - item names must exist in your item list
or they're silently skipped.

***

## Music player

```lua config.lua theme={"dark"}
Config.Music = {
    Enabled    = true,   -- show the music player / settings at all
    Autoplay   = true,   -- start playing when the screen opens
    DefaultUrl = 'https://www.youtube.com/watch?v=...',  -- default track, '' = none
}
```

Background music on the character screen. Players can paste their own YouTube URL in the
Settings popup; the choice is cached client-side and used on every visit.

***

## Starting apartment

```lua config.lua theme={"dark"}
Config.StartingApartment = false
```

When `true`, new characters are handed off to your apartment or housing resource on first spawn
instead of dropping at a fixed set of coords. The resource checks which housing script is running
and triggers it automatically.

<Tabs>
  <Tab title="QBX / QBCore">
    Supported: `ps-housing`, `qbx_properties`, `qbx_apartments`, `qb-apartments`,
    `bcs_housing`, `0r-apartment`, `okokSpawnSelector`, `vms_spawnselector`
  </Tab>

  <Tab title="ESX">
    Supported: `esx_property`, `ps-housing`, `esx_apartments`, `es_apartments`,
    `bcs_housing`, `okokSpawnSelector`, `vms_spawnselector`, `luxart-apartment`
  </Tab>
</Tabs>

<Warning>
  **Only one resource may own the new-player spawn.** If your framework (or housing script) also
  runs its *own* starter-apartment flow on player load, it will fire **at the same time** as
  awoken's - you'll get two overlapping apartment/clothing screens fighting for focus.

  Pick one owner:

  * **Use an apartment/housing script** → set `Config.StartingApartment = true` here **and disable
    the framework's built-in starter apartment** (see the QBX note below).
  * **Let awoken handle it** → set `Config.StartingApartment = false`; new characters spawn at
    `NewPlayerNoApartmentStartCoords` and go straight to the clothing editor. Make sure no housing
    script auto-spawns new players on load.
</Warning>

<Note>
  **QBX setup for `qbx_properties` (or any qbx apartment script).** In `qbx_core/config/client.lua`,
  turn off qbx's own starter apartment so it doesn't run alongside awoken:

  ```lua qbx_core/config/client.lua theme={"dark"}
  startingApartment = false,
  ```

  (`useExternalCharacters = true` should also be set, which disables qbx's built-in character
  management - required for any external multicharacter resource.)

  Then set `Config.StartingApartment = true` here. awoken closes the character selector, hands the
  new character to your apartment script, and re-shows the ped for clothing customisation. With
  both set this way there's no double apartment/skin screen and the ped is visible in the editor.
</Note>

To add support for an apartment resource not listed above, edit `server/apartments.lua` - it
contains instructions at the top.

If none of those are running (or `StartingApartment = false`), the player spawns at:

```lua config.lua theme={"dark"}
Config.NewPlayerNoApartmentStartCoords = vector4(-1037.11, -2736.96, 20.17, 323.76)
```

***

## Delete button

```lua config.lua theme={"dark"}
Config.EnableDeleteButton = false
```

`false` hides the delete button for everyone by default. You can still grant delete access
to specific players or Discord roles in `config_slots.lua` without exposing it globally.

***

## Custom HUD hook

```lua config.lua theme={"dark"}
Config.CustomHud = function(bool)
    -- bool = true when the selector opens, false when it closes
    -- exports['your-hud']:setVisible(not bool)
end
```

Called when the character selector opens (`true`) or closes (`false`). Use this to hide or
show your server HUD while the selector is on screen.

***

## Scenarios

Scenarios are the background scenes players cycle through on the selector screen.

```lua config.lua theme={"dark"}
Config.RandomScenarios = true   -- true = random on each slot click, false = arrow cycling in order
```

Each scenario entry:

```lua config.lua theme={"dark"}
Config.Scenarios = {
    {
        key         = 'location_1',
        label       = 'Michaels House',
        pedCoords   = vector4(-779.20, 183.91, 71.91, 155.01),
        camCoords   = vector4(-776.00, 186.50, 72.60, 155.01),  -- optional, auto-positioned if omitted
        time        = { h = 20, m = 30 },
        weather     = 'CLEAR',
        pedScenario = 'WORLD_HUMAN_SMOKING',    -- use pedScenario OR pedAnim, not both
        -- pedAnim = { dict = 'amb@world_human_picnic@female@idle_a', clip = 'idle_a' },
        -- dof = { strength = 0.25, fnumber = 2.8, near = 0.3, far = 4.0 },  -- optional
    },
}
```

| Field         | Required | Description                                                                                                       |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `key`         | Yes      | Unique string, stored as the player's last chosen scenario                                                        |
| `label`       | Yes      | Display name shown in the UI                                                                                      |
| `pedCoords`   | Yes      | `vector4` - where the character ped stands                                                                        |
| `camCoords`   | No       | `vector4` - custom camera position. Omit to let the camera position itself                                        |
| `time`        | Yes      | `{ h = 0..23, m = 0..59 }`                                                                                        |
| `weather`     | Yes      | See valid values below                                                                                            |
| `pedScenario` | No       | Native scenario string (e.g. `WORLD_HUMAN_SMOKING`)                                                               |
| `pedAnim`     | No       | `{ dict = '...', clip = '...' }` - plays an animation instead of a scenario                                       |
| `dof`         | No       | `{ strength, fnumber, near, far }` - per-scene camera depth of field. Omit for the default subtle background blur |

Use either `pedScenario` or `pedAnim`, not both. If neither is set the ped stands idle.

<Tip>
  Don't build scenario entries by hand - run `/scenecreator` in-game (admin, ace-gated).
  It frames the camera, captures the ped spot, animation, time, weather and DOF with a live
  preview of the exact select-screen render, then exports a ready-to-paste scenario entry.
</Tip>

Valid weather strings: `CLEAR`, `EXTRASUNNY`, `CLOUDS`, `OVERCAST`, `RAIN`, `THUNDER`, `FOGGY`, `SNOWLIGHT`, `BLIZZARD`

***

## Scene Creator

Settings live in their own file, `config_scenecreator.lua`. The command is fixed as
`/scenecreator` - see the [Commands](/commands) page for usage and the helper keybinds.

```lua config_scenecreator.lua theme={"dark"}
Config.SceneCreator = {
    AcePermission = 'awoken.admin',  -- same ace as the admin panel by default
    Weathers      = { 'CLEAR', 'EXTRASUNNY', ... },  -- weathers offered in the creator
    PedScenarios  = { 'WORLD_HUMAN_SMOKING', ... },  -- scenario poses in the animation picker
    PedAnims      = { { label = '...', dict = '...', clip = '...' }, ... },  -- anim-dict poses
}
```

***

## Slot system

Slot counts resolve in this order: **per-license override → Discord role → `Config.DefaultSlots`**

### Per-license overrides

```lua config_slots.lua theme={"dark"}
Slots.List = {
    { license = "license2:abc123", totalSlots = 9 },
}
```

### Discord role slots

```lua config_slots.lua theme={"dark"}
Slots.Discord = {
    status   = true,
    botToken = 'YOUR_BOT_TOKEN',
    guildId  = 'YOUR_GUILD_ID',
    roles = {
        { id = '1234567890', totalSlots = 7 },
        { id = '0987654321', totalSlots = 8 },
    }
}
```

If a player has multiple matching roles the highest `totalSlots` wins. The bot needs
**Server Members Intent** enabled in the Discord Developer Portal - without it role fetches
will silently fail and everyone gets `Config.DefaultSlots`.

Role data is cached when the player connects. A reconnect is required for slot changes to take effect.

### Delete access

Grant delete access to specific players when `Config.EnableDeleteButton = false`:

```lua config_slots.lua theme={"dark"}
Slots.DeleteAccess = {
    licenses = {
        "license2:abc123",
    },
    discordRoles = {
        "1234567890",
    }
}
```

***

## Webhooks

```lua config.lua theme={"dark"}
Config.Webhooks = {
    playerJoin     = '',
    playerLeave    = '',
    newCharacter   = '',
}
```

Discord webhook URLs for automatic notifications. Leave a field as `''` to disable that webhook.

| Field          | Fires when                                |
| -------------- | ----------------------------------------- |
| `playerJoin`   | A player selects a character and loads in |
| `playerLeave`  | A player disconnects or logs out          |
| `newCharacter` | A new character is created                |

***

## Debug

```lua config.lua theme={"dark"}
Config.Debug = false
```

Enables extra console logging. Useful when setting up the resource for the first time.