Configuration

Framework

config.lua

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

config.lua

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.

config.lua

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

config.lua

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:

server.cfg

setr awoken:primaryColor "#00E5FF"

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

Slots

config.lua

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

Appearance resource

config.lua

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)

config.lua

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

config.lua

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.

QBX / QBCore
ESX

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)`

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)`

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

config.lua

Config.CustomSpawnHandler = function(citizenid)
    TriggerEvent('my-spawn:client:openUI', citizenid)
end

Only called when Config.SpawnResource = 'custom'.

Logout command

config.lua

Config.EnableLogoutCommand = true

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

Cinematic intro

config.lua

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

config.lua

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

config.lua

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

config.lua

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.

QBX / QBCore
ESX

Supported: ps-housing, qbx_properties, qbx_apartments, qb-apartments, bcs_housing, 0r-apartment, okokSpawnSelector, vms_spawnselector

Supported: esx_property, ps-housing, esx_apartments, es_apartments, bcs_housing, okokSpawnSelector, vms_spawnselector, luxart-apartment

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.

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:

qbx_core/config/client.lua

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.

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:

config.lua

Config.NewPlayerNoApartmentStartCoords = vector4(-1037.11, -2736.96, 20.17, 323.76)

Delete button

config.lua

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

config.lua

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.

config.lua

Config.RandomScenarios = true   -- true = random on each slot click, false = arrow cycling in order

Each scenario entry:

config.lua

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.

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.

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 page for usage and the helper keybinds.

config_scenecreator.lua

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

config_slots.lua

Slots.List = {
    { license = "license2:abc123", totalSlots = 9 },
}

Discord role slots

config_slots.lua

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:

config_slots.lua

Slots.DeleteAccess = {
    licenses = {
        "license2:abc123",
    },
    discordRoles = {
        "1234567890",
    }
}

Webhooks

config.lua

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

config.lua

Config.Debug = false

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

Get Started

Awoken Scripts

Framework

Branding

Primary colour

Slots

Appearance resource

First character event (QB / QBX)

Spawn resource

Custom spawn handler

Logout command

Cinematic intro

Starter items

Music player

Starting apartment

Delete button

Custom HUD hook

Scenarios

Scene Creator

Slot system

Per-license overrides

Discord role slots

Delete access

Webhooks

Debug

​Framework

​Branding

​Primary colour

​Slots

​Appearance resource

​First character event (QB / QBX)

​Spawn resource

​Custom spawn handler

​Logout command

​Cinematic intro

​Starter items

​Music player

​Starting apartment

​Delete button

​Custom HUD hook

​Scenarios

​Scene Creator

​Slot system

​Per-license overrides

​Discord role slots

​Delete access

​Webhooks

​Debug

Framework

Branding

Primary colour

Slots

Appearance resource

First character event (QB / QBX)

Spawn resource

Custom spawn handler

Logout command

Cinematic intro

Starter items

Music player

Starting apartment

Delete button

Custom HUD hook

Scenarios

Scene Creator

Slot system

Per-license overrides

Discord role slots

Delete access

Webhooks

Debug