Kivo Character Suite Examples
Each example names the file and the setting to change. Per script details are on the pages for Multichar, Identity Creator and Spawn.
Example 1: full suite on QBX
Section titled “Example 1: full suite on QBX”server.cfg
ensure oxmysqlensure ox_libensure qbx_coreensure kivo-multi-charensure kivo-identity-creatorensure kivo-spawnNo config changes are needed. On the first start the console shows a CONFLICT line because qbx_core ships with useExternalCharacters = false. Type kivosetup in the server console and restart once.
What the player experiences:
- A new player connects and sees the selection scene. With no characters yet, the identity form opens straight away.
- They fill in the form. On QBX the height and nationality fields are shown by default.
- The character is created and logged in at the same moment (see Example 5). They appear at Multichar’s
Config.defaultSpawnand the appearance editor opens. - On the next connect they pick the character, press Play, and Kivo Spawn shows the location picker with a Last Location card.
Example 2: Multichar only
Section titled “Example 2: Multichar only”Use this when you want the selection screen but keep your framework’s own spawn handling.
-- kivo-multi-char/config.luaConfig.useIdentityCreator = false -- built-in dialog for creationConfig.spawnSelector = 'default' -- framework spawn selector, or direct teleportensure oxmysqlensure ox_libensure qb-coreensure kivo-multi-charThe built-in dialog asks for first name, last name, date of birth and gender only. See Example 4 for the values used for height and nationality.
Example 3: spawn selector choices
Section titled “Example 3: spawn selector choices”| Situation | What happens |
|---|---|
Config.spawnSelector = 'kivo-spawn' and kivo-spawn is running |
Kivo Spawn opens its location picker. |
Config.spawnSelector = 'kivo-spawn' but kivo-spawn is not running |
Multichar falls back to 'default' and prints a warning in the client console. |
Config.spawnSelector = 'default' on QBX with qbx_spawn running |
Multichar opens qbx_spawn. |
Config.spawnSelector = 'default' on QBCore |
Multichar opens qb-apartments (if running, together with qb-spawn), otherwise qb-spawn. |
Config.spawnSelector = 'default' with no spawn selector, or on ESX |
The player is teleported to their saved position (or Config.defaultSpawn) and the screen fades in. |
Config.spawnSelector = 'default' while kivo-spawn is started |
Kivo Spawn waits for Multichar’s hand-off, which never comes, so it stays idle. |
To use another selector, see Replace the spawn selector with Config.spawnSelector = 'custom'.
Example 4: what is saved
Section titled “Example 4: what is saved”Kivo Multichar collects a new character’s details in one of two ways:
Config.useIdentityCreator = true: Kivo Identity Creator.Config.useIdentityCreator = false, or Identity Creator not running: a built-inox_libinput dialog.
The open files do not include a hook for a third party identity form. To use another identity script, set Config.useIdentityCreator = false and remove the other script’s own creation step, or contact Kivo support.
What Multichar passes to your framework:
| Value | QBX | QBCore | ESX |
|---|---|---|---|
| First and last name | Yes | Yes | Yes |
| Date of birth | Yes, converted to YYYY-MM-DD |
Yes, converted to YYYY-MM-DD |
Yes, as entered (DD/MM/YYYY). 01/01/2000 when empty. |
| Gender | Yes | Yes | Yes |
| Nationality | Yes. Los Santos when not asked. |
Yes. Los Santos when not asked. |
Not stored by ESX |
| Height | Not stored by QBX | Not stored by QBCore | Yes. 180 when not asked. |
Names are trimmed and limited to 50 characters. Gender is read as female for female, f or 1, and as male for anything else, including an empty value.
On ESX, keep esx_identity removed in both cases. Two identity steps on one character conflict.
Example 5: create and login
Section titled “Example 5: create and login”On every framework, creating a character and logging in are one step, done by the framework itself:
| Framework | Call |
|---|---|
| QBX | exports.qbx_core:Login(src, false, newData) |
| QBCore | QBCore.Player.Login(src, false, newData), the same call qb-multicharacter uses |
| ESX | TriggerEvent('esx:onPlayerJoined', src, 'char<slot>', data), the same call esx_multicharacter uses |
What follows:
- The player confirms the identity form and the screen fades to black.
- Multichar’s server moves the player to the normal bucket (0) and runs the call above.
- QBX and QBCore: Multichar gives the framework’s starter items and sends the spawn instruction to the client with a “new character” flag. ESX: ESX loads the player and Multichar takes over from ESX’s player loaded event.
- The selection scene closes, the player is placed at the new character spawn and the appearance editor opens.
Consequences:
- There is no second Play click for a newly created character.
- Do not add another login call in
server/framework.lua. The character is already logged in, andqbx_coredrops a player who logs in twice. Multichar blocks duplicate logins itself (double clicks, or a resource restart while the player is in game). Config.defaultMoneysets the starting cash and bank on QBX and QBCore. ESX uses its ownConfig.StartingAccountMoney. The starting job always comes from the framework.
Example 6: new character spawn and appearance
Section titled “Example 6: new character spawn and appearance”| Step | QBX and QBCore | ESX |
|---|---|---|
| Spawn position | Config.defaultSpawn |
Config.esxNewCharSpawn, or Config.defaultSpawn when it is nil |
| Appearance editor | Multichar fires qb-clothes:client:CreateFirstCharacter, which illenium-appearance, qb-clothing and bl_appearance answer |
Multichar loads a base skin for the character’s gender with skinchanger:loadSkin, then opens esx_skin:openSaveableMenu, which esx_skin, illenium-appearance and bl_appearance answer |
| After the editor | The player is in the world | Multichar fires esx:onPlayerSpawn |
Returning ESX characters get their saved skin applied before they are placed in the world, and Multichar fires esx:onPlayerSpawn once they are there.
Example 7: routing buckets
Section titled “Example 7: routing buckets”- When the selector opens, the player is placed in routing bucket
Config.bucket(default732). - When a character is chosen or created, the player is moved back to bucket
0before the framework login. If the login fails, the player is put back intoConfig.bucket. - All players on the selection screen share bucket 732 with each other, and are separated from the main world.
Pick a Config.bucket number that no other resource on your server uses.
Example 8: multiple slots
Section titled “Example 8: multiple slots”-- kivo-multi-char/config.luaConfig.maxChars = 5 -- nobody can ever create more than 5Config.defaultSlots = 5 -- everybody starts with 5Give one player extra slots, or take some away, from the server console (not in game):
addslot <license> 2removeslot <license> 1<license> is the player’s license: or license2: identifier, including the prefix. Both are looked up. On QBX, prefer license2:, which is what qbx_core stores characters under. The change applies the next time that player connects.
Three limits to keep in mind:
- A slot above
Config.maxCharscannot be created, even if the player has been granted it. - The active scene needs a
charactersentry for every slot a player can use. The shippedscene_2has 5 entries. - Slot numbers must match the
idvalues in the scene (1, 2, 3 and so on). They are also the slot numbers saved in the database.
Example 9: demo mode
Section titled “Example 9: demo mode”| Mode | Setting | Use for |
|---|---|---|
| UI demo | Config.demo = true |
Checking scenes and the UI with mock characters from config_demo.lua. No framework or database needed. |
| Demo server | Config.demoServer = true |
QBX only. Shows three fixed slots (Michael, Trevor, Franklin) and teleports the player on Play, with no framework login. |
In both modes character creation and deletion are switched off and show a message to the player. Set both to false on a live server.
If you use Kivo Spawn in demo server mode, Multichar tells it that this is a demo server, so Kivo Spawn skips its framework lookups.
Example 10: folder names
Section titled “Example 10: folder names”Folder names do not matter. Each Kivo resource announces its own name when it starts, so Multichar finds Identity Creator and Kivo Spawn, and Kivo Spawn finds Multichar, whatever the folders are called.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause and fix |
|---|---|
A red CONFLICT line in the server console |
Run kivosetup in the server console and restart once. See installation step 3. |
| Two character menus, or kicked for “attempting to login twice” on QBX | Another multicharacter is running, or useExternalCharacters is false. Run kivosetup. |
| Characters list is empty on connect | The console line framework = … says nil: start your framework before Kivo Multichar. Also confirm Config.demo = false. |
| “No supported framework detected.” | None of qbx_core, qb-core or es_extended is running. |
| Stuck on the loading screen | Make sure your loading screen resource shuts down once the player session starts. Some setups use setr loadscreen:externalShutdown "false" in server.cfg. |
| Back does nothing on the identity form | Config.backEvent in Identity Creator was changed. Restore 'kivo-multichar:identityBack'. |
| Spawn picker never opens | Kivo Spawn is not started, or Config.spawnSelector is not 'kivo-spawn'. |
| Player spawns at the wrong place | Every entry in Config.spawnlocations needs a vector4 with a heading. A character with no saved position uses Multichar’s Config.defaultSpawn. |
| Duplicate identity step on ESX | Remove esx_identity from server.cfg. |
| ESX: “Loading the character failed” after 20 seconds | ESX could not load the character. Read the server console for es_extended errors. |
ESX reports Config.Multichar = false |
Restart the whole server, not only the resource, so ESX picks up Kivo Multichar. On older ESX builds, run kivosetup. |
| Selector area looks unloaded for some players | Raise Config.streaming.sceneTimeout and Config.streaming.collisionTimeout in Multichar. |
