Config

Everything you can change to tailor Nexus Multicharacter to your server.

All of the configuration lives in the shared/ folder and is escrow-ignored, so you can edit it freely.

File	What’s in it
`shared/config.lua`	Core settings, slots, spawn, integrations
`shared/theme.lua`	UI color theme
`shared/locales.lua`	Translatable UI strings
`shared/nationalities.lua`	Nationality dropdown list

Core settings

These control which framework you’re on and how players are identified.

shared/config.lua


Config.Locale          = 'en'        -- Active language. Add tables in shared/locales.lua and switch this.
Config.Framework       = 'auto'      -- auto | qb | qbx | esx
Config.IdentifierType  = 'license'   -- steam | license | discord | xbl | live (ESX + slot owner)
Config.Prefix          = 'char'      -- Prefix for character ID (ESX only)

Key	Type	Default	What it does
`Locale`	string	`'en'`	Active language key from `shared/locales.lua`.
`Framework`	string	`'auto'`	Detect automatically or force `qb`, `qbx`, or `esx`.
`IdentifierType`	string	`'license'`	Identifier used for ESX characters and for tracking slot ownership.
`Prefix`	string	`'char'`	Character ID prefix (ESX only).

Character slots

How many slots a player gets and where the paid ones come from.

shared/config.lua


Config.Freeslots  = 3        -- Slots granted to every player
Config.PaidSlots  = 1        -- Maximum extra slots that can be unlocked
Config.UnlockMode = 'tebex'  -- tebex | discord | both

Key	Type	Default	What it does
`Freeslots`	number	`3`	Slots every player gets by default.
`PaidSlots`	number	`1`	Max extra slots that can be unlocked through Tebex codes or Discord roles.
`UnlockMode`	string	`'tebex'`	Where paid slots come from. See the Paid slot unlock section below.

Spawn and apartment integration

shared/config.lua


Config.InitialSpawn = vec4(-1041.7906, -2745.0769, 21.3594, 331.8917)

Key	Type	What it does
`InitialSpawn`	vec4	Where every character spawns after creation.

If you have qb-apartments (QBCore) or qbx_properties (Qbox) installed, new characters will also be assigned a starter apartment alongside this spawn.

The clothing menu to use during character creation.

shared/config.lua


Config.AppearanceMenu = 'auto'

Supported values:

auto, fivem-appearance, illenium-appearance, qb-clothing, skinchanger, crm-appearance, bl_appearance, tgiann-clothing, rcore_clothing, dx_clothing, karma_clothing

If your menu isn’t on the list, you can wire it up by editing client/cl_customize.lua and server/sv_customize.lua.

UI toggles

Small switches for the selection screen.

shared/config.lua


Config.EnableDeleteButton   = true
Config.ShowSelectionHeader  = true
Config.UseSpawnSelector     = true

Key	Type	Default	What it does
`EnableDeleteButton`	boolean	`true`	Show or hide the delete button on each slot.
`ShowSelectionHeader`	boolean	`true`	Show the hex-logo “My Characters” header on the selection screen.
`UseSpawnSelector`	boolean	`true`	Route through a spawn selector when picking an existing character.

Branding

Server logo on the selection screen.

shared/config.lua


Config.Logo = 'https://ik.imagekit.io/your-account/logo.png'

Any direct image URL works. SVG, PNG, JPG, or WebP.

Sounds

UI sound effects.

shared/config.lua


Config.Sounds = {
    Reveal     = './sounds/reveal_sfx.mp3',  -- When the welcome screen halves split apart
    SlotSelect = './sounds/swoosh.mp3',      -- When a character slot is selected
}

Local files go in web/public/sounds/ and are referenced as './sounds/<file>'. You can also use absolute https:// URLs. Set a value to false or '' to disable that SFX.

Commands

shared/config.lua


Config.Commands = {
    relog = 'relog',  -- Returns the player to character select
}

Rename the command to whatever you want.

Starter items

Items every new character starts with. Set the whole table to false to disable.

shared/config.lua


Config.StarterItems = {
    { name = "id_card",         amount = 1 },
    { name = "driver_license",  amount = 1 },
}

Camera and animations

Each character slot can have its own location, idle animation, and camera offset for a personalized vibe in the selection screen.

shared/config.lua


Config.CamSettings = {
    CreationCam = vec4(908.1880, 1.5739, 111.2763, 226.6732),
}
 
Config.Animations = {
    [1] = {
        coords = vec4(-438.8713, 1075.3090, 351.4383, 347.4917),
        anim = {
            dict = 'anim@amb@carmeet@checkout_car@',
            clip = 'male_c_idle_d',
        },
        CameraCoordOffset = vec3(0.0, 0.0, 0.0),
        FocusCoordOffset  = vec3(0.0, 0.0, 0.0),
    },
    -- Add more slots if Config.Freeslots is increased.
}

Key	What it does
`coords`	World position the character idles at.
`anim.dict` / `anim.clip`	Animation dictionary and clip name.
`CameraCoordOffset`	Fine-tune the camera position relative to the character.
`FocusCoordOffset`	Where the camera looks. Useful for shoulder-up framing.

If Config.Freeslots is set higher than the number of Config.Animations entries, add matching slots [4], [5], etc., or the extra slots won’t have a per-slot scene.

Paid slot unlock

Config.UnlockMode decides how players unlock the extra slots in Config.PaidSlots:

Mode	Behavior
`'tebex'`	Players redeem codes you issue (DB-backed). Use the console commands below.
`'discord'`	Slots are granted automatically based on Discord roles. The redeem modal is hidden.
`'both'`	Tebex codes work AND Discord roles stack on top.

Tebex codes

When UnlockMode is 'tebex' (or 'both'), use the server console:

Command	What it does
`nxsaddcode <code>`	Add a new redeemable code.
`nxsdelcode <code>`	Delete a code.
`nxslistcodes`	List every code in the DB.

Discord roles

When UnlockMode is 'discord' (or 'both'), the resource queries Discord and grants slots based on role IDs.

shared/config.lua


Config.Discord = {
    BotToken     = '',  -- Bot token. Bot must be in your guild.
    GuildId      = '',  -- Your Discord server ID.
    CacheSeconds = 60,  -- How long to cache a player's roles before re-querying.
    Roles = {
        -- ['1234567890123456789'] = 1,   -- VIP role gives +1 slot
        -- ['9876543210987654321'] = 2,   -- Premium role gives +2 slots
    },
}

A player gets the sum of all matching role values, capped at Config.PaidSlots.

The bot needs to be a member of your guild but doesn’t need any special intents. It uses the /members/{user} endpoint, which only requires the bot to be in the server.

Admin commands

Run these in-game (with appropriate permissions) to manage slots manually:

Command	What it does
`/setslots <playerId> <amount>`	Set a player’s total slot count.
`/giveslot <playerId>`	Add one slot to a player.
`/takeslot <playerId>`	Remove one slot from a player.
`/playerslots <playerId>`	Print a player’s current slot count.

Theme colors

UI colors live in a separate file so they’re easy to tweak.

shared/theme.lua


Theme = {
    Primary = '#2389FD',  -- Accent: selected slot, Play / Create buttons, focus rings
    Danger  = '#FD2327',  -- Destructive: Delete button, Cancel, delete-confirm modal
    Bg      = '#0E0E0E',  -- Modal scrims, dark base under glassy panels
    Text    = '#FFFFFF',  -- Default text color
}

Hex colors only.

Languages and translations

All UI strings are in shared/locales.lua under language tables. The default is Locales.en.

To add another language:

Open shared/locales.lua and copy the Locales.en = { ... } block.
Rename it (for example Locales.de = { ... }) and translate the values.
In shared/config.lua, set Config.Locale = 'de'.

Nationalities

The nationality dropdown shown during character creation is editable in shared/nationalities.lua:

shared/nationalities.lua


Nationalities = {
    { value = 'american',  label = 'American' },
    { value = 'british',   label = 'British' },
    -- ...
}

value is the internal ID stored in the database (lowercase, no spaces, use _ instead).
label is what shows up in the UI dropdown.

Need help?

Stuck on a setting or want a feature exposed? Hop into our Discord .

Config

Core settings

Character slots

Spawn and apartment integration

Appearance menu

UI toggles

Branding

Sounds

Commands

Starter items

Camera and animations

Paid slot unlock

Tebex codes

Discord roles

Admin commands

Theme colors

Languages and translations

Nationalities

Need help?