Configuration

The config/config.lua file controls all the core logic of the multicharacter system, including character slots, spawn settings, framework behavior, appearance handlers, UI content, and more Let’s break it all down.

Config File (config.lua)

This file controls the basic functionality of the multicharacter.

Locale

Sets the active language for the UI.

Config.Locale = "en"

Must match a file inside the /locales/ folder.

Framework Prefix

Prefix used in the database to distinguish character entries (mostly for ESX-based servers).

Config.Prefix = "char"

Appearance Integration

Config.AppereanceResource = "qb-clothing"

Supported options:

"qb-clothing"
"fivem-appearance"
"illenium-appearance"
"skinchanger"
"tgiann-clothing", "dx_clothing", "rcore_clothing", "dx-clothing", "karma-clothing"

This defines which skin/appearance resource will be used during character creation.

Spawn Settings

Config.SpawnLastLocation = false
Config.defaultSpawn = vector4(-1037.449, -2737.475, 20.1692, 329.1169)

SpawnLastLocation: If true, player will spawn at their last known location.
defaultSpawn: The default spawn location if not using apartment or housing systems.

Camera Setup

Config.CamCoords = vector4(-556.22, 286.16, 882.2, -85.00)
Config.HiddenCoords = vector4(-779.01, 326.18, 196.08, 91.04)

CamCoords: Where the camera is placed during character selection.
HiddenCoords: Where your actual ped is teleported (hidden) during selection.

Starter Items

Config.starterItems = {
    { item = "bread", count = 5 },
    { item = "water", count = 5 },
}

Items automatically given to the player when they create a new character.

Identifier Settings

Config.Identifier = {
    column = "license",
    type = "license"
}

column: The database field to use for linking players.
type: Accepted types: "license", "steam", "fivem", "discord".

⚠️ If you’re using Qbox, change to license2.

UI Page Animation

Config.PageAnimation = "slide"

Controls how the multicharacter pages transition.

Options: "slide", "fade", "none"

UI Settings

Config.UISettings = {
    ['serverHeader'] = "SAKA <span>ROLEPLAY</span>",
    ['storeLabel'] = "SAKA <br>STORE",
    ['serverLabel'] = "Saka Roleplay",
    ['serverLogo'] = "https://.../sakaIcon.png",
    ['serverLogoLight'] = "https://.../serverIcon.png",
}

Modify branding, labels, and logos shown in the interface.

PED Animations

Config.Animations = {
    { dict = "anim@heists@heist_corona@single_team", name = "single_team_loop_boss" },
}

Random idle animations shown during character selection.

Character Slot & Limit

Config.defaultMaxNumberCharacters = 5
Config.defaultCharactersLimit = 3

defaultMaxNumberCharacters: How many slots are visually shown.
defaultCharactersLimit: How many characters the player can actually use (unless upgraded via Discord/Tebex/etc.)

Character Options

Config.canWriteStory = true
Config.canDeleteChar = true

canWriteStory: Players can write a short backstory.
canDeleteChar: Players can delete characters themselves.

Input Limits

Config.inputsLengths = {
    firstName = { min = 2, max = 20 },
    lastName = { min = 2, max = 20 },
    height = { min = 100, max = 220 },
}

Minimum and maximum lengths for first name, last name, and height input.

Birthday Format

Config.birthDayType = "dd/mm/yyyy"

Available formats:

"mm/dd/yyyy"
"dd/mm/yyyy"
"yyyy/mm/dd"

Character Deletion Tables

Config.deleteTables = {
    esx = {
        { table = "users", column = "identifier" },
        ...
    },
    qb = {
        { table = "players", column = "citizenid" },
        ...
    }
}

Defines which database rows get deleted when a character is removed.

⚠️ Make sure these tables exist in your database.

Job Icons

Config.JobIcons = {
    ['police'] = 'police.png',
    ['ambulance'] = 'ambulance.png',
    ...
}

Maps job names to icons shown in character profiles.
Place icon files in the UI assets folder.

Max Music Upload

Config.MaxMusic = 5

The maximum number of songs that can be added via the UI.

Logout Command

Config.Commands = {
    ['logout'] = {
        enable = true,
        command = "logout",
        permission = "user"
    }
}

Enables a /logout command to return to character selection.
permission: Set required permission group.

Theme File (theme.lua)

The config/theme.lua file lets you fully style the multicharacter UI. Two built-in themes are available:

Light – Bright, clean look
Dark – Dark, high-contrast style

Each theme includes four sections:

General Appearance

Controls core colors for text, backgrounds, buttons, and more.

general = {
    textColor = "#000000",
    textColorSecondary = "#000000",
    background = "#FFFFFFBF",
    musicPlayerBackground = "#FFFFFF",
    musicPlayerFill = "#000000",
    musicPlayerText = "#000000",
    musicPlayerTrack = "#00000042",
    musicPlayerTrackProgress = "#000000",
    closeBackground = "#0000003D",
    closeBorder = "#0000001C",
    closeFill = "#000000",
    characterSelectedBackground = "#00000033",
    inputBorder = "#00000026",
    inputPlaceholder = "#00000057",
    heredityBg = "#00000014",
    selectedHeredityBg = "#0000000D",
    heredityText = "#00000080",
}

textColor / textColorSecondary: Primary and secondary text colors
background: Overlay or panel background
closeBackground, closeBorder, closeFill: Close-button styling
characterSelectedBackground: Highlight for selected character slot
inputBorder / inputPlaceholder: Styling for input fields

Shortcuts

Styles for on-screen key hints and shortcut prompts.

shortcuts = {
    default = "#FFFFFF5C",
    active = "#FFFFFF",
    textColor = "#00000066",
    activeTextColor = "#00000099",
}

default / active: Inactive vs. active key color
textColor / activeTextColor: Label colors

Stories

If you use multi-step creation with story prompts, these control the buttons and highlights.

story = {
    buttonBackground = "#FFFFFF24",
    buttonBorder = "#FFFFFF1C",
    buttonFill = "#FFFFFF",
    buttonText = "#FFFFFFCC",
}

buttonBackground / buttonBorder: Button container styling
buttonFill / buttonText: Button icon/text colors

Settings

Used in any internal settings panels (e.g., Loading Screen, Multicharacter etc.).

settings = {
    boxBackground = "#FFFFFF33",
    switchBackground = "#FFFFFF1C",
    switchCircle = "#FFFFFF",
    activeSwitchBackground = "#FFFFFF66",
    themeBackground = "#FFFFFF1C",
    svgFill = "#FFFFFF",
    dividerColor = "#0000001A",
}

boxBackground: Panel container color
switchBackground / activeSwitchBackground: Toggle switch styling
switchCircle: The knob color on switches
svgFill: Color for inline SVG icons

Creating Your Custom Theme

1 - Duplicate either the light or dark block in Config.Themes.

2 - Rename the key (e.g., "custom").

3 - Adjust color codes per section.

Important Notes

Colors must be valid hex codes (e.g., #FFFFFF) or rgba formats (e.g., rgba(0,0,0,0.5)).
Shadows must follow valid CSS box-shadow syntax.
You can freely create your own theme by duplicating an existing one (light, dark) and editing the colors.

Camera Configuration (camLocations.lua)

This file defines the locations, positions, and angles of the camera and ped during character selection or creation.

Basic Options

Config.Cam.FOV = 30.0
Config.Cam.DefaultLocation = 'downtown'

FOV: Camera Field of View (zoom level)
DefaultLocation: The key of the default camera position used when opening the interface

Camera Presets

You can define multiple camera locations for aesthetic or immersive effects.

Config.Cam.camLocations = {
    ['downtown'] = {
        ['Label'] = "Downtown",
        ['camCoord'] = vector4(69.11, -238.78, 48.50, 249.91),
        ['pedCoord'] = vector4(71.97, -239.84, 48.19, 59.53),
    },
    ['campSide'] = {
        ['Label'] = "Camp Side",
        ['camCoord'] = vector4(3604.75, 4733.33, 6.02, 325.13),
        ['pedCoord'] = vector4(3606.76, 4736.15, 5.65, 147.65),
    },
    ...
}

Label: Display name on UI
camCoord: Where the camera floats
pedCoord: Where the ped (character) stands

You can add as many locations as you want. All appear in a dropdown selector (if supported by the UI).

Camera Movements

Config.Cam.Effect = {
    rotations = {
        x = 0.0,
        y = -10.0,
        z = -70.0,
    },
    offsets = {
        x = 1.0,
        y = 0.0,
        z = 0.5,
    }
}

rotations: Adjust camera tilt/angle
offsets: Slightly shift the camera from its base position (for dynamic camera effects)

API Keys

Used to integrate third-party services like Spotify.

Spotify Song Catcher Integration

APIKeys = {
    ['clientId']     = "YOUR_CLIENT_ID",
    ['clientSecret'] = "YOUR_CLIENT_SECRET",
}

These keys allow integration with the Spotify Web API
Use them to fetch songs and their artcovers.

Get your keys here:

🔗 https://developer.spotify.com/dashboard

⚠️ Never share this file publicly. Keep it server-side only!

PreviousInstallation NextSpawn Selection

Last updated 2 months ago