Configuration Reference

Table of Contents

• Character Slots
• Spawn Settings
• Name Validation
• Age Validation
• Nationality
• Scene Configuration
• Logout Settings
• External Links
• Announcements
• Complete Example

---

Character Slots

Control how many characters players can create.

-- Default character slots for all players
Config.DefaultNumberOfCharacters = 5

-- Override slots for specific players (by license)
Config.PlayersNumberOfCharacters = {
    { license = 'license:abc123def456', numberOfChars = 10 },
    { license = 'license:xyz789ghi012', numberOfChars = 8 },
}

Option	Type	Default	Description
DefaultNumberOfCharacters	number	5	Default character slots for all players
PlayersNumberOfCharacters	table		Per-player slot overrides

---

Spawn Settings

Configure how characters spawn after selection.

-- Skip spawn selection screen (use last position)
Config.SkipSelection = false

-- Default spawn location (used for new characters without apartments)
Config.DefaultSpawn = vector4(-1035.71, -2731.87, 12.86, 0.0)

-- Enable character deletion from the UI
Config.EnableDeleteButton = true

Option	Type	Default	Description
SkipSelection	boolean	false	Skip qb-spawn selection, spawn at last position
DefaultSpawn	vector4	Airport	Fallback spawn location
EnableDeleteButton	boolean	true	Show delete button in character UI

Spawn Flow

The spawn flow depends on your configuration and installed resources:

New Characters:

1. If qb-apartments is installed and has a starting apartment → Opens apartment selection
2. Otherwise → Spawns at Config.DefaultSpawn

Existing Characters:

1. If Config.SkipSelection is true → Spawns at last saved position
2. If qb-spawn is installed → Opens spawn selection UI
3. Otherwise → Spawns at last saved position or Config.DefaultSpawn

---

Name Validation

Configure character name requirements.

Config.NameLength = {
    min = 2,   -- Minimum characters
    max = 20,  -- Maximum characters
}

Option	Type	Default	Description
min	number	2	Minimum name length
max	number	20	Maximum name length

Name Rules

Names are validated with the following rules:

• Must be between min and max length
• Must start with a letter
• Can only contain: letters, spaces, hyphens, apostrophes
• Examples: "John", "Mary-Jane", "O'Brien", "Van Der Berg"

---

Age Validation

Configure the allowed age range for characters.

Config.AgeRange = {
    min = 18,  -- Minimum age
    max = 80,  -- Maximum age
}

Option	Type	Default	Description
min	number	18	Minimum character age
max	number	80	Maximum character age

Age is calculated from the date of birth entered during character creation.

---

Nationality

Configure how nationality is entered.

-- false = dropdown with preset options
-- true = freeform text input
Config.customNationality = false

Option	Type	Default	Description
customNationality	boolean	false	Enable freeform nationality input

When false, players select from a dropdown list. When true, players can type any nationality (2-50 characters).

---

Scene Configuration

Scenes provide the background environment for character selection.

Basic Structure

Config.Scenes = {
    default = 'apartment',  -- Default scene on first load
    list = {
        -- Scene definitions here
    },
}

Scene Definition

Each scene requires the following properties:

apartment = {
    name = 'Apartment',  -- Display name in scene selector

    -- Camera settings
    cam = {
        coords = vector3(-784.7750, 340.0801, 211.3950),
        rotation = vector3(0.682074, 0.0, 222.697968),
        fov = 40.0,
    },

    -- Primary ped position (required)
    ped = {
        coords = vector4(-781.3235, 336.4592, 210.1991, 355.3351),
        animation = { dict = 'timetable@ron@ig_3_couch', name = 'base' },
    },

    -- Additional ped positions (optional)
    ped_2 = {
        coords = vector4(-780.0191, 337.0320, 210.1972, 87.4483),
        animation = { dict = 'timetable@ron@ig_3_couch', name = 'base' },
        -- Optional: custom camera for this spot
        rotation = vector3(0.682074, 0.0, 240),
        fov = 30.0,
    },
    ped_3 = { ... },
    ped_4 = { ... },

    -- Optional: preview vehicle
    vehicle = {
        model = 'zentorno',
        coords = vector4(999.2031, -2993.1677, -41.0713, 54.7334),
    },
    -- Or nil for no vehicle:
    vehicle = nil,

    -- Environment settings
    weather = 'EXTRASUNNY',
    time = { hour = 20, minute = 0 },
}

Scene Properties Reference

Property	Type	Required	Description
name	string	Yes	Display name in scene selector
cam.coords	vector3	Yes	Camera position
cam.rotation	vector3	Yes	Camera rotation (pitch, roll, yaw)
cam.fov	number	Yes	Camera field of view
ped.coords	vector4	Yes	Primary ped position (x, y, z, heading)
ped.animation	table	Yes	Animation dict and name
ped_2, ped_3, etc.	table	No	Additional character positions
vehicle.model	string	No	Vehicle model name
vehicle.coords	vector4	No	Vehicle position and heading
weather	string	No	Weather override
time.hour	number	No	Time override (0-23)
time.minute	number	No	Time override (0-59)

Ped Spot Camera Override

Each ped spot can have its own camera settings. When a character is selected, the camera transitions to that spot's camera (or uses the scene's default camera).

ped_2 = {
    coords = vector4(-780.0191, 337.0320, 210.1972, 87.4483),
    animation = { dict = 'timetable@ron@ig_3_couch', name = 'base' },
    -- Custom camera for this spot
    rotation = vector3(0.682074, 0.0, 240),
    fov = 30.0,
}

Weather Options

Valid weather types:

• EXTRASUNNY, CLEAR, NEUTRAL, SMOG
• FOGGY, OVERCAST, CLOUDS, CLEARING
• RAIN, THUNDER, SNOW, BLIZZARD
• SNOWLIGHT, XMAS, HALLOWEEN

---

Logout Settings

Configure the logout functionality.

Config.Logout = {
    enabled = true,           -- Enable logout functionality
    command = 'logout',       -- Chat command name
    fadeOutDuration = 500,    -- Fade to black duration (ms)
    holdDuration = 1500,      -- Hold black screen duration (ms)
    fadeInDuration = 500,     -- Fade from black duration (ms)
}

Option	Type	Default	Description
enabled	boolean	true	Enable logout functionality
command	string	'logout'	Chat command to trigger logout
fadeOutDuration	number	500	Fade to black duration in ms
holdDuration	number	1500	Black screen hold duration in ms
fadeInDuration	number	500	Fade in duration in ms

---

External Links

Configure external links shown in the UI.

Config.Links = {
    discord = 'https://discord.gg/dZ6q8FyGhm',
}

Option	Type	Description
discord	string	Discord invite URL

---

Announcements

Display announcements on the character selection screen.

Config.Announcements = {
    {
        title = 'Welcome to Our Server',
        body = 'Thanks for joining! Check out the rules at our Discord.',
        type = 'info',
        date = '2026-01-24',
    },
    {
        title = 'Patch 2.0.0',
        body = 'New character creation flow, improved scenes, and bug fixes.',
        type = 'update',
        date = '2026-01-20',
    },
    {
        title = 'Scheduled Maintenance',
        body = 'Server will be offline tomorrow at 3 AM EST.',
        type = 'warning',
        date = '2026-01-18',
    },
}

Announcement Properties

Property	Type	Required	Description
title	string	Yes	Announcement title
body	string	Yes	Announcement content
type	string	Yes	Type: 'info', 'update', or 'warning'
date	string	Yes	Date string (for display)

Announcement Types

Type	Use Case
info	General information, welcome messages
update	Patch notes, new features
warning	Important notices, maintenance

---

Complete Example

Here's a complete config.lua example:

Config = {}

-- Character slots
Config.DefaultNumberOfCharacters = 5
Config.PlayersNumberOfCharacters = {}

-- Spawn settings
Config.SkipSelection = false
Config.DefaultSpawn = vector4(-1035.71, -2731.87, 12.86, 0.0)
Config.EnableDeleteButton = true

-- Validation
Config.NameLength = { min = 2, max = 20 }
Config.AgeRange = { min = 18, max = 80 }
Config.customNationality = false

-- Scenes
Config.Scenes = {
    default = 'apartment',
    list = {
        apartment = {
            name = 'Apartment',
            cam = {
                coords = vector3(-784.7750, 340.0801, 211.3950),
                rotation = vector3(0.682074, 0.0, 222.697968),
                fov = 40.0,
            },
            ped = {
                coords = vector4(-781.3235, 336.4592, 210.1991, 355.3351),
                animation = { dict = 'timetable@ron@ig_3_couch', name = 'base' },
            },
            weather = 'EXTRASUNNY',
            time = { hour = 20, minute = 0 },
        },
    },
}

-- Logout
Config.Logout = {
    enabled = true,
    command = 'logout',
    fadeOutDuration = 500,
    holdDuration = 1500,
    fadeInDuration = 500,
}

-- External links
Config.Links = {
    discord = 'https://discord.gg/dZ6q8FyGhm',
}

-- Announcements
Config.Announcements = {}