Rarx Multicharacter

Overview#

RARX Multicharacter is an advanced character selection system for FiveM servers featuring a built-in loading screen, main menu, spawn selector, starter vehicle system, and a full admin panel. The framework is auto-detected at runtime -- no manual configuration needed.

Features#

Requirements#

• Framework: ESX, QBCore, or QBox (auto-detected)
• ox_lib
• oxmysql
• rarx_lib

Installation#

1. Install dependencies

   Make sure these resources are installed and running before rarx_multicharacter:

   • oxmysql — database driver
   • ox_lib — runtime library
   • rarx_lib — provided in your Keymaster bundle
   • An appearance system: illenium-appearance, fivem-appearance, rarx_clothing, or bl_appearance

1. Download & extract

   Download the latest rarx_multicharacter from your Keymaster and extract it into your resources/ folder (e.g. resources/[core]/rarx_multicharacter/).

2. Import the database

   The install/ folder contains framework-specific SQL files. For ESX, run them in this order:

   SQLCopy

   -- 1. Required for ALL frameworks — multichar slots, character status, CK backups, tracking
   install/general.sql
   
   -- 2. Framework-specific — adds `nat` and `side` columns to your `users` table
   install/esx.sql

   For QBCore/QBox use the matching install/qb.sql or install/qbox.sql.

1. Edit server.cfg

   On ESX servers, ordering matters. The dependencies must start before es_extended initializes its multichar handlers. Recommended layout:

   server.cfgCopy

   # Core dependencies (oxmysql first, then everything else)
   ensure chat
   ensure hardcap
   ensure oxmysql
   
   # Order-sensitive: ox_lib -> framework -> appearance -> multichar
   ensure ox_lib
   ensure rarx_lib
   ensure es_extended
   ensure illenium-appearance       # or your appearance system
   ensure rarx_multicharacter
   
   # Umbrella ensures (pick up everything else in those folders)
   ensure [core]
   ensure [standalone]
   ensure [esx_addons]

   Set the locale convar for your appearance system, e.g.:

   server.cfgCopy

   setr illenium-appearance:locale "en"

2. Apply framework-specific setup

   Open the matching tab below — ESX, QBCore or QBox — and follow its steps. The ESX path requires patching es_extended; if you skip it the selector will never open.

3. Configure & restart

   Edit config.lua to set your branding, slot counts, spawn locations and admin permissions, then perform a full server restart (not just restart rarx_multicharacter). Some settings — especially Config.Multichar in es_extended — are only read at script load.

Framework-Specific Setup#

exports('GetApartmentsConfig', function()
    return Apartments
end)

-- BEFORE
Config.Multichar = GetResourceState("esx_multicharacter") ~= "missing"

-- AFTER
Config.Multichar = true

-- BEFORE
CreateThread(function()
    while not Config.Multichar do
        Wait(100)
        if NetworkIsPlayerActive(ESX.playerId) then
            ESX.DisableSpawnManager()
            DoScreenFadeOut(0)
            Wait(500)
            TriggerServerEvent("esx:onPlayerJoined")
            break
        end
    end
end)

-- AFTER
CreateThread(function()
    while not NetworkIsPlayerActive(ESX.playerId) do
        Wait(100)
    end
    ESX.DisableSpawnManager()

    if not Config.Multichar then
        DoScreenFadeOut(0)
        Wait(500)
        TriggerServerEvent("esx:onPlayerJoined")
    end
end)

provides {
  "esx_skin",
  "skinchanger",
}

Verifying the install#

After restarting the server, connect once and check both consoles for these signals. They confirm each stage of the boot completed correctly.

1. Server console (txAdmin live or fxserver.log)

   You should see, in this order:

   TextCopy

   [oxmysql] Database server connection established!
   [es_extended] [INFO] ESX Legacy 1.13.5 initialized!
   [resources] Started resource rarx_multicharacter

   On player connect:

   TextCopy

   [hardcap] Connecting: <name>
   [es_extended] [INFO] Player "<firstname lastname>" has connected to the server. ID: <n>

   If es_extended never prints "initialized!" something is wrong with oxmysql or your jobs table.

2. Client (F8)

   On connect, you should see the rarx loadscreen, then the character selector with your existing characters (or a "Create character" slot if none exist). No black-screen-with-floating-menu, no infinite loadscreen.

   Enable Config.Debug = true in rarx_multicharacter/config.lua for extra [rarx_multicharacter] lines that trace every step.

3. Database

   Pick an existing test character and inspect its users row:

   SQLCopy

   SELECT identifier, firstname, lastname, sex, height,
          LENGTH(skin) AS skin_len, LEFT(position, 60) AS position
   FROM users WHERE identifier LIKE 'char%';

   You should see one row per character, with identifier prefixed char1:, char2:, etc., a populated skin (illenium appearance JSON) and a saved position. If skin_len = 0, illenium's save callback didn't fire — see the troubleshooting section.

Clean reset (re-test from scratch)#

If you need to wipe a test player and start over (for example after fixing a half-broken install):

-- Replace <license> with the hex after `license:` from your identifier
DELETE FROM users WHERE identifier LIKE 'char%:<license>';
DELETE FROM playerskins WHERE citizenid LIKE '%<license>%';
DELETE FROM player_outfits WHERE citizenid LIKE '%<license>%';
DELETE FROM multicharacter_slots WHERE identifier LIKE '%<license>%';
DELETE FROM multicharacter_character_status WHERE citizenid LIKE '%<license>%';

Reconnect — you'll be back at the "Create character" prompt.

Configuration#

Language#

The language is set via the rarx-lang convar in your server.cfg, shared across all RARX resources:

setr rarx-lang "en"

Available languages: en (English) and es (Spanish). To add another, copy translates/en.lua and translate the strings inside it.

UI Appearance#

Config.Ui = {
    bannedWords = {'badword1', 'badword2'},
    maxBirthYear = 2015,
    minBirthYear = 1900,
    maxCharSlots = 5,       -- Total slots displayed
    allowCharSlots = 1,     -- Default unlocked slots
    hideKeyBind = "L",
    delKeyBind = "Delete",
    delAllowed = false,     -- Allow players to delete characters
    primaryColor = "#c94f4f",
    secondaryColor = "#c94f4f",
    logoUrl = "https://your-logo-url.png",
    nationalities = {
        ['United States'] = true,
        ['Spain'] = true,
        -- ... add/remove countries as needed
    },
}

Color Scheme#

Config.Colors = {
    primary = '#c94f4f',
    secondary = '#1a1a1a',
}

Character Info Display#

Config.Characters = {
    -- Fields shown on character cards
    -- Available: 'name', 'job', 'cash', 'bank', 'phone', 'nationality', 'dob'
    displayInfo = { 'name', 'job' },
}

Spawn System#

Config.SpawnSystem = {
    enabled = true,
    useRandomBucket = true,    -- Prevents player overlap during selection
    forceDefaultBucket = 0,    -- Bucket when entering the world

    ui = {
        showLastLocation = true,
        animatedTransition = true,
    },

    defaultSpawns = {
        {
            name = "LS Airport",
            coords = vector4(-1035.63, -2735.84, 20.17, 330.49),
            icon = 'fa-plane',
            description = "Los Santos International Airport"
        },
    },
}

Starter Vehicle#

Config.StarterVehicle = {
    enabled = true,
    showSelector = true,   -- Show UI selector (false = random from list)
    garage = 'garaje_central',
    vehicles = {
        { model = 'panto', label = 'Panto' },
        { model = 'blista', label = 'Blista' },
        { model = 'faggio2', label = 'Faggio Sport' },
    }
}

Loading Screen#

Config.Loading = {
    enabled = true,  -- Set to false to disable the custom loading screen
    background = {
        type = 'video',  -- 'video' | 'image' | 'youtube'
        url = 'https://your-video-url.mp4',
    },
    music = {
        enabled = true,
        type = 'mp3',    -- 'mp3' | 'youtube'
        url = 'https://your-music-url.mp3',
        volume = 0.5,
    },
    logo = 'https://your-logo-url.png',
    tips = {
        'Welcome to the server!',
        'Use /help for available commands',
    },
    tipInterval = 5,
}

Main Menu#

Config.Menu = {
    serverName = 'Your Server',
    serverSlogan = 'Your best roleplay experience',

    features = {
        { icon = 'fa-coins', text = 'Realistic Economy' },
        { icon = 'fa-car', text = 'Custom Vehicles' },
    },

    -- Navbar sections
    sections = {
        { id = 'home', label = 'HOME', isDefault = true },
        { id = 'rules', label = 'RULES', items = { ... } },
        { id = 'controls', label = 'CONTROLS', items = { ... } },
        { id = 'discord', label = 'DISCORD', isExternalLink = true, url = 'https://discord.gg/...' },
    },

    stats = {
        { type = 'players', label = 'PLAYERS ONLINE', icon = 'fa-users' },
        { type = 'uptime', label = 'UPTIME', icon = 'fa-clock' },
        { type = 'staff', label = 'STAFF ONLINE', icon = 'fa-user-shield' },
    },
}

Apartment Integration#

Config.Apartments = {
    disableQBApartment = false,
    enableQBApartmentSpawns = true,
    showApartmentsToExisting = true,
    enable0rMotels = false,
    enableOrigenHousing = false,
}

Commands#

Slot Management#

Example:

/setslots steam:12345678 5

Character Management (ESX)#

Character Management (QBCore / QBox)#

Other Commands#

Admin Panel#

The admin panel provides full character management capabilities with Discord webhook logging.

Access Control#

Config.AdminSystem = {
    enable = true,
    useAcePermissions = true,
    acePermission = 'qbcore.god',   -- QBCore / QBox only — see the per-framework note below
    adminIdentifiers = {
        '123456789',                -- Discord ID (with or without 'discord:' prefix)
        'steam:110000123456789',    -- Steam HEX
        -- 'license:abc123',        -- License
        -- 'fivem:12345',           -- FiveM ID
    },
    command = 'multicharadmin',
}

Both ACE permissions and identifier-based access work in parallel -- if either matches, access is granted.

Features#

• Slot Management -- Grant or remove character slots per player
• Character Activation/Deactivation -- Disable or re-enable character profiles with required reasons
• Character Kill (CK) -- Permanently remove characters with automatic backup creation
• Discord Webhooks -- Log all admin actions to separate Discord channels

Webhook Configuration#

Config.AdminSystem.webhooks = {
    enable = true,
    setSlots = 'https://discord.com/api/webhooks/...',
    characterStatus = 'https://discord.com/api/webhooks/...',
    characterKill = 'https://discord.com/api/webhooks/...',
    general = 'https://discord.com/api/webhooks/...',
}

Appearance Systems#

The script integrates with these appearance resources for character display during selection:

• rarx_clothing (recommended)
• illenium-appearance
• fivem-appearance
• bl_appearance
• origen_clothing
• qb-clothing

The system auto-detects which appearance resource is running and uses it automatically. No manual configuration needed.

Anticheat Compatibility#

This resource uses natives during character selection and spawn that may trigger false positives in anticheats. Below are the exact events and the natives they execute, so you can whitelist them.

Character Selection#

Spawn#

Events:

• rarx_multicharacter:client:spawnDefault
• rarx_multicharacter:client:spawnInApartment
• rarx_multicharacter:client:spawnInFirstApartment

Summary#

Troubleshooting#

add_ace identifier.discord:123456789 qbcore.god allow

if not ESX then
    ESX = exports["es_extended"]:getSharedObject()
end
if ESX and ESX.GetJobs then
    ESX.Jobs = ESX.GetJobs()  -- blocks until Core.JobsLoaded
end
isDatabaseConnected = true

SendNUIMessage({ action = 'hide' })
SendNUIMessage({ action = 'hideBlackOverlay' })

TriggerEvent("esx_skin:resetFirstSpawn")
TriggerEvent("skinchanger:loadSkin", skin, function()
    local ped = PlayerPedId()
    SetPedAoBlobRendering(ped, true)
    ResetEntityAlpha(ped)
    DoScreenFadeIn(600)

    TriggerEvent("esx_skin:openSaveableMenu", function()
        finished = true
    end, function()
        finished = true
    end)
end)

local target = spawn
if isNew then
    local realSpawns = Config.SpawnSystem and Config.SpawnSystem.defaultSpawns
    if realSpawns and #realSpawns > 0 and realSpawns[1].coords then
        target = realSpawns[1].coords
    elseif Config.DefaultSpawn and Config.DefaultSpawn.z > -50.0 then
        target = Config.DefaultSpawn
    else
        target = vector4(-1035.63, -2735.84, 20.17, 330.49) -- LSIA fallback
    end
end
SetEntityCoords(ped, target.x, target.y, target.z, false, false, false, false)
SetEntityHeading(ped, target.w or target.heading or 0.0)
RequestCollisionAtCoord(target.x, target.y, target.z)
NewLoadSceneStart(target.x, target.y, target.z, target.x, target.y, target.z, 50.0, 0)
local t = 0
while not IsNewLoadSceneLoaded() and t < 100 do Wait(50) t = t + 1 end
NewLoadSceneStop()

SendNUIMessage({ action = 'hide' })
SendNUIMessage({ action = 'hideBlackOverlay' })
-- ... existing esxSpawnPlayer / skinchanger / restoreLoadout calls ...
Wait(1000)
DoScreenFadeIn(800)
PostSpawnPlayer()