# 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](https://github.com/qbcore-fivem/qb-multicharacter/tree/85a03c4f3bdc100e898b9fb65614a9ce914fe926).
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`:

```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`](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/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](https://github.com/qbcore-fivem/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](/docs/troubleshooting/resource-load-order) and
   [QBCore installation](/docs/installation) for the full setup.
6. Test a first character, an existing character, a reconnect, and a second character on staging.

The official
[README](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/README.md)
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](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/server.lua)
`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-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](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/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](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/server.lua)
and [client source](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/client.lua):

| 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](/docs/database/core-schema),
[qb-clothing](/docs/resources/qb-clothing), and
[resource update conflicts](/docs/troubleshooting/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](/docs/resources/qb-spawn) |
| Deletion button is unavailable | Verify `Config.EnableDeleteButton` and the deployed menu implementation |

Use [multicharacter loading troubleshooting](/docs/troubleshooting/multicharacter-loading)
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](/docs/resources/qb-spawn#spawn-locations).

### 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](/docs/resources/qb-spawn) — public spawns, last location and the NUI handoff
- [qb-apartments](/docs/resources/qb-apartments) — starting apartments
- [qb-clothing](/docs/resources/qb-clothing) — character appearance
- [qb-inventory](/docs/resources/qb-inventory) — starter items
- [QBCore player data](/docs/core/player-data) — ownership and persistence
- [Multicharacter loading troubleshooting](/docs/troubleshooting/multicharacter-loading)

## Sources

- [qb-multicharacter source (pinned revision)](https://github.com/qbcore-fivem/qb-multicharacter/tree/85a03c4f3bdc100e898b9fb65614a9ce914fe926)
- [Configuration](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/config.lua)
- [Server events and callbacks](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/server.lua)
- [Client and NUI flow](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/client.lua)
- [Resource manifest](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/fxmanifest.lua)

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.
