Installation

The folder name is locked

The resource folder must be named exactly:

nuggs_multicharacter

Lower case, no suffix. A bracketed parent directory is fine — [qbx]/nuggs_multicharacter is still named nuggs_multicharacter, because only the last path segment counts. What catches almost everybody out is the suffix an unzip adds by itself: -main, -master, (1), a version number. Check for one before you start the server.

Why it is fixed. Exports are keyed on the folder name and FiveM gives no way to alias them, so every exports.nuggs_multicharacter:... call — the whole of INTEGRATION.md, plus anything you or a third party writes against this resource — stops resolving the moment the folder is called something else. The documented integration events move with it. The escrow entitlement is issued against this asset name too.

What happens if it is wrong. The check lives in an encrypted file and cannot be edited, so this is not advice:

a boxed error in the server console at boot and once a minute after it, naming the folder that was found and the folder it has to be
the same banner in every client’s F8 console, plus a chat line
mcdiag leads with it
every player is refused at the connection screen, with the fix in the message
every server event and the character screen itself refuse to run

The fix. Stop the server, rename the folder to nuggs_multicharacter, make sure server.cfg says ensure nuggs_multicharacter, start it again. Nothing else changes — your config.lua, locales and database are untouched.

Requirements


Server artifact	10188 or newer
OneSync	Infinity (`onesync infinity` in `server.cfg`)
Database	`oxmysql`
Framework	one of `es_extended`, `qb-core`, `qbx_core`
Appearance	`skinchanger` on ESX only — not used on QBCore or Qbox

That is the whole list. There is no dependency on ox_lib, on a target resource, or on a compatibility layer of any kind.

nugg_bridge is not required and is not used. This resource carries its own framework layer, because character loading, identity, appearance and money accounts differ between ESX, QBCore and Qbox in ways a shared flat API cannot express — so it detects your framework at startup and talks to it directly. Nothing in the resource calls exports.nugg_bridge.

If nugg_bridge is already running for other scripts on your server, leave it. It neither helps nor hinders this one. Installing it will not fix anything here, and removing it will not break anything here.

Clothing, tattoo and housing resources are different: those are detected at startup and integrated with if present, and the startup banner names which ones it found. None of them is required either — see the sections below.

Install

Drop the folder into your resources. The folder must be named exactly nuggs_multicharacter — see The folder name is locked below. Rename it and the resource refuses to start and nobody can connect.
You do not need to run install.sql. Every table this resource owns is created for you the first time it starts, and the rest of the schema is discovered rather than assumed, so there is no import step and nothing to paste into your database tool. install.sql ships purely as a reference: it documents the statements the resource runs on its own, for anyone who would rather run them by hand or have their DBA review them first. If you do choose to run it, only the section for your framework applies.
ensure nuggs_multicharacter in server.cfg, after your framework.
Turn off the character screen you are replacing (below).
On QBCore and Qbox, turn off the other character creator (below). These are two separate jobs, and skipping the second is the cause of nearly every “clothing and tattoos are not saving” report.
Restart and read the console. The startup banner names the framework, clothing, housing and tattoo resources it detected, and lists every problem it found in your config.lua.

ensure [folder] starts every resource inside that folder. Stopping an old character screen means moving it somewhere nothing ensures — renaming it is not enough.

Turn off the screen you are replacing

Framework	Do this
ESX	Stop `esx_multicharacter`, then keep ESX in multicharacter mode — see below
QBCore	Stop `qb-multicharacter`, and `qb-spawn` unless you want its arrival picker too
Qbox	In `qbx_core/config/client.lua`, set `characters.useExternalCharacters = true`

ESX — in es_extended/shared/config/main.lua:

Config.Multichar = GetResourceState("esx_multicharacter") ~= "missing" or GetResourceState("nuggs_multicharacter") ~= "missing"

Without it ESX drops to single-character mode and esx_identity opens its own form over this screen. Use this resource’s folder name if you renamed it.

QBCore and Qbox: turn off the other creator

Read this even if the screen looks like it is working. These four reports are all the same bug:

clothes are not saving
tattoos disappear after spawn
the creator opens twice
the character looks right in the line-up and wrong in the world

The cause. Something on your server fires qb-clothes:client:CreateFirstCharacter at illenium-appearance after this resource has already created the character. illenium then strips the ped and overwrites the playerskins row that was just written. illenium has no config option to stop this — the trigger has to be stopped at its source.

Stop the triggers

Framework	Fix
Qbox	In `qbx_core/config/client.lua`: `useExternalCharacters = true` and `startingApartment = false`. Both are in the `characters` block
QBCore	Park `qb-multicharacter`, `qb-apartments` and `qb-spawn` in a folder nothing ensures
ESX	Stop `esx_identity` running its first-spawn step, or apply the guard below

startingApartment is the one people miss. It lives in qbx_core’s config but is read by qbx_properties, which answers every login with its apartment picker and then fires the creator event. It ships as true, and ensure [qbx] starts qbx_properties whether you meant it to or not.

qbx_core/config/client.lua is read at start, so this needs a full server restart, not restart qbx_core.

Verify

From your server root:

grep -rn "CreateFirstCharacter" resources/

On a correctly configured Qbox server the only hits are qbx_core, qbx_properties (both now dead code) and illenium’s own handler. Anything else — an old qb-apartments, a paid housing or spawn script, a custom apartment selector — fires it too and has to be dealt with the same way.

Recommended: guard illenium’s handler

The config switches are enough on a clean server. This one-line guard is what keeps it fixed when you add a housing script six months from now.

In illenium-appearance/client/framework/qb/main.lua, find the qb-clothes:client:CreateFirstCharacter handler and add the first line:

RegisterNetEvent("qb-clothes:client:CreateFirstCharacter", function()
    if GetResourceState("nuggs_multicharacter") == "started" then return end

    QBCore.Functions.GetPlayerData(function(pd)
        PlayerData = pd
        setClientParams()
        InitializeCharacter(Framework.GetGender(true))
    end)
end)

On ESX, the same guard goes on the esx_skin:playerRegistered handler in illenium-appearance/client/framework/esx/compatibility.lua. fivem-appearance carries the same handlers in the same places.

This turns off illenium’s creator only. Clothing shops, barbers, tattoo shops, saved outfits, job uniforms and appearance loading on login are all untouched.

Notes:

Use your folder name in GetResourceState if you renamed this resource.
Safe when this resource is stopped — the guard falls through and illenium behaves exactly as shipped.
Re-apply it after updating illenium-appearance, which overwrites that file.

Check it worked

Make a new character with clothes and at least one tattoo, then:

The creator opens exactly once. illenium’s menu appearing after the fade-in means a trigger is still live.
The startup banner reads appearance illenium-appearance.
One playerskins row, active = 1, containing "headBlend", "components" and "tattoos":
```
SELECT citizenid, model, active, LEFT(skin, 200) AS skin
FROM playerskins WHERE citizenid = 'YOURCITIZENID';
```
A "face" key with an item field instead means a qb-clothing row — set Config.Appearance.publish = "illenium" explicitly.
Relog. The character comes back wearing what you made, tattoos included.
Visit a clothes shop, change something, check the row again. "tattoos" must still hold your designs, not [].

Repair a character that already lost its ink

/mctattoos 1              the character that player is currently on
/mctattoos ABC12345       by character key, online or not
/mctattoos                the character you are playing

4 here, 0 in playerskins - OUT OF STEP is the wipe. It is repaired on the spot, and again on that character’s next login.

Existing characters

Nothing is migrated and nothing is lost. Characters made by esx_multicharacter, qb-multicharacter or Qbox’s own screen all keep working.

What this resource takes over on QBCore and Qbox

QBCore:Client:OnPlayerLoaded — raised by this resource once the player has spawned, right before the fade-in.
Starter items — read back out of the framework (qbx_core/config/shared.lua or QBCore.Shared.StarterItems), so editing yours there is enough. Config.StarterItems overrides it, and has a block for ESX doing the same.
Character deletion — the framework’s own delete runs first, then this resource sweeps anything else keyed on a citizenid.

Not taken over: starting apartments. The arrival picker replaces that step.