Lumo Multicharacter

Character selection and creation with live 3D previews and mugshot portraits.

Version 1.0.3 · Frameworks QBCore · Qbox · ESX · standalone

Installation · Config files · Exports & events · Changelog

Bundle

Sold together with Spawn as the Character & Spawn bundle.

Character selection and creation with live 3D previews, mugshot portraits and a themed React interface.

QBCore · Qbox · ESX · Standalone (detected automatically) · by Lumo · https://lumo-server.tebex.io/

Version 1.0.0 · one folder, no lumo-bridge or any other Lumo resource needed

---

Features

• Character selector: each slot shows name, job, cash, bank and last played
• Live 3D previews: characters stand in the room wearing their saved appearance; drag to rotate
• Character creation: first and last name, date of birth, gender, height, nationality
• Mugshot portraits captured automatically and shown on the cards
• Delete characters, with ownership checked on the server on every framework
• Per-licence slot limits (up to 4 by default)
• Works with any spawn script: lumo-spawn, qb-spawn, qbx_spawn or qb-apartments. With none installed, players spawn at their last location
• Appearance auto-detect: lumo-clothing, illenium-appearance, fivem-appearance, qb-clothing, esx_skin
• Standalone mode: no framework? It stores characters itself and works as a light "core" that other scripts can read through exports
• Drop-in replacement: keeps every qb-multicharacter: event name and declares provide 'qb-multicharacter', so existing scripts keep working
• 0.00 ms idle

Requirements

Resource	Needed?
oxmysql	Required
qb-core / qbx_core / es_extended	Optional, detected automatically (standalone works too)
A spawn script (lumo-spawn, qb-spawn, qbx_spawn)	Optional. Without one, players spawn at their last location
An appearance script	Optional. Needed for the first-time clothing creator
ox_lib	Optional (notifications in standalone). Required on Qbox (commands)
An inventory (ox_inventory, qb-inventory, …)	Optional. Only used for starter items

Installation (short version)

1. Put the lumo-multicharacter folder in your resources folder.

2. Switch off the character selection you are replacing (this is the step people miss):

   Framework	What to do
   QBCore	Remove ensure qb-multicharacter (or move it out of [qb])
   Qbox	useExternalCharacters = true in qbx_core/config/client.lua
   ESX	Config.Multichar = true in es_extended/shared/config/main.lua (older ESX: es_extended/config.lua), and don't start esx_multicharacter
   Standalone	Nothing to switch off

3. In server.cfg, ensure it after oxmysql, your framework and your spawn script:

   ensure oxmysql
   ensure ox_lib             # recommended
   ensure qb-core            # or qbx_core / es_extended / nothing
   ensure lumo-spawn         # or qb-spawn / qbx_spawn / nothing
   ensure lumo-multicharacter

4. Start the server. Tables are created automatically (sql/install.sql is included if you prefer to import by hand). The console shows:

   [lumo-multicharacter] ready — framework: qb

Full step-by-step guide for every framework: Installation.

Commands

Command	Who	What
/logout	Admin	Back to the character selector
/closeNUI	Everyone	Close the selector if it ever gets stuck

Admin = the framework's admin/god group (QBCore, Qbox, ESX) or the ACE group group.admin in standalone.

Configuration

Two files, both left readable in every edition:

shared/config.lua — gameplay and look:

Option	What it does
Config.DefaultNumberOfCharacters	Slots per player (max 4)
Config.PlayersNumberOfCharacters	Per-licence slot overrides
Config.EnableDeleteButton	Let players delete their characters
Config.DefaultSpawn	Where a brand-new character appears (no apartment script)
Config.Interior, PedCoords, PedConfig, CamCoords	The selection room, peds and camera
Config.CharacterCreation	Height, weight and date-of-birth limits
Config.MugshotsEnabled	Portrait capture on/off
Config.SpawnResources, Config.LastLocationFallback	Which spawn scripts get the handoff; last-location spawn when none runs
Config.UI, Config.Notifications	Layout and messages
Config.SyncLumoUI	Share theme settings with Lumo HUD if installed (not required)

bridge/config.lua — framework layer: force a framework, starter items, ESX identifier format, appearance/inventory choice, standalone settings, custom core hooks. Most servers never touch it.

Translations: locales/en.lua (copy it to add a language).

For developers

• Events keep the stock names (qb-multicharacter:client:chooseChar, …). After login it fires qb-spawn:client:setupSpawns + qb-spawn:client:openUI, or apartments:client:setupSpawnUI when qb-apartments runs.
• Client export: exports['lumo-multicharacter']:GetMugShotBase64(ped, transparent) (also reachable as exports['qb-multicharacter']).
• Standalone exports and lumo:* events: Standalone.

Troubleshooting (top 5)

• Selector never appears / you load straight in — the old character selection still runs. See step 2 above.
• Console says framework: standalone on a QBCore/Qbox/ESX server — your core starts after this script. Ensure it first. The console names the core it found.
• Stuck in the room after picking a character — your spawn script has a custom name. Add it to Config.SpawnResources.
• New characters spawn without clothes menu — no appearance script started.
• Starter items missing — the item names in bridge/config.lua must exist in your inventory.

More in Support.

Docs

• Installation, every framework
• Standalone mode, exports and events
• Frameworks and custom cores
• Troubleshooting and support
• Changelog

Build the interface (open-source edition)

The compiled UI ships in html/dist/, so servers need nothing installed. To change it:

cd lumo-multicharacter/nui
npm ci
npm run build

Store, updates and other releases: https://lumo-server.tebex.io/