Configuration

This page documents the configurable settings in config.lua and the editable Discord table in server/utils.lua. Restart ars_multicharacter after changing these values.

Core Settings

Config.Debug = true
Config.Framework = 'auto'
Config.MaxCharacters = 4

Setting	Default	Purpose
Debug	false	Enables verbose debug output. Set to true for troubleshooting.
Framework	'auto'	Selects qbx, qb, or esx; 'auto' detects resources in priority order.
MaxCharacters	4	Default character slot count when no license override exists.

Framework Settings

Config.FrameworkSettings = {
    qb = {
        starterItems = true,
        skinResource = 'auto',
    },
    qbx = {
        starterItems = true,
        skinResource = 'auto',
    },
    esx = {
        starterItems = true,
        prefix = 'char',
        skinResource = 'auto',
    },
}

Setting	Purpose
starterItems	Gives configured starter items when a new character is created
skinResource	Forces an appearance resource, or uses auto-detection when set to 'auto'
prefix	ESX character identifier prefix, such as char1:license:...

Starter Items

Config.StarterItems = {
    qb = {
        { item = 'id_card', amount = 1 },
        { item = 'driver_license', amount = 1 },
    },
    qbx = {
        { item = 'id_card', amount = 1 },
        { item = 'driver_license', amount = 1 },
    },
    esx = {
        { item = 'id_card', amount = 1 },
        { item = 'driver_license', amount = 1 },
    },
}

If ox_inventory is running, starter items are added through ox_inventory. Otherwise, the framework bridge uses its own inventory API.

Admin Permissions

Config.Permissions = {
    qb = {
        god = 'god',
    },
    qbx = {
        god = 'god',
    },
    esx = {
        god = 'superadmin',
    },
}

Config.AdminLicenses = {
    -- ['license:1234567890abcdef'] = true,
}

Setting	Purpose
Permissions.qb.god	Required QBCore permission or ACE principal for admin commands
Permissions.qbx.god	Required QBX ACE principal for admin commands
Permissions.esx.god	Required ESX group for admin commands
AdminLicenses	Rockstar licenses that always pass the admin check

Admin commands are /deletechar, /setcharslots, and /generatecharcode. /logout is available to all players.

Selector Coordinates and Camera

Config.DefaultSpawn = vector3(-1035.71, -2731.87, 12.86)
Config.PedCoords = vector4(-1051.57, -25.72, 49.26, 52.66)
Config.SkinCreationCoords = vector4(-759.84, 325.43, 170.61, 92.91)

Setting	Purpose
DefaultSpawn	Fallback spawn when Config.Spawn.skipSelection is enabled for new characters
PedCoords	Base position and heading for portrait peds and selector cameras
SkinCreationCoords	Location where players are placed while using the appearance creator

Offsets

Config.Offsets = {
    ground = -0.98,
    hidden = { behind = 15.0, below = 5.0 },
    lineup = { behind = 3.5 },
    skyCam = { forward = 3.0, height = 0.55, fov = 15.0 },
    cam = { forward = 1.8, height = 0.45, targetHeight = 0.5, fov = 30.0 },
    lights = {
        key   = { forward = 2.0, height = 1.5, r = 255, g = 245, b = 235, range = 8.0, intensity = 1.5, shadow = 5.0 },
        fill  = { behind = 1.5, height = 1.0, r = 180, g = 200, b = 255, range = 6.0, intensity = 0.6 },
        back  = { behind = 1.0, height = 2.0, r = 200, g = 220, b = 255, range = 5.0, intensity = 0.8 },
    },
}

These values control the hidden player position, portrait ped lineup, active camera, sky camera, and in-scene lighting.

UI and Display

Config.ServerName = 'My Server'
Config.ServerLogo = 'logo.png'
Config.ShowPlayerCount = true
Config.TosLink = ''
Config.RulesLink = ''
Config.DefaultLayout = 'minimalist'
Config.EnableMusic = true
Config.EnableDeleteButton = true
Config.customNationality = false
Config.SkipSelection = false
Config.UseLandCam = true

Setting	Purpose
ServerName	Server name shown in the selector
ServerLogo	Logo filename inside html/; leave empty for the default icon
ShowPlayerCount	Shows online/max player count
TosLink	External Terms of Service URL; leave empty for the built-in modal
RulesLink	External Rules URL; leave empty for the built-in modal
DefaultLayout	Initial layout: 'sidebar', 'obsidian', or 'minimalist'
EnableMusic	Enables ambient selector music
EnableDeleteButton	Allows players to delete their own characters through the UI
customNationality	false uses the Config.Countries dropdown; true uses a free-text input
SkipSelection	Skips spawn selection when loading an existing character
UseLandCam	Enables land-cam transitions for spawn selection

Notifications

Config.Notifications = {
    duration = 4000,
}

Setting	Purpose
duration	Default NUI notification duration in milliseconds

Environment

Config.NightTime = { hour = 0, minute = 0 }
Config.SelectionWeather = 'CLEAR'

Setting	Purpose
NightTime	Time forced while the selector is open
SelectionWeather	Weather forced while the selector is open

The resource restores normal time and weather sync when the selector closes or the resource stops.

Cinematic

Config.Cinematic = {
    enabled = true,
    fov = 50.0,
}

Setting	Purpose
enabled	Enables the opening city flyover
fov	Field of view for the cinematic camera

LandCam

Config.LandCam = {
    startHeight = 150.0,
    fov = 60.0,
    duration = 4000,
    behindDistance = 3.0,
    endHeight = 1.0,
}

Setting	Purpose
startHeight	Starting camera height
fov	Camera field of view
duration	Camera transition duration in milliseconds
behindDistance	Distance behind the player for the final camera position
endHeight	Final camera height

Portrait Peds

Config.Portrait = {
    pedSpacing = 1.5,
    slideDuration = 600,
    offscreenDistance = 3.0,
    transitionStyle = 'slide',
}

Setting	Purpose
pedSpacing	Distance between portrait peds
slideDuration	Transition duration in milliseconds
offscreenDistance	Distance used for off-screen transition positions
transitionStyle	'slide' or 'walk'

Ped Emotes

Config.PedEmotes = {
    enabled = false,
    { type = 'scenario', anim = 'WORLD_HUMAN_GUARD_STAND' },
    { type = 'scenario', anim = 'WORLD_HUMAN_HANG_OUT_STREET' },
}

Each entry can be a scenario or an animation with dict and anim.

Housing

Config.Housing = {
    resource = 'auto',
    useApartmentForNewChar = false,
}

Setting	Purpose
resource	'auto', 'ps-housing', 'qb-housing', or 'none'
useApartmentForNewChar	Sends new characters to qb-apartments when using qb-houses

ps-housing shows owned properties through the properties table. qb-houses shows owned houses and apartments through player_houses and apartments.

Spawn Locations

Config.Spawn = {
    skipSelection = false,
    locations = {
        {
            coords = vector4(235.33, -872.04, 30.49, 343.52),
            label = "Legion Square",
            description = "The bustling heart of downtown Los Santos. Highly populated with immediate vehicle access.",
        },
    },
}

Config.Spawns = Config.Spawn.locations

Setting	Purpose
skipSelection	Skips spawn selection after a new character finishes appearance creation
locations	Ordered spawn presets shown to players
Spawns	Alias for Spawn.locations

Appearance Resources

Config.Appearance = {
    autoDetect = true,
    fallback = 'illenium-appearance',
    fivemAppearanceConfig = {
        ped = true, headBlend = true, faceFeatures = true, headOverlays = true,
        components = true, props = true, tattoos = true, enableExit = true,
    },
}

Setting	Purpose
autoDetect	Kept in config; appearance resources are detected automatically unless skinResource is explicit
fallback	Fallback resource if auto-detection finds nothing
fivemAppearanceConfig	Flags passed to compatible appearance resources during customization

Supported detected resources are bl_appearance, illenium-appearance, qs-appearance, fivem-appearance, qb-clothing, and skinchanger.

Character Levels

Config.CharacterLevels = {
    enabled = false,
    startLevel = 1,
    startXp = 0,
    xpPerLevel = 100,
    xpFormula = 'linear',
    levelCap = 100,
}

Setting	Default	Purpose
enabled	false	Master toggle. When false, no level or XP is read, written, or displayed
startLevel	1	Starting level for new characters
startXp	0	Starting XP for new characters
xpPerLevel	100	Base XP value used in the level-up formula
xpFormula	'linear'	'linear' (level * xpPerLevel) or 'exponential' (level² * xpPerLevel)
levelCap	100	Maximum achievable level

When enabled, the level and XP are stored inside the framework’s existing metadata JSON column and merged with any existing metadata (hunger, thirst, stress, etc.). Character cards display a level badge and an XP progress bar in all three UI layouts.

Other scripts can add XP through the AddCharacterXp server export. See Exports for details.

Slot Overrides and Tebex

Config.SlotOverrides = {
    enabled = true,
    storeUrl = '',
}

Setting	Purpose
enabled	Enables per-license slot overrides and the UI slot-purchase panel
storeUrl	Store URL shown when players need more slots

Slot sources are calculated like this:

1. Read ars_multicharacter_slots for the player’s license
2. Fall back to Config.MaxCharacters when no row exists
3. Redeemed codes add slots to that total by updating ars_multicharacter_slots

Countries and Nationality

Config.Countries = {
    "United States",
    "United Kingdom",
    "Germany",
    "France",
    "Brazil",
}

When Config.customNationality is false, the selector uses this list as a dropdown. When it is true, players enter nationality as free text.

Discord Tebex Logging

server/utils.lua contains an editable Discord table used for Tebex purchase logging:

Discord = {
    Enabled = false,
    WebhookURL = '',
    BotName = 'ARS Multicharacter',
    BotAvatar = '',
    Colors = {
        Success = 3066993,
        Info = 7506394,
        Warning = 16776960,
        Error = 16711680,
    },
}

Setting	Purpose
Enabled	Enables Discord webhook logging
WebhookURL	Discord webhook URL for Tebex events
BotName	Webhook display name
BotAvatar	Webhook avatar URL
Colors	Embed colors for success, info, warning, and error events

---

Note: This guide is written by a third party. If you find any incorrect or outdated information, please contact us on Discord so we can update it for you.