Kivo Multichar Configuration
Kivo Multichar has these editable files:
config.luaconfig_demo.luashared/framework.luashared/spawnbridge.luaclient/framework.luaserver/framework.lua
The last four are covered on Exports and integration. This page covers the two config files.
General
Section titled “General”| 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).
Spawn selector and spawn positions
Section titled “Spawn selector and spawn positions”| 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'.
Defaults for new characters
Section titled “Defaults for new characters”| 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).
Scene streaming
Section titled “Scene streaming”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. |
Scenes
Section titled “Scenes”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 }, },}Scene fields
Section titled “Scene fields”| 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. |
Character entry fields
Section titled “Character entry fields”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. |
Shipped scenes
Section titled “Shipped scenes”| 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.
Demo mode
Section titled “Demo mode”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_demo.lua
Section titled “config_demo.lua”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.
Console commands
Section titled “Console commands”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.
Debug commands
Section titled “Debug commands”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. |
Framework detection
Section titled “Framework detection”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.
