Skip to content

Kivo Multichar Exports and Integration

Kivo Multichar does not declare any exports. It connects to other scripts through four open files:

File What it is for
shared/spawnbridge.lua Client side bridge that decides how a returning character is spawned. Edit it to use your own spawn script.
client/framework.lua Client side appearance layer: applies saved skins to the preview peds, opens the first-character appearance editor, and handles the spawn after login.
server/framework.lua Server side layer that lists, creates, logs in and deletes characters for QBX, QBCore and ESX.
shared/framework.lua Detects the framework and sets Config.framework.

These files are left open on purpose. Keep the function names, arguments and return shapes listed below, because the rest of the resource calls them.

shared/spawnbridge.lua defines a global table SpawnBridge on the client. It exists inside the Kivo Multichar resource only. It is not an export.

SpawnBridge.doSpawn(spawnCoords, opts)
Side Client
spawnCoords vector4 (x, y, z, heading): the character’s last saved position, or Config.defaultSpawn
opts.cData Optional. The character’s citizenid, cid, charinfo and position (QBX and QBCore), for spawn resources that need them.
opts.onSpawned Optional. Called once the player is standing in the world. ESX uses it to fire esx:onPlayerSpawn.
Returns Nothing

Multichar calls it after a returning character is logged in and the selection scene is gone. The screen is black at that moment. It reads Config.spawnSelector:

Config.spawnSelector Action
'kivo-spawn' If Kivo Spawn is running: fires the framework’s player loaded event (QBX and QBCore), fires kivo:client:readyForSpawn with (spawnCoords, false, Config.demoServer == true) and calls opts.onSpawned when Kivo Spawn reports the player as spawned. If Kivo Spawn is not running, continues as 'default'.
'custom' Calls SpawnBridge.custom(spawnCoords, opts) and stops.
anything else Continues as 'default'.

'default' opens your framework’s spawn selector: qbx_spawn on QBX, qb-apartments with qb-spawn or qb-spawn alone on QBCore. Those resources fire the player loaded event themselves once the player picks a location. If none is running, or on ESX, the bridge teleports the player to spawnCoords (waiting for the ground to load), fires the player loaded event, fades in over 500 ms and calls opts.onSpawned.

SpawnBridge.custom(spawnCoords, opts)

Your hook. The shipped version teleports the player and fades in, so nobody is stranded. When you replace it, you are responsible for:

  1. Calling KivoFirePlayerLoaded() on QBX and QBCore (it does nothing on ESX), unless your spawn script fires the player loaded event itself.
  2. Placing the player and fading the screen back in.
  3. Calling opts.onSpawned() when the player is in the world, if it is set.
KivoFirePlayerLoaded()

Client global. Fires the QBX or QBCore player loaded event exactly once. It sends QBCore:Server:OnPlayerLoaded and only fires QBCore:Client:OnPlayerLoaded locally when the server does not echo it back (QBX, and older QBCore). Firing the client event twice would run every player loaded handler on your server twice. Does nothing on ESX.

To use another spawn script with Kivo Multichar:

  1. In config.lua, set Config.spawnSelector = 'custom'.
  2. Edit SpawnBridge.custom in shared/spawnbridge.lua.
  3. Remove ensure kivo-spawn from server.cfg if you no longer use Kivo Spawn.

Fire an event of your spawn script

function SpawnBridge.custom(spawnCoords, opts)
KivoFirePlayerLoaded()
TriggerEvent('mySpawn:openSelector', spawnCoords) -- placeholder event name
if opts.onSpawned then opts.onSpawned() end
end

Call an export, with a fallback

function SpawnBridge.custom(spawnCoords, opts)
KivoFirePlayerLoaded()
if GetResourceState('my_spawn') == 'started' then -- placeholder resource name
exports['my_spawn']:open(spawnCoords) -- placeholder export
else
local ped = PlayerPedId()
SetEntityCoords(ped, spawnCoords.x, spawnCoords.y, spawnCoords.z, false, false, false, true)
SetEntityHeading(ped, spawnCoords.w or 0.0)
SetEntityVisible(ped, true, false)
FreezeEntityPosition(ped, false)
DoScreenFadeIn(500)
end
if opts.onSpawned then opts.onSpawned() end
end

Keep a framework spawn selector such as qb-spawn or qbx_spawn

No code needed. Set Config.spawnSelector = 'default' and keep that resource started.

my_spawn, mySpawn:openSelector and open are placeholders. Use the real names from the script you are connecting.

Use Kivo Spawn with another multicharacter

Section titled “Use Kivo Spawn with another multicharacter”

See Using Kivo Spawn with another multicharacter script.

Multichar supports Kivo Identity Creator (Config.useIdentityCreator = true) or its built-in dialog (false). The open files contain no hook for a third party identity form. See Replacing the identity creator.

client/framework.lua defines these client globals.

KivoApplyPedAppearance(ped, skin)

Applies a saved skin (a table or a JSON string) to any ped. Multichar uses it for the preview peds. The applier is chosen from the skin’s format:

Format Recognised by Applied with
illenium-appearance / fivem-appearance components, props, headBlend or faceFeatures The running resource’s setPedAppearance export, with a built-in fallback if the export is missing or fails
skinchanger (esx_skin) sex, tshirt_1, torso_1 or pants_1 Built-in, because skinchanger:loadSkin only works on the player ped
qb-clothing pants, torso2, t-shirt or face tables Built-in

To support another appearance format, add a branch to detectSkinFormat and an applier for it.

local model = KivoSkinModel(skin)

Returns the ped model a saved skin wants (the model of an illenium or fivem-appearance skin, or the freemode model for a skinchanger sex), or nil.

KivoOpenAppearanceCreator({ isFemale = false, onDone = function() end })

Opens the first-character appearance editor after a new character is created.

Framework What it does
QBX, QBCore Fires qb-clothes:client:CreateFirstCharacter, which illenium-appearance, qb-clothing and bl_appearance answer. With only upstream fivem-appearance running, it calls its startPlayerCustomization export on a freemode ped of the right gender.
ESX Loads a base skin for the gender with skinchanger:loadSkin, then fires esx_skin:openSaveableMenu, which esx_skin, illenium-appearance and bl_appearance answer. onDone runs when the editor closes.

If no appearance resource is running, the player is put on a freemode model of the right gender and no editor opens.

server/framework.lua registers these server side events and callbacks.

Name Type Direction Purpose
queryCharacters(src) Global function (server) Called by Multichar when the selector opens Returns chars, slotCount.
KivoIsLoggedIn(src) Global function (server) Called by Multichar true if the player already has a loaded character.
kivo-multichar:selectCharacter Net event Client to server Logs the chosen character in.
kivo-multichar:server:createCharacter lib.callback Client to server Creates a character and logs it in.
kivo-multichar:server:deleteCharacter lib.callback Client to server Deletes a character.
kivo-multichar:server:getQBPedData lib.callback Client to server Saved appearance for a QBX or QBCore character.
kivo-multichar:server:getESXPedData lib.callback Client to server Saved appearance for an ESX character.

Every login and every creation goes through a per player lock plus an “already logged in” check. A second request while one is running, or for a player who already has a character loaded, is refused. This prevents double logins from double clicks, and from a resource restart while players are in game. qbx_core drops a player who logs in twice. Do not add your own login calls.

local chars, slotCount = queryCharacters(src)

Returns a table indexed by slot number, and the number of slots the player has.

Framework Fields per character
QBX, QBCore citizenid, name, gender ('Male' or 'Female'), cash, bank, job, location, position
ESX identifier, name, gender, dateofbirth, cash, bank, job, job_grade, skin
Demo The entries of Config.demoData[Config.defaultScene] (see config_demo.lua)

Which identifier is used to find characters:

Framework Characters looked up under
QBX license2, then license (the same as qbx_core)
QBCore license only. QBCore.Player.Login only accepts the plain license, so rows stored under license2 are not offered.
ESX char<slot>:<identifier>, with the identifier from ESX.GetIdentifier
TriggerServerEvent('kivo-multichar:selectCharacter', { slot = 1, citizenid = 'ABC12345', spawnCoords = coords })
data field Used by Description
citizenid QBX, QBCore The character to log in.
identifier ESX The character identifier, char<slot>:<identifier>.
spawnCoords All Position passed on to the spawn step.
slot All The slot number. Only used in log messages.

The server checks that the player owns the character, moves them to bucket 0 and logs them in (exports.qbx_core:Login, QBCore.Player.Login, or esx:onPlayerJoined with the char<slot> prefix). On QBX and QBCore it then sends kivo-multichar:client:doSpawn. On ESX, ESX’s own esx:playerLoaded event takes over. On failure the player sees a message and the selector stays usable.

local result = lib.callback.await('kivo-multichar:server:createCharacter', false, {
slot = 1,
charinfo = {
firstname = 'Jane',
lastname = 'Doe',
dateofbirth = '21/04/1995', -- DD/MM/YYYY, converted to YYYY-MM-DD for QBX and QBCore
gender = 'female', -- 'female', 'f' or 1 is female; anything else is male
nationality = 'Los Santos', -- QBX and QBCore
height = 175, -- ESX
},
})
Side Server (called from the client)
Slot rule A whole number from 1 to the player’s slot allowance, and never above Config.maxChars
Required firstname and lastname: text, trimmed, at most 50 characters

Return value:

Field Description
success true or false.
reason On failure, the message shown to the player.
shouldSpawn true on success. The player is already logged in.
character The new character’s panel data (QBX and QBCore).

Failure messages: Character creation is disabled in demo mode., Invalid request., Invalid slot., Missing character info., You are already logged in., Slot already occupied., Framework rejected character creation., No supported framework detected.

What it does: QBX and QBCore call Login(src, false, newData), which creates the character and logs the player in, then give the framework’s starter items and send doSpawn with the new character flag. ESX fires esx:onPlayerJoined(src, 'char<slot>', data), which makes ESX create and load the character. See create and login.

local result = lib.callback.await('kivo-multichar:server:deleteCharacter', false, { citizenid = 'ABC12345' })
-- ESX: { identifier = 'char1:...' }

Returns { success = true } or { success = false, reason = '...' }. Refused when Config.allow.self.delete = false, in demo mode, when the player does not own the character, or when the player already has a character loaded.

Framework What is deleted
QBX The qbx_core DeleteCharacter export, which cleans every table qbx_core knows about.
QBCore QBCore.Player.ForceDeleteCharacter, which cleans QBCore’s player tables.
ESX The row in users. Data in other tables stays until you clean it up.
Callback Argument Returns
kivo-multichar:server:getQBPedData citizenid skin, model from playerskins where active = 1. A model stored as a number in text (qb-clothing) is returned as a number.
kivo-multichar:server:getESXPedData identifier The skin column of users, only for the player’s own characters.
Event Arguments
kivo-multichar:client:doSpawn spawnCoords (vector4), isNew (boolean), cData (citizenid, cid, charinfo, position)
kivo-multichar:client:selectFailed none. Re-enables the Play button after a refused login.
kivo-multichar:client:notify type (for example 'error'), message (text)

The server sets GlobalState.kivoMultichar to the resource’s folder name. Kivo Spawn reads it to find Multichar whatever the folder is called.

Use a different appearance table. If your appearance script stores skins elsewhere, edit the query in getQBPedData and keep returning skin, model:

local ok, row = pcall(MySQL.single.await,
'SELECT skin, model FROM my_appearance_table WHERE citizenid = ? AND active = 1', -- placeholder table
{ citizenid })

Change the starter items. QBX starter items come from qbx_core’s config/shared.lua (starterItems), QBCore’s from QBCore.Shared.StarterItems. Change them there. To give nothing, empty that list, or remove the giveStarterItems call in the create callback.

Add values to a new QBX or QBCore character. Add fields to the newData table in the create callback (for example metadata). The framework fills in everything you leave out.

Another framework. The open files support QBX, QBCore and ESX. For another framework, no characters are listed and creation reports that no supported framework was detected. Contact Kivo support if you need one added.