esx_multicharacter

esx_multicharacter lets one FiveM account own several ESX characters. Players pick, create or delete a character on a selection screen before they spawn, and admins can grant extra slots or lock characters. ESX enables multicharacter mode automatically as soon as this resource is present on the server.

OverviewCopy Anchor Link

es_extended sets Config.Multichar = GetResourceState("esx_multicharacter") ~= "missing". You do not toggle multicharacter in the es_extended config; you add or remove this resource.

How characters are storedCopy Anchor Link

Every character is a normal row in users. Its identifier is <Config.Prefix><slot>:<license>, for example char1:1a2b3c.... The player keeps one license; the prefix selects the character.

On start the resource migrates the database itself:

• adds users.disabled (TINYINT(1), default 0) used by /disablechar
• creates the multicharacter_slots table (identifier, slots)
• scans every table with an identifier or owner VARCHAR column, widens it to fit the prefix and adds an index

The scanned tables are also the ones cleaned when a character is deleted, so you do not need to register your own tables for deletion as long as they use an identifier or owner column.

ConfigurationCopy Anchor Link

config.lua is shared, but some keys only exist on one side.

CommandsCopy Anchor Link

The admin commands are allowed from the server console. The database change is applied, but the confirmation notification then throws a script error because there is no xPlayer, so prefer running them in game. identifier is the raw license (without char1:), for example:

/setslots 1a2b3c4d5e6f7a8b9c0d 5
/disablechar 1a2b3c4d5e6f7a8b9c0d 2

The slot count is clamped between 1 and 100.

Events and callbacksCopy Anchor Link

ServerCopy Anchor Link

The resource listens to esx_identity:completedRegistration to create the new character and then fires esx:onPlayerJoined with the charN prefix. For relog it triggers esx:playerLogout, which saves and unloads the xPlayer.

Possible error values: delete_disabled, invalid_character, busy, rate_limited, stale_session, database_error, refresh_failed, already_loaded, disabled, not_loaded.

ClientCopy Anchor Link

Reacting to a character switchCopy Anchor Link

Use the ESX events instead of multicharacter internals. They fire for both first spawn and relog:

RegisterNetEvent('esx:playerLoaded', function(xPlayer, isNew, skin)
    ESX.PlayerData = xPlayer
    -- build blips, jobs, UI for the selected character
end)

RegisterNetEvent('esx:onPlayerLogout', function()
    -- clean up anything tied to the previous character
end)

Common issuesCopy Anchor Link

• "ESX Requires Onesync Infinity to work". Add set onesync on to server.cfg.
• "Cannot Find the servers mysql_connection_string". The resource parses the database name from mysql_connection_string. Use the mysql://user:pass@host/database or database=...; form.
• "identifier-active" when joining. Another connected player (or a stale session) uses the same license. The resource cleans stale entries automatically if the old player no longer has a ping. With EnableDebug on in es_extended, the duplicate check is skipped for testing.
• Black screen after selecting a character. Usually a failed schema migration or a resource that errors in esx:playerLoaded. Check the server console.
• Players see the default slot count after /setslots. Make sure you passed the license without the char1: prefix.

RelatedCopy Anchor Link

• esx_identity
• esx_skin
• es_extended configuration
• Client events
• Database schema

Frequently asked questions