Updated 2026-10-09 · 7 min read
qb-multicharacter
qb-multicharacter manages character slots and the character-selection screen on QBCore servers.
It loads an existing character or creates a new one, then hands the player into the configured
spawn/apartment flow. The upstream config uses Config.DefaultNumberOfCharacters and
Config.PlayersNumberOfCharacters, not a generic Config.MaxCharacters setting.
This reference is based on qb-multicharacter commit 85a03c4. Server forks and appearance replacements may implement different events or persistence rules.
Quick answer
To set the number of character slots, edit qb-multicharacter/config.lua:
-- Default number of character slots per Rockstar license.
Config.DefaultNumberOfCharacters = 5
-- Optional per-license overrides.
Config.PlayersNumberOfCharacters = {
{ license = 'license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', numberOfChars = 2 },
}
-- Whether users can delete their own characters from the UI.
Config.EnableDeleteButton = true
-- Set true to bypass normal spawn selection and use last location.
Config.SkipSelection = falseReplace the example license with the real identifier for a test account, or leave the override table empty when you only need the site-wide default. The application has to load the edited config and resource before the UI reflects it.
See the verified config.lua
for all current options.
Installation & Setup
- Install
qb-coreand the database connector from your actual QBCore deployment recipe. - Place qb-multicharacter at
resources/[qb]/qb-multicharacterwithout renaming its resource folder. - Install and configure
qb-spawn. The verified manifest listsqb-coreandqb-spawnas dependencies. It also imports@qb-apartments/config.luaand theoxmysqllibrary, so the corresponding files must exist in the installed stack. - For the upstream character-preview and clothing workflow, configure
qb-clothingandqb-weathersyncas expected by the pinned client. Useqb-apartmentswhen your onboarding flow offers starting apartments. - Start the dependencies before the character resource; use resource load order and QBCore installation for the full setup.
- Test a first character, an existing character, a reconnect, and a second character on staging.
The official
README
lists the supporting resources. Do not replace your application's entire server.cfg with
isolated snippets from a character UI tutorial.
Configuration
Character slot limits
Config.DefaultNumberOfCharacters is the ordinary number of available character slots.
Config.PlayersNumberOfCharacters is an array of overrides, each with a Rockstar license and
numberOfChars. The
server callback
qb-multicharacter:server:GetNumberOfCharacters reads these values when the selection menu opens.
The shipped UI is designed around up to five default characters. A larger configured number alone does not prove a modified UI supports that many; inspect and test the deployed NUI first.
Character preview and deletion
The upstream config.lua includes:
| Setting | Purpose |
|---|---|
Config.EnableDeleteButton | Show or hide character deletion in the selection UI |
Config.SkipSelection | Bypass ordinary spawn selection for a returning character |
Config.DefaultSpawn | Fallback position when the new-character apartment flow is disabled |
Config.Interior | Interior used for character preview |
Config.PedCoords / Config.CamCoords | Character preview actor and camera |
Config.HiddenCoords | Hide the real player ped during selection |
Config.customNationality | Configure the nationality input mode |
Config.DefaultSpawn is a vector3 in this revision. There is no upstream
Config.AllowCharacterDeletion or Config.AssignApartment setting. Editing those invented
settings will not affect the pinned resource.
Player Experience
Existing character
The client opens the selection menu via qb-multicharacter:client:chooseChar and requests
character information from the server through qb-multicharacter:server:setupCharacters.
A selected character is sent through qb-multicharacter:server:loadUserData, which calls the
framework's player login mechanism.
After login, the server loads house data and chooses the appropriate route:
Config.SkipSelection = true: restore the last saved location.- Otherwise, when
qb-apartmentsis started: open apartment/spawn setup. - Otherwise: send
qb-spawn:client:setupSpawnsand thenqb-spawn:client:openUI.
This sequence is implemented in the upstream
server.lua.
Do not register a second loadUserData handler just to change the UI: a duplicate network
handler can interfere with login and authorization.
New character
A new character is submitted through the existing NUI and the server event
qb-multicharacter:server:createCharacter. The framework creates the player record, then the
server chooses the starting-apartment or fallback-spawn path. The upstream gives starter items
using the installed qb-inventory export; inspect that dependency before swapping inventories.
Character-name rules, slot ownership, and creation limits must be enforced by the framework
and the deployed server implementation. Do not trust a client-selected citizenid or slot count
as authorization on its own.
Delete a character
When deletion is enabled, the upstream event qb-multicharacter:server:deleteCharacter calls
QBCore.Player.DeleteCharacter with the requesting player and citizen ID. It does not expect
you to write your own SQL deletion handler. Treat character deletion as irreversible unless you
have verified restorations from backups.
API Reference
Use the registered public names from the pinned server and client source:
| Event or callback | Side | What it does |
|---|---|---|
qb-multicharacter:client:chooseChar | Client event | Opens character selection |
qb-multicharacter:server:setupCharacters | Server callback | Loads characters for the player's license |
qb-multicharacter:server:GetNumberOfCharacters | Server callback | Resolves default/per-license slot limit |
qb-multicharacter:server:loadUserData | Server event | Begins login for the selected character |
qb-multicharacter:server:createCharacter | Server event | Creates a new character through framework login |
qb-multicharacter:server:deleteCharacter | Server event | Delegates deletion to QBCore player logic |
qb-multicharacter:server:getSkin | Server callback | Reads the active character appearance record |
These names document the installed upstream integration, not a suggestion to expose the server events through new UI buttons or unauthenticated scripts. Server-side authorization must remain with the existing handlers.
Database and Appearance
The upstream character selector reads player rows from the QBCore players table by Rockstar
license and looks up active appearance data in playerskins. The exact table owners and schemas
depend on your installed qb-core, qb-clothing, and database revisions.
Do not run generic ALTER TABLE players scripts or create a character_meta table from an
unrelated example. Do not create an extra player_outfits table unless the installed appearance
resource explicitly ships and requires that migration.
Use QBCore database schema, qb-clothing, and resource update conflicts for a source-backed migration plan. Back up the existing database and test a restore before changing character storage.
Troubleshooting
| Symptom | Verify |
|---|---|
| Character menu does not open | First client/server error, qb-core load, qb-multicharacter state, qb-weathersync, preview interior and NUI files |
| Character slots do not change | Edit Config.DefaultNumberOfCharacters or the matching license override, not Config.MaxCharacters; restart the resource |
| Saved characters are missing | Check the player license in the players table and the server callback result; do not reset character IDs |
| Character previews have wrong clothing | Inspect qb-multicharacter:server:getSkin, the playerskins record, and your clothing implementation |
| New player remains on loading screen | Check startup order, the existing server login flow, apartments, qb-spawn, and the first console error |
| No spawn menu after choosing a character | Verify Config.SkipSelection and the qb-apartments branch, then inspect the qb-spawn setup |
| Deletion button is unavailable | Verify Config.EnableDeleteButton and the deployed menu implementation |
Use multicharacter loading troubleshooting for a reproducible diagnosis before deleting player or appearance data.
Frequently Asked Questions
How many characters can a player create?
The upstream default is five slots. Change Config.DefaultNumberOfCharacters for the standard
limit or Config.PlayersNumberOfCharacters for a license-specific override. Verify the deployed
selection UI before exceeding the default supported design.
How do I disable character deletion?
Set Config.EnableDeleteButton = false in qb-multicharacter/config.lua. This controls the
upstream UI and server event guard; still protect administrative and database access separately.
How do I spawn at the last location?
Config.SkipSelection = true bypasses the normal selector for an existing character. If you want
players to choose from public points, keep it false and configure
QB.Spawns in qb-spawn.
Does qb-multicharacter create its own SQL tables?
The verified source relies on existing QBCore player data and an active appearance record. Import only SQL explicitly required by the exact QBCore and appearance resources you deploy.
Related Resources
- qb-spawn — public spawns, last location and the NUI handoff
- qb-apartments — starting apartments
- qb-clothing — character appearance
- qb-inventory — starter items
- QBCore player data — ownership and persistence
- Multicharacter loading troubleshooting
Sources
- qb-multicharacter source (pinned revision)
- Configuration
- Server events and callbacks
- Client and NUI flow
- Resource manifest
Source reviewed on 2026-10-09. This is a code review, not an in-game validation on a FiveM staging server. Keep your deployed revision and test environment as the compatibility baseline.
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
qb-houses
Source-backed qb-houses guide covering the current shell/furniture housing system, ownership records, keyholders, stashes, house garages and official dependencies.
qb-spawn
Configure qb-spawn with the actual QB.Spawns table, connect character and apartment selection, and fix missing spawn menus on QBCore.
