Installation#

Requirements#

1. Add the resource#

   Put koja-multicharacter in your resources folder.

2. Set up your framework#

   Remove ensure esx_multicharacter and ensure esx_identity from server.cfg.

   ESX only loads characters in multicharacter mode when Config.Multichar is true. es_extended sets it to true when the esx_multicharacter folder exists, so either keep that folder in resources without ensuring it, or set it yourself in es_extended/shared/config/main.lua:

   es_extended/shared/config/main.lua

   Config.Multichar = true

   The resource prints a red warning on start when Config.Multichar is false.

   Remove ensure qb-multicharacter and ensure qb-spawn from server.cfg.

   Disable the built-in character menu in qbx_core/config/client.lua:

   qbx_core/config/client.lua

   characters = {
       useExternalCharacters = true,
   }

   Stop qbx_spawn if you use it.

3. Start it after its dependencies#

   server.cfg

   ensure oxmysql
   ensure es_extended        # or qb-core / qbx_core
   ensure koja-lib
   ensure illenium-appearance
   ensure koja-spawnselector # optional
   ensure koja-multicharacter

4. Start the server#

   The tables are created on the first start. sql/koja_multicharacter.sql is only there for reference. On ESX the resource also widens the identifier and owner columns so the character prefix (char1:) fits. Turn this off with Config.Esx.AutoResizeColumns = false.

Discord logs (optional)#

set kmc_webhook_created "https://discord.com/api/webhooks/..."
set kmc_webhook_deleted "https://discord.com/api/webhooks/..."
set kmc_webhook_selected "https://discord.com/api/webhooks/..."
set kmc_webhook_admin "https://discord.com/api/webhooks/..."

Character selection is only logged when ServerConfig.LogSelected = true in server/config.lua.

Slot tiers and admin access (optional)#

add_ace group.vip koja.multicharacter.slots.vip allow
add_ace group.admin koja.multicharacter.slots.staff allow
add_ace group.admin koja.multicharacter.admin allow

The tier ACEs and slot counts are set in Config.Slots.Tiers. Framework groups listed in Config.Admin.Groups can use the admin commands without the ACE.

Building the UI (only if you change it)#

cd web
pnpm install
pnpm build   # outputs web/build
pnpm dev     # browser preview with mock data on http://localhost:5201