Installation — lumo-multicharacter

Pick your framework below and follow only that section. Every section ends with the same test checklist.

Back up first. Copy your database and the resource you are replacing somewhere safe. Rolling back is then just moving a folder back.

• QBCore
• Qbox (qbx_core)
• ESX (es_extended)
• Standalone (no framework)
• Moving from the lumo-bridge edition

---

QBCore

1. Copy lumo-multicharacter into resources/ (any category, e.g. [lumo]).
2. Stop qb-multicharacter. If your cfg says ensure [qb], move the folder out of the category (see Disabling a resource). Do not run both: this resource declares provide 'qb-multicharacter'.
3. server.cfg:

   ensure oxmysql
   ensure qb-core
   ensure [qb]               # qb-spawn, qb-apartments, qb-clothing …
   ensure lumo-multicharacter

4. Restart. Console: [lumo-multicharacter] ready — framework: qb.

Nothing in your players table changes. Starter items come from QBCore.Shared.StarterItems as usual.

Qbox (qbx_core)

Qbox has no qbx_multicharacter resource. Character selection is built into qbx_core, so you switch it off with a flag instead of stopping a resource.

1. Copy lumo-multicharacter into resources/.
2. In qbx_core/config/client.lua:

   characters = {
       useExternalCharacters = true,   -- was false

3. server.cfg, after the Qbox category:

   ensure ox_lib
   ensure [qbx]
   ensure lumo-multicharacter

4. Restart. Console: [lumo-multicharacter] ready — framework: qbx.

Notes:

• Spawn: keep qbx_spawn (it accepts the handoff) or use lumo-spawn.
• Starter items: Qbox has no shared starter list, so it is in bridge/config.lua → StarterItems. Use names that exist in ox_inventory.
• qbx_properties runs its own new-character flow (pick apartment → place ped → creator). This script stands aside so you do not get two creators.
• If the console says framework: qb on Qbox, set Framework = 'qbx' in bridge/config.lua.

ESX (es_extended)

This replaces esx_multicharacter. ESX must run in multicharacter mode (Config.Multichar = true) with esx_multicharacter itself not started.

1. Copy lumo-multicharacter into resources/.

2. Turn on multicharacter mode in es_extended. Where depends on your ESX version:

   ESX version	File	Line
   ESX Legacy 1.10+ (current)	es_extended/shared/config/main.lua	Config.Multichar = GetResourceState("esx_multicharacter") ~= "missing"
   Older ESX Legacy	es_extended/config.lua	Config.Multichar = false

   Change that line to:

   Config.Multichar = true

   On current ESX the default only stays true while the esx_multicharacter folder exists, so if you delete that folder without this edit, ESX loads a character on connect and the selector seems to do nothing.

3. Stop esx_multicharacter: remove its ensure, or if your cfg uses ensure [core] / ensure [esx_addons], move the folder into a category nothing ensures (see Disabling a resource). Keeping the folder is fine; it must just not be started.

4. server.cfg:

   ensure oxmysql
   ensure es_extended
   ensure lumo-spawn           # recommended: ESX has no spawn selector
   ensure lumo-multicharacter

5. Restart. Console: [lumo-multicharacter] ready — framework: esx. If you see es_extended has Config.Multichar = false, step 2 did not take.

Notes:

• Characters stay in users with ESX's own char1:<licence> identifiers. ESX creates the row itself (starting money, required columns).
• Different identifier prefix? Set ESX.IdentifierFormat in bridge/config.lua.
• ESX forks with a different login call: ESX.LoginHook in bridge/config.lua.
• Without a spawn script players go to their last location (Config.LastLocationFallback).
• Supported ESX versions: ESX Legacy 1.6 and newer, including the current release. ESX 1.1/1.2 (pre-Legacy) has no multicharacter mode in the core, so it needs ESX.LoginHook in bridge/config.lua.
• Skins: esx_skin + skinchanger, illenium-appearance and fivem-appearance are all read from users.skin, on the previews and after spawning. lumo-clothing uses its own table. A new character gets esx_skin's creator (or illenium's) once the selector closes.
• Starter items: ESX.StarterItems in bridge/config.lua, by default 1 phone, 3 bread and 3 water, all items stock ESX Legacy ships in its items table. Change or empty the list as you like; an item your inventory does not have is skipped with one console line that names it.
• Apartments: ESX has no starter apartments, so a new character starts at Config.DefaultSpawn. Owned esx_property properties show in lumo-spawn's map.

Standalone (no framework)

For servers without QBCore, Qbox or ESX. The script stores characters in its own table and acts as a small core. Details: Standalone.

1. Copy lumo-multicharacter into resources/.
2. server.cfg:

   ensure oxmysql
   ensure ox_lib               # optional: nicer notifications
   ensure lumo-spawn           # optional: spawn selector
   ensure lumo-multicharacter
   
   # admins for /logout (repeat per admin)
   add_principal identifier.license:YOUR_LICENSE group.admin

3. Restart. Console: [lumo-multicharacter] ready — framework: standalone. The lumo_characters table is created on first start.

What you get: selection, creation, deletion, mugshots, a freemode ped matching the character's gender, position saved every minute and on logout/disconnect, and last-location spawn. Money, jobs and inventory are framework features, so they show as 0 / Civilian.

Disabling a resource inside a category

ensure [qb] starts everything in that folder, so deleting a line does nothing. Make a disabled category and move the old resource there:

resources/
  [qb]/
  [disabled]/              <- create this
    qb-multicharacter/     <- move it here

Nothing inside [disabled] starts, and putting it back is a drag-and-drop.

Database

All tables are created automatically. sql/install.sql is included if your database user cannot create tables:

Table	Used on	Purpose
player_mugshots	every framework	Character portraits
lumo_characters	standalone only	Characters

Your framework's own table (players on QBCore/Qbox, users on ESX) is read and written only by the framework itself.

Moving from the lumo-bridge edition

This edition carries its own copy of the framework layer in bridge/, so it no longer needs the separate lumo-bridge resource.

1. Replace the whole lumo-multicharacter folder (do not merge).
2. Move any changes you made in lumo-bridge/config.lua (forced framework, starter items, ESX options) into lumo-multicharacter/bridge/config.lua.
3. lumo-bridge is no longer needed by this script. Keep it only if other Lumo resources (inventory, clothing, HUD) still list it.
4. No database changes.

Test checklist

• [ ] Connect: the selector appears and you are not spawned behind it
• [ ] Existing characters listed with the right name, job and money
• [ ] Create a character: slot taken, starter items given, clothing creator opens
• [ ] Pick a character: spawn selector (or last location) works
• [ ] Reconnect: last location is where you left
• [ ] /logout (admin) returns to the selector
• [ ] Delete a character: it disappears from the list and the database
• [ ] Female characters preview as female