How to Configure QBCore Multichar
Your QBCore server boots, players connect, and they’re thrown straight into the game as a single character with no way to switch. That works for testing, but any real RP server needs multiple character support. Players want alts — a cop character, a criminal, maybe a civilian just for vibes. Without multichar, you’re capping your server’s replayability before it even launches.
I’ve helped dozens of server owners set this up through our Discord, and the process itself isn’t hard. But there are specific steps people skip that lead to broken spawns, invisible characters, and database errors that take hours to debug. This guide covers the full setup so you don’t hit those walls.
What qb-multicharacter Actually Does
QBCore doesn’t natively support multiple characters per player. Out of the box, one license equals one character. The qb-multicharacter resource adds a character selection screen at connection — players see their existing characters, can create new ones, and pick which one to play.
Under the hood, it works by hooking into QBCore’s player loading system. Instead of auto-loading the single character tied to a license, it presents a selection UI, lets the player choose (or create), and then calls QBCore.Player.Login with the selected character’s citizenid. The character data — name, money, job, gang, inventory — is all stored in the players table, with each row representing a separate character.
This is different from how ESX handles it (ESX uses esx_multicharacter or illenium-appearance combos), but the concept is the same. If you’re choosing between frameworks and multichar support matters to you, the ESX vs QBCore vs Qbox comparison covers broader differences.
Prerequisites
Before you touch multichar, make sure you have these sorted:
A working QBCore server with qb-core running properly. If you haven’t set that up yet, follow the server setup guide first — don’t try to configure multichar on a broken base.
A MySQL database connected and accessible. You’ll need to run SQL queries, so have phpMyAdmin, HeidiSQL, or another database tool ready.
qb-spawn installed. Multicharacter handles the selection screen, but qb-spawn handles where the player actually appears in the world after selecting. These two resources work as a pair.
qb-clothing or an appearance resource like illenium-appearance or fivem-appearance. Players need to set their character’s look during creation.
Installation Step by Step
Step 1: Download the Resource
Grab qb-multicharacter from the official QBCore GitHub organization. Don’t download random forks from sketchy sites — use the official repo or a trusted source. If you’re not sure how resource installation works in general, the script installation guide walks through the full process.
cd /resources/[qb]
git clone https://github.com/qbcore-framework/qb-multicharacter.gitIf you’re not using git, download the ZIP and extract it into your [qb] resource folder. The folder name needs to be exactly qb-multicharacter.
Step 2: Add to server.cfg
Add the resource to your server.cfg. Order matters here — qb-multicharacter needs to start after qb-core and before qb-spawn:
ensure qb-core
ensure qb-multicharacter
ensure qb-spawn
ensure qb-clothingIf you’re using illenium-appearance instead of qb-clothing, replace that line accordingly. The key point is that the appearance resource needs to be running before a player tries to create a character.
Step 3: Run the Database Migration
qb-multicharacter expects a specific table structure. Most versions include a SQL file in the resource folder. Look for qb-multicharacter.sql or check the README for the schema.
If there’s no SQL file, the resource usually creates its tables automatically on first start through QBCore’s built-in migration system. But I’d rather you check manually. Open your database tool and verify these columns exist in the players table:
-- Check your players table structure
DESCRIBE players;You need citizenid, license, name, money, charinfo, job, gang, position, metadata, and cid columns at minimum. The cid column is what tracks which character slot (1, 2, 3, etc.) belongs to which player. If it’s missing, the resource won’t know how to differentiate characters under the same license.
If cid doesn’t exist, add it:
ALTER TABLE `players` ADD COLUMN `cid` INT(11) DEFAULT 1;Step 4: Configure Character Slots
Open qb-multicharacter/config.lua. This is where you control how many characters each player can have:
Config = {}
Config.MaxCharacters = 5 -- max characters per player
Config.PlayersTable = 'players' -- database table name
Config.Interior = vector4(-1042.99, -2745.65, 21.36, 328.48) -- character selection location
Config.HidePlayer = true -- hide other players during selection
Config.StartingApartment = true -- force apartment selection for new charsConfig.MaxCharacters — I’d keep this between 3 and 5. Going above 5 invites abuse (people creating throwaway characters to exploit the economy). Going below 2 defeats the purpose. The sweet spot for most RP servers is 4.
Config.Interior — This is the world coordinates where the player’s camera sits during character selection. The default uses the aircraft carrier interior. You can change this to any interior you want — a custom apartment, a police station, whatever fits your server’s theme. Just make sure the interior is loaded (streamed) when the player connects.
Config.StartingApartment — When true, new characters get routed through qb-spawn’s apartment selection after creation. When false, they spawn at a default location. I recommend keeping this on — it gives new characters a home location and teaches players how the housing system works.
Step 5: Configure qb-spawn to Work With Multichar
This is the step people forget. qb-spawn needs to know that multichar is handling the initial connection. Open qb-spawn/config.lua:
Config = {}
Config.WaitTime = 5 -- seconds to wait for spawn data
Config.MaxSpawns = 8 -- max saved spawn locations
Config.LastLocationEnabled = true -- allow "last location" spawn option
-- IMPORTANT: Set this to true when using qb-multicharacter
Config.Houses = {}The critical thing is that qb-spawn should not be showing its own spawn selection screen on initial connect — that’s multichar’s job. In most current versions, qb-spawn detects qb-multicharacter automatically. But in older versions, you might need to check for a flag like Config.DontShowSpawnOnFirstConnect or similar. Read the config file in your specific version — they vary.
Step 6: Restart and Test
Restart your server completely. Don’t just ensure the resources — do a full restart. Then connect and you should see the character selection screen.
# In txAdmin or server console
restart qb-core
restart qb-multicharacter
restart qb-spawnActually, for first-time setup, just restart the entire server. Hot-reloading these core resources can cause weird state issues that waste your time debugging phantom problems.
Setting Up the Character Creation Flow
When a player clicks “Create New Character” on the selection screen, a few things happen in sequence:
- The multichar UI collects basic info (first name, last name, date of birth, gender, nationality)
- The character gets created in the database with a unique
citizenid - The player gets routed to the appearance menu (clothing/face customization)
- After appearance is saved, they either pick an apartment or spawn at a default location
If any step in this chain is broken, you’ll see problems. The most common issue is step 3 failing silently — the character gets created but the appearance menu never opens, leaving the player stuck on a black screen.
To debug this, check your server console for errors right after clicking “Create Character.” Nine times out of ten, the issue is your appearance resource not being started or not being compatible with your QBCore version.
Common Issues and Fixes
Black Screen After Character Selection
This is the number one issue. Player selects a character, the screen goes black, and nothing happens. Causes:
qb-spawn isn’t receiving the spawn signal. Check your server console for errors from qb-spawn. If multichar sends the “player selected” event but spawn doesn’t pick it up, the player gets stuck. Usually a version mismatch — make sure both resources are from the same QBCore release.
Missing position data. If a character’s position column in the database is NULL or contains invalid JSON, the spawn system doesn’t know where to put them. Fix it with a default position:
UPDATE players SET position = '{"x":-269.4,"y":-955.3,"z":31.2,"heading":205.8}'
WHERE position IS NULL;Appearance resource crashing. If qb-clothing or your appearance resource throws an error during character load, the whole chain stops. Check F8 console on the client side for NUI errors.
”Character Limit Reached” When Slots Are Available
Usually a database issue. The resource counts characters by querying rows where license matches the connecting player. If you’ve manually deleted characters from the database without properly cleaning up, orphaned rows can count against the limit.
-- Check how many characters a license has
SELECT citizenid, cid, charinfo FROM players
WHERE license = 'license:abc123xyz';If you see rows that shouldn’t be there, delete them — but be careful. Back up the table first.
Characters Not Saving
If character data (money, inventory, position) isn’t persisting between sessions, the issue isn’t multichar — it’s the core save system. QBCore saves player data on disconnect and at intervals. Check that qb-core isn’t throwing database errors. A common culprit is the charinfo column being too small to hold the JSON data. Increase its size:
ALTER TABLE `players` MODIFY `charinfo` TEXT;Duplicate citizenid Errors
This happens when two characters somehow get the same citizenid. It shouldn’t happen normally, but server crashes during character creation can cause it. Add a unique constraint if one doesn’t exist:
ALTER TABLE `players` ADD UNIQUE INDEX `citizenid_unique` (`citizenid`);Customizing the Selection UI
The default multichar UI is functional but plain. It’s an NUI (HTML/CSS/JS overlay), which means you can restyle it however you want. The files are in qb-multicharacter/html/.
Before you go wild customizing, know that every QBCore update might overwrite your changes if you pull from the repo. I’d recommend either forking the resource or keeping a separate CSS override file that you layer on top.
Some things worth customizing:
Background scene — Change Config.Interior to a more visually interesting location. Some servers use custom YMAP interiors, others use greenscreen rooms with a custom NUI background image.
Character card layout — The default shows name, job, and basic info. You can add bank balance, gang affiliation, phone number, or whatever data you want to show at a glance.
Animations — The default character model just stands there. You can trigger an animation or scenario on the ped during selection to make it look less static.
If you want something more polished without building it yourself, there are several premium multichar replacements on the market. Some of our scripts pair well with custom character systems — for example, LMX Multijob Pro works with multichar setups where players need different jobs across characters.
Performance Considerations
Multichar itself is lightweight — it only runs during the connection phase and goes dormant after the player loads in. But the way it interacts with other systems can cause performance issues if you’re not careful.
Database queries — Each time a player connects, multichar queries the players table for all characters under that license. On a large server with thousands of player records, this query can be slow if the table isn’t indexed properly. Make sure you have an index on the license column:
ALTER TABLE `players` ADD INDEX `license_index` (`license`);Character loading — When a player selects a character, QBCore loads their entire data set: inventory, job, gang, metadata, phone data, housing data, vehicles. If any of these systems are slow, the character load feels sluggish. Check your resmon after players connect to see which resources spike during the load phase.
Appearance caching — Loading character appearances (skin, clothing, hair) can cause a visible delay. Some appearance resources cache this data; others query fresh every time. If your players complain about slow character switching, look into whether your appearance resource supports caching.
Multichar on Qbox
If you’re running Qbox instead of QBCore, the multichar situation is a bit different. Qbox uses qbx_multicharacter, which is a fork optimized for the Qbox ecosystem. The setup process is similar, but the config options and internal events differ.
The biggest difference is that Qbox’s version integrates more tightly with ox_lib and ox_appearance. If you’re on Qbox, don’t try to use the vanilla qb-multicharacter — it’ll conflict with Qbox’s player loading system. Stick with the Qbox-specific version from their GitHub.
Not sure which framework you should be on? The framework comparison covers this in detail. And if you’re considering Qbox specifically, keep an eye on the blog — I’ll be writing more about Qbox-specific setups soon.
Tips From Running This on Real Servers
After helping configure multichar on more servers than I can count, here are patterns I’ve noticed:
Set character limits per permission level. The default config uses a single MaxCharacters value for everyone. But you can extend this with ace permissions — give VIP players or Patreon supporters extra character slots. It’s a good monetization hook that doesn’t affect gameplay balance. If you’re thinking about how to monetize your server, the monetization guide covers strategies that work.
Delete characters properly. When admins delete a character, they need to clean up across multiple tables — not just players. Apartments, vehicles, phone data, bank accounts, gang data — all of these reference citizenid. Leaving orphaned data behind causes bugs and bloats your database over time.
Test with multiple accounts. Don’t just test with your admin account. Use a second FiveM license (or have a friend connect) to test the full first-time player experience. Admins often have permissions that bypass issues regular players will hit.
Back up before updates. Whenever you update QBCore or multichar, back up your players table first. Schema changes in updates can break existing character data if the migration doesn’t run cleanly.
We also have a collection of free scripts that work alongside multichar setups if you’re building out your server on a budget. No sense paying for everything when solid free options exist for a lot of base features.
Wrapping Up
QBCore multichar is one of those things that’s straightforward once you understand the moving parts, but confusing if you just download and pray. Get the resource order right, make sure your database schema matches what the resource expects, and test the full character creation flow before opening your server to players.
If you get stuck, drop into the YBN Scripts Discord — there’s usually someone around who’s dealt with the exact same issue. And if you’re still building out your server’s core systems, the Lua scripting tutorial is worth reading before you start tweaking configs you don’t fully understand.