Skip to content

Kivo Multichar Configuration

Kivo Multichar has these editable files:

  • config.lua
  • config_demo.lua
  • shared/framework.lua
  • shared/spawnbridge.lua
  • client/framework.lua
  • server/framework.lua

The last four are covered on Exports and integration. This page covers the two config files.

Option Default Description
Config.debug true Prints debug messages to the server and client consoles and turns on the /startchar, /stopchar and /freecam commands for every player. Use it while you set up scenes and set it to false on a live server.
Config.locale 'en' Language code. The current version ships English text only, so changing it has no effect.
Config.demo false true uses the mock data in config_demo.lua instead of database queries. Must be false on a live server. See Demo mode.
Config.manageTime true true sets the game clock to the scene’s time while the selector is open.
Config.allow.self.delete true true lets players delete their own characters from the selection screen. false turns the option off.
Config.bucket 732 Routing bucket that isolates players during character selection. Use a number no other resource uses.
Config.defaultScene 'scene_2' Name of the scene (a key of Config.scenes) that loads on connect.
Config.maxChars 5 Hard cap. A character can never be created in a slot above this number.
Config.defaultSlots 5 Slots for players with no override. addslot and removeslot adjust from this.
Config.useIdentityCreator true true opens Kivo Identity Creator when a player creates a character. false uses a built-in ox_lib dialog (first name, last name, date of birth, gender). If Identity Creator is not running, the built-in dialog is used anyway.
Config.identityCreatorResource 'kivo-identity-creator' Only needed with Identity Creator builds older than 1.5.0. Current builds announce their folder name themselves.

Slots work like this: Config.defaultSlots is how many slots a player gets. Config.maxChars is the highest slot number that can ever be used. The scene must also have a characters entry for every slot a player can use (see Scenes).

Option Default Description
Config.spawnSelector 'kivo-spawn' Which spawn system runs after a returning character is logged in. Valid values: 'kivo-spawn', 'default', 'custom'.
Config.defaultSpawn vector4(-269.4, -955.3, 31.22, 208.0) Fallback spawn if a character has no saved position. Also where a newly created character is placed. x, y, z, heading.
Config.esxNewCharSpawn nil ESX only. Where to place the player during first-character appearance creation. nil uses Config.defaultSpawn.

Config.spawnSelector values:

Value What happens
'kivo-spawn' Multichar fades the screen out and fires kivo:client:readyForSpawn so Kivo Spawn shows its selector. If Kivo Spawn is not running, Multichar falls back to 'default'.
'default' QBX: opens qbx_spawn. QBCore: opens qb-apartments (when running together with qb-spawn), otherwise qb-spawn. If none of these is running, and always on ESX, the player is teleported to their position and the screen fades in.
'custom' Calls SpawnBridge.custom() in shared/spawnbridge.lua. Edit that function to use any third party selector. See Replace the spawn selector.

Any other value behaves like 'default'.

Option Default Description
Config.defaultMoney.cash 500 Starting cash on QBX and QBCore.
Config.defaultMoney.bank 5000 Starting bank balance on QBX and QBCore.
Config.defaultJob { name = 'unemployed', grade = 0 } Not used since 1.5.0. New characters get the framework’s default job.

On ESX, starting money comes from ESX’s own Config.StartingAccountMoney, because ESX creates the character itself. New QBX and QBCore characters also receive the framework’s starter items (qbx_core starterItems, or QBCore.Shared.StarterItems).

Controls how long the client waits for the scene area to load before showing it. The defaults are generous on purpose, because a remote server on a player’s first connect streams slower than a local test server. Raise the timeouts if players on slow connections still see an unloaded area.

Option Default Description
Config.streaming.radius 500.0 Radius, in metres, of the area loaded around the scene.
Config.streaming.sceneTimeout 20000 Maximum milliseconds to wait for the scene to report loaded.
Config.streaming.collisionTimeout 10000 Maximum milliseconds to wait for collision around the player ped.
Config.streaming.settleDelay 250 Milliseconds to wait for textures and LODs to arrive after the waits above.

Config.scenes holds one entry per scene. Config.defaultScene picks which one loads. A scene only defines visuals. The text on the panel (name, job, cash and so on) comes from the database, or from config_demo.lua in demo mode.

Config.scenes = {
scene_2 = {
totalSlots = 5,
lockedSlots = {},
time = { hour = 22, minute = 0 },
hub = {
camCoords = vector3(-1891.5763, -1241.5302, 24.8024),
camRot = vector3(-16.8177, 0.0000, -59.5295),
},
characters = {
{
id = 1,
alwaysSpawn = true,
coords = vector4(-1850.1757, -1239.6500, 7.6158, 140.3702),
camCoords = vector3(-1852.3617, -1241.0260, 9.3529),
camRot = vector3(-8.0899, -0.0000, -56.7587),
model = 'mp_m_freemode_01',
animDict = 'amb@world_human_leaning@female@wall@back@holding_elbow@idle_a',
animName = 'idle_a',
approach = {
{ camCoords = vector3(-1864.4683, -1247.9441, 12.9597), camRot = vector3(-15.8549, 0.0000, -65.9619) },
},
},
-- more entries
},
},
}
Field Description
totalSlots How many slots the screen shows.
lockedSlots List of slot numbers shown as locked. In normal operation Multichar locks every slot above the player’s allowance instead, so you rarely need to edit this.
time.hour, time.minute Game clock while the selector is open. Used when Config.manageTime is true.
hub.camCoords, hub.camRot The central camera position. When the player switches slot, the camera travels through the hub on its way to the next slot. Required.
characters List of slot entries. See below.

Each entry is a visual template for one slot.

Field Type Description
id number The slot number. Must be unique, start at 1, and match the slot numbers saved in the database. This is not the same as the position in the list.
alwaysSpawn boolean true keeps the slot’s ped in place after the camera moves on to another slot. All shipped scenes use true.
coords vector4 Where the ped stands. x, y, z, heading.
camCoords, camRot vector3 Camera position and rotation when this slot is selected.
model string Ped model shown for this slot.
animDict, animName string Animation the ped plays.
approach list Camera waypoints between the hub and this slot, each with camCoords and camRot. Use {} for none. Always include the field.
Scene Slots shown Entries in characters Time
scene_1 5 2 17:30
scene_2 (default) 5 5 22:00
scene_3 2 2 21:00

scene_3 is set inside an Eclipse Towers apartment. The interior must be loaded on your server (for example with bob74_ipl), otherwise the peds stand in an empty shell.

Two modes exist for testing.

Mode Option What it does
UI demo Config.demo = true Uses mock data from config_demo.lua. No framework or database needed. Creating and deleting characters is switched off. Pressing play spawns the player with no framework login.
Demo server Config.demoServer = true QBX only. Shows three fixed slots and locks the rest. Pressing play teleports the player to Config.defaultSpawn with no framework login.

Demo server options:

Option Default Description
Config.demoServer false Turns demo server mode on.
Config.demoServerModels { 'player_zero', 'player_two', 'player_one' } Ped models for the three slots.
Config.demoServerNames { 'Michael', 'Trevor', 'Franklin' } Names shown on the three slots.

Config.demoData holds the mock characters used when Config.demo = true. It is keyed by scene name, then by slot number.

Config.demoData = {
scene_2 = {
[1] = { pfp = 'profil.png', name = 'CHAR ONE' },
[2] = { pfp = 'profil.png', name = 'CHAR TWO' },
[3] = { pfp = 'profil.png', name = 'CHAR THREE' },
},
}
Field Description
pfp Portrait image file name. The default is 'profil.png'.
name Name shown on the panel.
gender Text such as 'Female'.
cash, bank Numbers shown on the panel.
age Number.
location Text such as 'Los Santos'.
job Text such as 'Unemployed'.

You can leave out any field you do not want to show. The demo data that is used is the entry for Config.defaultScene. If that scene has no entry in Config.demoData, no characters are shown. In demo mode the slot count equals Config.maxChars.

Run these in the server console (or the txAdmin live console), not in game.

Command Description
addslot <license> [amount] Adds amount slots (default 1) to the player’s allowance. Applies on their next connect.
removeslot <license> [amount] Removes amount slots (default 1). The allowance never drops below 1.
kivosetup Fixes the conflicts reported at startup: stops other multicharacter resources for the session, and sets useExternalCharacters = true (QBX) or Config.Multichar = true (older ESX). Keeps a .kivo-backup copy of changed files. Restart the server once afterwards.

<license> is the player’s license: or license2: identifier, including the prefix. Both are looked up, the one the framework stores characters under first (license2: on QBX, license: on QBCore). For a player with no override yet, the change starts from Config.defaultSlots.

Available while Config.debug = true, for every player.

Command Description
/startchar [scene] Opens the selector with a scene (default Config.defaultScene) so you can preview it.
/stopchar Closes it again.
/freecam Free camera to read coordinates for scenes and for Kivo Spawn. See capture coordinates with freecam.

shared/framework.lua runs on both client and server when the resource starts and sets Config.framework.

Order Resource checked Config.framework
1 qbx_core started or starting 'qbx'
2 qb-core started or starting 'qb'
3 es_extended started or starting 'esx'
none nothing above nil (no characters are listed, and creation reports that no supported framework was found)

If the framework starts after Multichar, the server detects it again once the framework has started, and prints a reminder to fix the start order. The detected framework is printed in the server console on every start.