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.
Spawn bridge
Section titled “Spawn bridge”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
Section titled “SpawnBridge.doSpawn”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
Section titled “SpawnBridge.custom”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:
- Calling
KivoFirePlayerLoaded()on QBX and QBCore (it does nothing on ESX), unless your spawn script fires the player loaded event itself. - Placing the player and fading the screen back in.
- Calling
opts.onSpawned()when the player is in the world, if it is set.
KivoFirePlayerLoaded
Section titled “KivoFirePlayerLoaded”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.
Replace the spawn selector
Section titled “Replace the spawn selector”To use another spawn script with Kivo Multichar:
- In
config.lua, setConfig.spawnSelector = 'custom'. - Edit
SpawnBridge.custominshared/spawnbridge.lua. - Remove
ensure kivo-spawnfromserver.cfgif 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() endendCall 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() endendKeep 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.
Replace the identity creator
Section titled “Replace the identity creator”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.
Appearance layer
Section titled “Appearance layer”client/framework.lua defines these client globals.
KivoApplyPedAppearance
Section titled “KivoApplyPedAppearance”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.
KivoSkinModel
Section titled “KivoSkinModel”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
Section titled “KivoOpenAppearanceCreator”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.
Framework layer
Section titled “Framework layer”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. |
Login protection
Section titled “Login protection”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.
queryCharacters
Section titled “queryCharacters”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 |
kivo-multichar:selectCharacter
Section titled “kivo-multichar:selectCharacter”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.
kivo-multichar:server:createCharacter
Section titled “kivo-multichar:server:createCharacter”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.
kivo-multichar:server:deleteCharacter
Section titled “kivo-multichar:server:deleteCharacter”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. |
Appearance callbacks
Section titled “Appearance callbacks”| 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. |
Client events sent by the server
Section titled “Client events sent by the server”| 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) |
Discovery
Section titled “Discovery”The server sets GlobalState.kivoMultichar to the resource’s folder name. Kivo Spawn reads it to find Multichar whatever the folder is called.
Adapting the framework layer
Section titled “Adapting the framework layer”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.
