QBCore Frameworkqbcore.netCommunity docs
On this page

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 = false

Replace 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

  1. Install qb-core and the database connector from your actual QBCore deployment recipe.
  2. Place qb-multicharacter at resources/[qb]/qb-multicharacter without renaming its resource folder.
  3. Install and configure qb-spawn. The verified manifest lists qb-core and qb-spawn as dependencies. It also imports @qb-apartments/config.lua and the oxmysql library, so the corresponding files must exist in the installed stack.
  4. For the upstream character-preview and clothing workflow, configure qb-clothing and qb-weathersync as expected by the pinned client. Use qb-apartments when your onboarding flow offers starting apartments.
  5. Start the dependencies before the character resource; use resource load order and QBCore installation for the full setup.
  6. 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:

SettingPurpose
Config.EnableDeleteButtonShow or hide character deletion in the selection UI
Config.SkipSelectionBypass ordinary spawn selection for a returning character
Config.DefaultSpawnFallback position when the new-character apartment flow is disabled
Config.InteriorInterior used for character preview
Config.PedCoords / Config.CamCoordsCharacter preview actor and camera
Config.HiddenCoordsHide the real player ped during selection
Config.customNationalityConfigure 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-apartments is started: open apartment/spawn setup.
  • Otherwise: send qb-spawn:client:setupSpawns and then qb-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 callbackSideWhat it does
qb-multicharacter:client:chooseCharClient eventOpens character selection
qb-multicharacter:server:setupCharactersServer callbackLoads characters for the player's license
qb-multicharacter:server:GetNumberOfCharactersServer callbackResolves default/per-license slot limit
qb-multicharacter:server:loadUserDataServer eventBegins login for the selected character
qb-multicharacter:server:createCharacterServer eventCreates a new character through framework login
qb-multicharacter:server:deleteCharacterServer eventDelegates deletion to QBCore player logic
qb-multicharacter:server:getSkinServer callbackReads 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

SymptomVerify
Character menu does not openFirst client/server error, qb-core load, qb-multicharacter state, qb-weathersync, preview interior and NUI files
Character slots do not changeEdit Config.DefaultNumberOfCharacters or the matching license override, not Config.MaxCharacters; restart the resource
Saved characters are missingCheck the player license in the players table and the server callback result; do not reset character IDs
Character previews have wrong clothingInspect qb-multicharacter:server:getSkin, the playerskins record, and your clothing implementation
New player remains on loading screenCheck startup order, the existing server login flow, apartments, qb-spawn, and the first console error
No spawn menu after choosing a characterVerify Config.SkipSelection and the qb-apartments branch, then inspect the qb-spawn setup
Deletion button is unavailableVerify 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.

Sources

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.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website