Skip to content

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.

server.cfg

ensure oxmysql
ensure ox_lib
ensure qbx_core
ensure kivo-multi-char
ensure kivo-identity-creator
ensure kivo-spawn

No 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:

  1. A new player connects and sees the selection scene. With no characters yet, the identity form opens straight away.
  2. They fill in the form. On QBX the height and nationality fields are shown by default.
  3. The character is created and logged in at the same moment (see Example 5). They appear at Multichar’s Config.defaultSpawn and the appearance editor opens.
  4. On the next connect they pick the character, press Play, and Kivo Spawn shows the location picker with a Last Location card.

Use this when you want the selection screen but keep your framework’s own spawn handling.

-- kivo-multi-char/config.lua
Config.useIdentityCreator = false -- built-in dialog for creation
Config.spawnSelector = 'default' -- framework spawn selector, or direct teleport
ensure oxmysql
ensure ox_lib
ensure qb-core
ensure kivo-multi-char

The 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.

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'.

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-in ox_lib input 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.

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:

  1. The player confirms the identity form and the screen fades to black.
  2. Multichar’s server moves the player to the normal bucket (0) and runs the call above.
  3. 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.
  4. 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, and qbx_core drops a player who logs in twice. Multichar blocks duplicate logins itself (double clicks, or a resource restart while the player is in game).
  • Config.defaultMoney sets the starting cash and bank on QBX and QBCore. ESX uses its own Config.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.

  • When the selector opens, the player is placed in routing bucket Config.bucket (default 732).
  • When a character is chosen or created, the player is moved back to bucket 0 before the framework login. If the login fails, the player is put back into Config.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.

-- kivo-multi-char/config.lua
Config.maxChars = 5 -- nobody can ever create more than 5
Config.defaultSlots = 5 -- everybody starts with 5

Give one player extra slots, or take some away, from the server console (not in game):

addslot <license> 2
removeslot <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:

  1. A slot above Config.maxChars cannot be created, even if the player has been granted it.
  2. The active scene needs a characters entry for every slot a player can use. The shipped scene_2 has 5 entries.
  3. Slot numbers must match the id values in the scene (1, 2, 3 and so on). They are also the slot numbers saved in the database.
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.

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.

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.