Skip to content

Kivo Multichar Examples

This is the config a new install starts with, listed as the values you are most likely to change. None of them has to be changed for the script to work.

Config.demo = false
Config.bucket = 732
Config.defaultScene = 'scene_2'
Config.maxChars = 5
Config.defaultSlots = 5
Config.useIdentityCreator = true
Config.spawnSelector = 'kivo-spawn'
Config.defaultSpawn = vector4(-269.4, -955.3, 31.22, 208.0)
Config.defaultMoney = { cash = 500, bank = 5000 }
Config.useIdentityCreator = false
Config.spawnSelector = 'default'

Only kivo-multi-char (and its dependencies) needs to be started. Players get the built-in creation dialog, and returning characters are handed to your framework’s spawn selector (qbx_spawn, qb-apartments or qb-spawn) or teleported to their saved position.

Config.maxChars = 5
Config.defaultSlots = 3

Everybody starts with three slots. Slots 4 and 5 show as locked until you grant them with addslot. The scene must still have a characters entry for every slot a player can reach. The shipped scene_2 has five.

  1. Copy an existing scene block in Config.scenes and give it a new key, such as my_scene.
  2. Set totalSlots, time and the hub camera.
  3. Give each slot a characters entry with a unique id (1, 2, 3 and so on), a ped position, a camera, a model and an animation. Use approach = {} when the camera can go straight from the hub to the slot.
  4. Set Config.defaultScene = 'my_scene'.
  5. In demo mode, add matching entries to Config.demoData.my_scene in config_demo.lua.
  6. Restart kivo-multi-char, then preview it with /startchar my_scene (debug on) and close it with /stopchar.
Config.scenes.my_scene = {
totalSlots = 4,
lockedSlots = { 4 },
time = { hour = 20, minute = 0 },
hub = {
camCoords = vector3(0.0, 0.0, 0.0), -- replace with your coordinates
camRot = vector3(0.0, 0.0, 0.0),
},
characters = {
{
id = 1,
alwaysSpawn = true,
coords = vector4(0.0, 0.0, 0.0, 0.0), -- ped position and heading
camCoords = vector3(0.0, 0.0, 0.0),
camRot = vector3(0.0, 0.0, 0.0),
model = 'mp_m_freemode_01',
animDict = 'anim@amb@nightclub@lazlow@hi_dancefloor@',
animName = 'dancecrowd_li_09_v1_male^6',
approach = {},
},
-- entries 2, 3 and 4 in the same shape
},
}
Config.defaultScene = 'my_scene'

Add approach waypoints when something blocks the direct path between the hub and the slot. Each waypoint is a camera position and rotation:

approach = {
{ camCoords = vector3(0.0, 0.0, 0.0), camRot = vector3(0.0, 0.0, 0.0) },
}

Only one scene is shown at a time, the one named in Config.defaultScene.

The ped is placed on the ground at coords before its animation starts. For sitting or lying animations, nudge the z value up or down if the ped floats or sinks into the furniture. /freecam gives camera positions only; read the ped’s standing spot with any coordinates tool you already use.

Use /freecam to read camera values for your scenes, or for the hub and locations of Kivo Spawn.

  1. Set Config.debug = true in kivo-multi-char/config.lua and restart the resource.
  2. Join the server and run /freecam in the chat.
  3. Move: W, A, S, D, Space and Ctrl for up and down, the mouse to look, Shift to go fast. If the selector is open (for example with /startchar), the free camera starts from the current scene camera.
  4. Press ENTER to print the camera position and rotation in the client console (F8). Press BACKSPACE to exit.

The printed lines look like this and can be pasted into a scene:

camCoords = vector3(-1891.5763, -1241.5302, 24.8024),
camRot = vector3(-16.8177, 0.0000, -59.5295),

For the Kivo Spawn hub, copy the same numbers into coords and rot.

Set Config.debug back to false when you are done. The command is only available while debug is on.

From the server console:

addslot <license> 1

<license> is the player’s license: or license2: identifier, including the prefix. Both work; on QBX prefer license2:. The change applies the next time the player connects. To take a slot back:

removeslot <license> 1

A player never has fewer than one slot.

Config.allow.self.delete = false

When deletion is on and a player deletes a character, the slot’s ped goes back to the scene’s default ped and the camera moves to the first remaining character. If none are left, character creation opens.

Preview your scenes without a framework or a database:

Config.demo = true
-- config_demo.lua
Config.demoData = {
scene_2 = {
[1] = { pfp = 'profil.png', name = 'AKIRA AUTUMN', gender = 'Female', cash = 1200, bank = 3500, age = 27, location = 'Los Santos', job = 'Unemployed' },
[2] = { pfp = 'profil.png', name = 'SECOND CHAR' },
},
}

Creating and deleting are switched off in demo mode. Set Config.demo = false before you open the server to players.

For a QBX demo server with three fixed characters, use Config.demoServer = true instead, and set Config.demoServerModels and Config.demoServerNames.

Situation What happens
Player has QBX characters under both license and license2 All are listed.
A QBCore row stored under license2 (for example migrated from QBX) Not listed, because QBCore.Player.Login would drop the player for it.
ESX character identifiers Stored as char<slot>:<identifier>, so the slot number is part of the identifier.
The scene has fewer characters entries than the player has slots Slots without an entry have no ped or camera. Add entries.
A slot above Config.maxChars or above the player’s allowance It cannot be created.
Config.framework is nil No characters are listed. Creation fails with “No supported framework detected.”
Config.useIdentityCreator = true but Identity Creator is not running The built-in dialog is used and a warning is printed.
Config.spawnSelector = 'kivo-spawn' but Kivo Spawn is not running Multichar behaves as 'default'.
The resource is restarted while players are in game Players who already have a character loaded are not sent back to the selector.
The player double clicks Play Only the first click is sent.
New character on ESX Placed at Config.esxNewCharSpawn, or at Config.defaultSpawn when it is nil.
Character just created Already logged in. The player is not asked to press Play.
  1. A red CONFLICT line in the server console.

    • Run kivosetup in the server console and restart the server once. Remove the old multicharacter’s ensure line.
  2. Characters list is empty on connect.

    • Check the console line framework = …. If it says nil, start your framework before kivo-multi-char.
    • Check that Config.demo is false.
  3. 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.
  4. Spawn fires but the player never enters the world.

    • With 'kivo-spawn', check that Kivo Spawn is running. With 'custom', check that SpawnBridge.custom fades the screen back in.
  5. ESX: duplicate identity or character conflict.

    • Remove esx_identity and esx_multicharacter from server.cfg.
  6. The selector area looks unloaded.

    • Raise Config.streaming.sceneTimeout and Config.streaming.collisionTimeout.
  7. Players see “Character not found.” or “Failed to load character.”

    • The framework did not accept the login. Read the server console with Config.debug = true.
  8. The wrong scene appears.

    • Config.defaultScene must match a key in Config.scenes exactly.
  9. Preview peds show the wrong clothes or a default ped.

    • The character has no saved skin yet, or it is stored outside playerskins (QBX, QBCore) or users.skin (ESX). See Adapting the framework layer.
  • Old multicharacter removed from server.cfg
  • Console shows setup OK
  • Config.demo = false
  • The scene has an entry for every slot a player can use
  • Tested with a new and a returning character
  • Config.debug set to false for production