Installation Guide

This guide takes you from a fresh download to a working character screen. Follow the steps in order. You do not need to know how to write code — every step tells you exactly what to do and what you should see when it works.

A few terms used throughout this guide:

• Resource - A folder in your server's resources directory that the server loads, like oxide-multichar itself.
• server.cfg - The text file that tells your server which resources to start and in what order. You edit it with any plain text editor.
• Framework - The roleplay system your server runs on, such as QBCore, ESX, or QBX. It manages players, jobs, and money.
• o-link - A "translator" resource that lets oxide-multichar work with any framework. It is required.
• Clothing resource - The resource that stores and applies how a character looks (face, hair, clothes). Examples: illenium-appearance, qb-clothing, esx_skin.

Prerequisites

Required Resources

These must already be installed and working on your server before you start. If you are running a normal QBCore, ESX, or QBX server, you very likely have ox_lib and oxmysql already.

Supported Frameworks

oxide-multichar works with any framework that o-link supports. The frameworks below work out of the box.

Do I Need to Import a Database File?

No. oxide-multichar does not create or use any database tables of its own. Your characters continue to live in your framework's existing tables. There is nothing to import and nothing to remove if you ever uninstall it.

Installation Steps

Step 1: Place the Resource

Copy the oxide-multichar folder into your server's resources folder, the same way you install any other resource.

If you are also going to install the recommended clothing resource (illenium-appearance — covered later), place that folder in resources now too.

Step 2: Add It to server.cfg

Open your server.cfg in a text editor. The order resources start in matters, so add the lines below in this exact order. Pick the one framework core line that matches your server and delete the other two.

ensure ox_lib
ensure oxmysql

# Your framework core — keep ONE of these, delete the others
ensure qb-core                # QBCore
ensure qbx_core               # QBX
ensure es_extended            # ESX

# Recommended clothing resource — must start before o-link
ensure illenium-appearance

ensure o-link
ensure oxide-multichar

Why this order: o-link checks which clothing resource is running the moment it starts, so the clothing resource (illenium-appearance) has to start before o-link. And oxide-multichar needs o-link ready, so it goes last.

You do not need to build anything. The screen is shipped ready to use — there is no npm or build step required to install it.

Step 3: Turn Off Your Framework's Built-In Character Screen

This is the most important step. oxide-multichar replaces the character selection screen your framework comes with. If you leave the old one running, both will fight to open and you will see flickering, a frozen screen, or the wrong menu. The exact steps depend on your framework — see the next section.

Disabling the Native Character Screen

Do the steps for your framework only.

QBCore

Make sure qb-multicharacter is not started. In your server.cfg, find any line that says ensure qb-multicharacter and either delete it or put a # at the start of the line to turn it off:

# ensure qb-multicharacter

That's all. QBCore boots fine without it, and oxide-multichar takes over automatically.

ESX

Make sure esx_multicharacter is not started. In your server.cfg, find any line that says ensure esx_multicharacter and delete it or comment it out:

# ensure esx_multicharacter

If you prefer, you can also delete the esx_multicharacter folder from resources entirely. ESX normally looks for that folder to decide it should run in multi-character mode, but oxide-multichar announces itself to the server under that name too, so ESX stays in multi-character mode either way.

oxide-multichar takes over automatically.

QBX (qbx_core)

QBX is different: its character screen is built directly into qbx_core rather than a separate resource, so you cannot simply turn it off in server.cfg. Instead you make two small edits to one file. This is a copy-and-paste change — you are only turning two existing lines into comments.

Open this file in a text editor:

qbx_core/client/character.lua

Edit 1 — find this block (around line 507):

RegisterNetEvent('qbx_core:client:playerLoggedOut', function()
    if GetInvokingResource() then return end -- Make sure this can only be triggered from the server
    chooseCharacter()
end)

Change it to this (the only change is putting -- in front of chooseCharacter()):

RegisterNetEvent('qbx_core:client:playerLoggedOut', function()
    if GetInvokingResource() then return end -- Make sure this can only be triggered from the server
    -- [oxide-multichar] Native selection disabled; o-link's QBX adapter
    -- bridges this event to oxide-multichar instead.
    -- chooseCharacter()
end)

Edit 2 — find this block (around line 512):

CreateThread(function()
    while true do
        Wait(0)
        if NetworkIsSessionStarted() then
            pcall(function() exports.spawnmanager:setAutoSpawn(false) end)
            Wait(250)
            chooseCharacter()
            break
        end
    end

Change it to this (again, only the chooseCharacter() line is commented out):

CreateThread(function()
    while true do
        Wait(0)
        if NetworkIsSessionStarted() then
            pcall(function() exports.spawnmanager:setAutoSpawn(false) end)
            Wait(250)
            -- [oxide-multichar] Native selection disabled on boot; oxide-multichar
            -- opens the selection scene instead.
            -- chooseCharacter()
            break
        end
    end

Save the file and restart your server. oxide-multichar now handles both joining the server and the /logout command.

Recommended Clothing Resource

This step is optional but strongly recommended.

During character creation, and when drawing each character on the selection screen, oxide-multichar asks your clothing resource how the character looks. Some clothing resources can only describe clothes and props, not the face shape, skin tone, hair, and tattoos. With those, your characters in the selection scene will have a generic face until they actually spawn into the world.

illenium-appearance is a free, open-source clothing resource that describes the full look, so your selection-screen characters look exactly like the player built them. We recommend it on every framework.

• QBX already ships with illenium-appearance — there is nothing to do.
• QBCore and ESX servers can switch to it for the best results.

What you get with each clothing resource

Switching to illenium-appearance is purely a visual upgrade. Everything else works the same either way.

If you switch to illenium-appearance

Turn off your old clothing resource so two don't run at once:

• QBCore - Do not start qb-clothing.
• ESX - Do not start esx_skin or skinchanger.
• QBX - Nothing to do; it already uses illenium-appearance.

Verification

After installing, start your server and confirm each of these. This is what "working" looks like:

1. Everything loads. In the server console, confirm ox_lib, oxmysql, your framework, illenium-appearance (if used), o-link, and oxide-multichar all start without red dependency errors.
2. The screen appears. Join the server. After the loading screen, you should see the rendered selection scene (a camera looking at a location) with your characters standing in it — not your framework's old menu.
3. You can create a character. Click the dimmed "Create Character" figure (or the create option). Enter a name, date of birth, and gender. If you use a supported clothing resource, the appearance editor opens next. After confirming, you choose a spawn point and drop into the world.
4. Characters are remembered. Type /logout, or reconnect. Your new character should appear in the scene with its saved look.
5. Logout works. Type /logout while playing and confirm you return to the selection scene.
6. Deleting works. Delete a character and confirm the slot frees up.

If any of these fail, see Troubleshooting.

Notes

Character Data Ownership

oxide-multichar owns no database tables. Character data stays in your framework's own tables (players for QBCore and QBX, users for ESX) and is read and written through o-link. Nothing to import, nothing to back up separately, nothing left behind if you uninstall.

Maximum Characters

The number of character slots every player gets is set in one place — Config.MaxCharacters in config.lua — regardless of framework. Specific players (VIPs, staff) can be granted extra slots with Config.SlotGrants. See Configuration.

Language / Text

All on-screen text lives in one file: locales/en.json inside the resource. Every label, button, and message is a line in that file, so you can reword anything by opening it in a plain text editor and changing the text on the right-hand side of each line. Keep any %s and %d markers in place — the script fills those in with names and numbers.

To translate the screen into another language, copy locales/en.json to a new file named after your language code (for example locales/de.json for German), translate it, and add this line to your server.cfg:

setr ox:locale de

This is the same language setting ox_lib uses, so if your server already runs in another language, oxide-multichar picks it up automatically.

Next Steps

• Configuration - Customize spawn points, scenes, slot count, and more
• Features - Understand how each part of the screen works
• Troubleshooting - Fix common setup problems