Multicharacter
Troubleshooting
Black screen, appearance, weather sync, missing characters and more.
Start every investigation with gmc selftest in the server console: it lists what to fix.
#Black screen on join
Check F8 and the server console, then run gmc selftest. Common causes:
oxmysqlnot started, or the resource starts before the framework.- ESX does not see
esx_multicharacter(see Installation: the resource stays passive). qb-multicharacter,qb-spawnoresx_multicharacterstill running.- Another loadscreen is running (FiveM uses only one).
A watchdog (Config.Scenes.revealTimeoutMs, 15 s) clears the black screen anyway; if the scene fails to load, a plain backdrop is shown.
#A character does not show up
Run gmc info <target> and gmc backup list <target>. To bring characters over from another script use gmc import esx|qb|qbox from the console (without --apply it is a dry run).
#The selection scene looks wrong (missing ped, out of frame)
Set Config.Scenes.debug = true and run /gmc camdebug in game. F8 shows scene, camera (position, fov, distance, check) and, for every ped, coordinates, IsEntityOnScreen, ground and pose. With debug the discarded spots are printed too. Send those lines to support.
#The appearance creator fails
The player is never left stuck: if saving the appearance fails it is retried 3 times, then the player goes back to the selection with an error message, and the creator restarts on re-entry. Check the adapter with the selftest.
#Weather and time during selection
While a scene is open the resource pauses weather sync and sets time and weather itself; sync resumes when it closes. Works with qb-weathersync, cd_easytime and Renewed-Weathersync (rows in Config.Scenes.weatherPause; for other scripts add a row with a pause and a resume event).
Limits: the original vSync has no clean pause, so the scene weather is not guaranteed (stop it or switch to Renewed-Weathersync). cd_easytime forces EXTRASUNNY while paused.
#The pause menu does not open / ESC does nothing
Pause menu situations are controlled by Config.Pause.block. With blockedAction = 'ignore' ESC does nothing while blocked; with 'native' the GTA menu opens. If detection fails, force Config.Pause.interceptMode to 'controls', 'frontend' or 'native'.
#Players cannot go back to the selection
Only /relog (or the pause menu button) works, and it follows the Config.Pause.changeCharacter rules: dead, cuffed, recent damage, in vehicle and the cooldown all block it. The reason is shown in the pause menu.
#Qbox: "delete door still open" warning
Follow step 3 of the Qbox installation: remove the two deleteCharacter handlers in qbx_core.
#Still stuck?
Send the gmc selftest output and your framework to support.