Multicharacter
Step-by-step installation guide, common issues & solutions, code snippets, error codes, config previews, locales previews, SQL previews, and changelogs; all in 1 easily accessible place.
This resource can be purchased as part of a bundle for a discount here.
Translate
INSTALLATION GUIDE
Step 0 - First Steps
1. Download your resource from FiveM’s Keymaster.
2. Unzip the cd_multicharacter.zip
folder and place this folder in your server's resource folder.
3. Add the resource to your server start config (server.cfg): ensure cd_multicharacter
. If you are using a framework, it must be placed anywhere below your framework resource e.g., es_extended, not above.
Step 1 - Fxmanifest
Depending on your framework and dependencies, you may need to make some changes inside the [cd_multicharacter/fxmanifest.lua]
. We have made this easier by commenting on the lines you possibly need to change.
Step 2 - Configure Resource
You MUST read all configurable options inside the [cd_multicharacter/configs/config.lua]
file and configure them to suit your server's needs. Please read the ”commented out help text” at the end of each line so you can understand what each config option does.
The most important sections are the options under the Framework and Important sections at the top of the config.lua
. Everything else is optional.
Step 3 - SQL Database
You MUST import the SQL file to your database. This SQL file is located inside theREAD_ME_AFTER_PURCHASING
folder; the file is named SQL_main.sql
. Watch this video if you are unsure how to do this HeidiSQL / PHPMyAdmin.
Step 4 - Install Dependencies
Where can I find these dependencies?
Open the [cd_multicharacter/dependencies]
folder. The folders inside are the required dependencies. You will find a text file inside each folder that includes a GitHub download link. Alternatively, they are listed in the table below.
Where should I put these dependencies?
These resources should be placed in your resources folder like any other, but remember, you shouldn't put them in the cd_multicharacter folder.
Do I need to add them to the server start config?
No, it will start automatically because it is listed as a dependency for this resource.
Step 5 - ESX Client Edit
We need to do a small modification to stop your framework from registering our character instantly when you load into the server.
essentialmode/client/main.lua/line 5
- comment out this code.
Step 6 - Player Skin Edit
We will be setting the skin of your chosen character directly from the cd_multicharacter or cd_identity, so we don't need your skin creator script to do this.
Part 1: Find the block of code that looks similar to the examples below in the client-side main.lua
and comment out the code.
There are many different versions and not all will look the exact same.
View the examples below:
Step 7 - Multi-Peds Skin Edit
Now we need to copy and paste some code into your character skin creation script to set the skin of the peds. Currently, we support 3 different clothing scripts. However, we have 2 different methods for esx_skin as the first supports older versions and the second supports newer versions, but always try the older version first.
If you use esx_skin, use this version first.
Part 1 - Copy and paste this export below into your skinchanger
script, anywhere in the client-side main.lua.
Part 2 - Copy and paste this block of code below into your skinchanger
script, at the very bottom of the client-side main.lua.
OPTIONAL FEATURES
This section is to help you understand how the built-in features of this resource work, and if applicable, how you can make them compatible with other resources. These features are not required, they are optional and can be configured in the [configs/config.lua]
.
Advanced multi-character method
WARNING If you are not 100% sure what you are doing here we would not recommend doing this, but if you insist please read the information before implementing these changes. If you are unsure what this does, read more about it on our Web Store.
This is completely optional. We do not recommend using this option unless you have basic knowledge of Lua and you understand what needs to be done from reading the instructions below. This method is more complicated and more effort to install but is far more optimized than the standard esx_kashacters method.
Part 1: Set the Config.UseAdvancedMultiCharMethod
in the config.lua
to true.
Part 2: If you are switching from the standard multi-character version to the advanced multicharacter version you need to use this command in your server console below before any players join.
Part 3: Replace the FiveM native method of getting a players identifier (steam id, license) GetPlayerIdentifiers(source)[1]
or GetPlayerIdentifiers(source)[2]
with xPlayer.identifier
for every server-side resource which uses the identifier to fetch a character's data from the database. xPlayer of course needs to be defined before using it eg., local xPlayer = ESX.GetPlayerFromId(source)
.
Example 1: Do not change this.
Part 4: Follow the guide below for your version of ESX.
Switching Characters
Part 1: Copy and paste this block of code below into your character skin creator script, at the very bottom of the client-side main.lua.
Part 2: We need to add 2 events to your es_extended resource to tell the code that we are switching characters.
ESX (all versions) - /server/main.lua
- add this block of code at the bottom of the file.
INFORMATION
Default Key Binds
These keys can be modified and/or disabled in the Keys and Commands section of the [configs/config.lua]
.
Chat Commands
These chat commands can be renamed and/or disabled in the Keys and Commands section of the [configs/config.lua]
.
The exact usage for each command will be displayed in the chat suggestions when using the commands in-game.
COMMON ISSUES
Please check out our Troubleshooting Guide before contacting our support.
🔔 Folder Name Make sure the name of the folder is cd_multicharacter
.
🔔 Encrypted Files Do not edit the encrypted files in any way.
🔔 Always F8 Quit Make sure you and your players fully close FiveM before reconnecting to your server by either F8 quitting or force closing FiveM; this is a known issue with FiveM, not the multicharacter.
🔔 Always Restart Server Never restart the resource while the server is live; always restart the server to ensure no unforeseen issues.
SERVER-SIDE (database)
SQL Unknown Column Error?
eg., if you see an SQL error in the server console similar to this example -
ER_BAD_FIELD_ERROR: Unknown colum 'max_chars' in 'where clause'
.
SQL Table Doesn't Exist Error?
eg., if you see an SQL error in the server console similar to this example -
ER_NO_SUCH_TABLE: Table 'exampletable' dosesn't exist'
.
SQL Duplicate Entry Error? (datastore table)
eg., if you see an SQL error saying you have a duplicate entry in the datastore table similar to this:
[ERROR] [MySQL] An error happens on MySQL for query "INSERT INTO datastore_data (name, owner, data) VALUES ('property', 'steam:111738473874', '{}')": ER_DUP_ENTRY: Duplicate entry 'property-steam:111738473874' for key 'index_datastore_data_name_owner'
.
SERVER-SIDE
Characters not saving after re-logging?
eg., if your characters don't save after you create them or some data is not being saved in the database.
All of my characters are default peds with no character info?
eg., if you see default peds with no character information being display when you are certain you have characters saved in the database.
UI not displaying the correct sex?
eg., if you see "Non-Binary" on the character selection UI, this means the script could not find one of the standard sex types eg.,
m, male, f, female
in the sex column for this character in the users database table. And if you see "Autosexual" that means the sex column for one of your characters is empty.
CLIENT-SIDE
Ped visible on first spawn?
eg., if you see your ped when first loading into the server before the character selection screen activates.
Ped in front of camera?
eg., if you see your player's ped standing in front of the camera during the character selection screen.
No such export GetPedList in resource skinchanger?
eg., if you see an error similar to this in the client F8 console.
Character floating in the sky
eg., if your character is floating in the sky (like this).
Issues with skins not loading?
eg., if your peds skins are not loading.
Characters not showing but blue arrows do show
eg., if your character is not showing but the blue arrows are showing.
ERROR CODES
If you see an error code not listed below please open a script support ticket in the Codesign Discord.
665 - This is because you have copied and pasted the Config.DatabaseTables from an old version or from esx_kashacters. Use the table format from the default config and add to it.
634 - There is an error in the GetSkin()
function in the configs/client_customise_me.lua. Please try to troubleshoot this yourself before contacting support.
778 - The sex column for one of your characters in the users database table is empty. It should contain m, male, f, female
etc., in a string format. This means your identity script is not adding the correct data to the database so you should check why. But a quick fix is to manually add m
into the database column which is currently empty.
897/654 - The GetIdentifier
function in the server_customise_me.lua
is returning a nil value, when it should be returning the player's identifier as a string. This is because the string inside the Config.ESX_version
is invalid. Only one of the following options is acceptable: [ '1.1' / '1.2' / '1.final' / 'exm' / 'legacy' ], or because the Config.Identifiertype has a typo in it.
331/487/905 - The GetUserInfos
function in the server_customise_me.lua
is not returning a table. This is most likely due to an issue in the database. You can try removing the characters for the player(s) having the issue and tell them to relog. But you still need to debug this yourself.
FRESH TEST SERVER
PLEASE READ: The only purpose of the steps below is to help you debug the multicharacter script if you are having issues that are not common andunable to debug the cause of the issues.
We recommend you do this on a test server/local host.
Test Environment Setup
Operating System: Windows 10
MySQL Database Server: 10.4.13-MariaDB
FiveM Server Artifacts: Latest Recommended (5562)
Database Viewer: HeidiSQL Version 11.3.0.6295 (64 Bit)
FiveM MySQL Resource: mysql-async Version 3.3.2
Framework: ESX Legacy
OneSync: Infinity
Guide
Step 1 - Download Server Files
Download our full FiveM Server folder from our GitHub.
Do you use esx_skin
? Download this version.
Do you use cui_character
? Download this version.
Step 2 - Add License Key
Open the server.cfg and add in your licenseKey.
Step 3 - Import Database
Watch this video if you are unsure how to do this.
Step 4 - Add Codesign Scripts
Make sure you download the latest versions of cd_multicharacter
/ cd_spawnselect
/ cd_identity
and add them into the [Codesign]
folder.
Now start the server, create a character, relog and choose your newly created character.
CHANGELOG
Files Changed
Not every update requires you to replace the whole folder. We do this because we understand it's a pain to redo the configs for every update.
All Files - This means you should delete your old
cd_multicharacter
folder, download and add in the latest version, reconfigure the configs folder and restart your server.All Files Except config.lua - This means you should do all of the above (in the All Files section) but additionally make a backup of the
config.lua
file and replace the new config.lua file with the one you made a backup of.Specific Files - This means you can copy and paste the SPECIFIC new files over the old ones and restart the server.
Update Type
On rare occasions, you are forced to update to the latest version. Mostly due to authentication updates where the old versions will no longer work.
Mandatory - This means you MUST update to this new version, or the old versions will no longer work.
Optional - This means it's completely your choice whether you wish to update to the latest version. But we do not offer support for old versions for obvious reasons; they are old.
Skipping Updates
If you are attempting to update to the latest version but have skipped previous updates, you should update all files just to be safe. For example., let's say you are currently on v4.0.1, you did not update when v4.0.2 was released, and now v4.0.3 is released, and you want to update; you should always use the “All Files” update method.
26/12/2020 - 10/08/2021
v3.0.0 - v3.2.0
Files Changed:
Update Type:
Changelog:
Add
Added in the "kashactersS:CharacterChosen" which will send the charid just like esx_kashacters does so scripts that use this will not need modifying.
Added the ability to switch characters in game using a chat command.
Added easier to understand error handling methods.
Added support for the use of ghmattimysql along side mysql.
Added support EXM (essentialmode).
Added support for modified versions of es_extended which use a different identifier type. For example if you use esx 1.2 but you have modified it to use steamid instead of license.
Added the ability to rename all esx events such as the setjob and playerloaded events.
Added the option to only allow players to switch characters at set locations using a command or keypress and optional blips on the map.
Added drag and drop support for the new esx legacy version.
Added support for the use of ped models on the character selection screen.
Added the ability to customize the job name which is displayed on the UI without compromising the optimization.
Added extra checks to make sure that incompatible database tables that people add to the
Config.DatabaseTables
such asuser_lastcharacter
etc do not get ran as that would cause a script breaking problem.
Edit
Made modifications for this to work out of the box with "cd_identity".
Changed "Database cleaner" to be a command instead of being used every restart as its only really needed to be used once every week to a month.
Modified the "Config.DatabaseTables" to be easier to understand for new people.
Updated the codesign error handlers.
Updated the SetAllMaxChars console command to also update the max_chars column default value in the user_lastcharacter database table with the new value.
Added some extra fail-safe checks to ensure stability - If a player's maximum character limit in the user_lastcharacter database table is larger than the maximum amount of ped coordinates that the script is currently configured for, the script will fix itself and show the default 5 characters as a temporary fix until the server devs can resolve the issue.
Added checks so the spawnmanager exports are only triggered for certain versions of esx.
Fixed compatibility with linden_inventory.
When you change the
Config.DefaultCharAmount
it will automatically modify the default maximum character value in the database.All of your
Config.DatabaseTables
identifier column lengths are automatically checked and set to the minimum value of 50 if needed.All of the code required to add compatibility with other clothing/skin resources is now available to edit.
Your chosen characters skin data is now sent to the
CharacterHasLoaded_EXISTING
function in order to reduce SQL queries.Removed some config options which ask you if you are using other Codesign resources and replaced them the
GetResourceState()
FiveM native to ensure people don't misconfigure the config which would cause script breaking problems.Moved the code to change the location of the peds to the config to be more ”new developer friendly“.
Removed some unneeded config options and rewrote the config to be more "new developer friendly".
Removed some unneeded SQL queries along with greatly optimising others such as the get character data quiey and the get skin queries.
Rewrote huge portions of the server and the client side code to be more optimized.
Fix
Fixed random server error on server start.
Fixed the typo with the "Delete" button on the UI.
Optimised server side.
Fixed a typo with the "kashactersS:CharacterChosen" trigger event sending the wrong data.
Fixed a random crash on linux servers.
Small minor clean-ups.
Fixed a typo causing which caused errors when using only 1 character
Fixed a bug causing the drawtextui for the switch character to not work correctly.
Fixed a typo causing the advanced multi character method to not work correctly.
Test fix for a NUI state related issue.
Fixed the trigger event to initialise esx.
Fixed the bug where sometimes your ped would fall when first spawning.
Added better checks to make sure your ped and other players peds are invisible during the character selection.
Fixed the Config.Emoji not being able to be disabled.
Temporary fix for the canary issue until the new Tebex FiveM license system is ready to launch, when this is released we will be fully switching over to the new system.
Fixed compatibility with cui_character (read the read me and complete the newly edited steps).
Switching characters in game is no longer experimental and now should be fully ready to use.
Fixed the bug where when you switch characters in game and create a new character it would show your previous characters clothes instead of a default ped.
Hide the esx hud during the character selection screen when switching character in game.
Fixed the screen fade not fully disabling when switching character in game
Force save the coords of your previous character when you switch character in game.
Fixed the "xPlayer is nil" errors in external resources such as cd_spawnselect or cd_identity etc when triggering events from the multicharacter after the player chosen their character, as now these events will only be triggered after ESX has fully loaded a players character data.
Re-added and improved the code to shut down the loading screen early to avoid seeing the bridge as long.