esx_loadingscreen
esx_loadingscreen for ESX Legacy explained. How the loading screen works, how to change the logo, tips and texts, and how shutdown with multicharacter works.
esx_loadingscreen is the loading screen players see while they connect to an
ESX Legacy server. It shows a logo, a progress bar driven by the game's real
load progress and rotating tips. It has no Lua config; you customize it by
editing the files in web/.
Overview
| Resource | esx_loadingscreen |
| Side | Client (loadscreen NUI) |
| Dependencies | None |
| Config | None, edit web/script.js, web/style.css, web/logo.png |
| Required | No, any loading screen resource works |
The manifest declares loadscreen "web/index.html" and
loadscreen_manual_shutdown "yes". Manual shutdown means the game does not
close the loading screen on its own; a script has to call
ShutdownLoadingScreenNui().
How it works
Progress
FiveM sends loadProgress messages with a loadFraction between 0 and 1 to the
page. The bar animates to that value and switches the status text through
"Connecting", "Handshaking", "Downloading resources", "Loading scripts",
"Spawning player" and "Finalizing".
Completion
When loadFraction reaches 1, the page posts the NUI callback
loadingComplete. The client script waits 2500 ms (SHUTDOWN_DELAY) and calls
ShutdownLoadingScreenNui().
Spawn
es_extended (without multicharacter) and esx_multicharacter also call
ShutdownLoadingScreen() and ShutdownLoadingScreenNui() when the player
spawns or the character selection opens, and fire the client event
esx:loadingScreenOff.
Customization
| What | Where |
|---|---|
| Logo | Replace web/logo.png (keep the file name, it is listed in fxmanifest.lua) |
| Tips | tips array in web/script.js (rotates every 6000 ms) |
| Loading texts | loadingTexts array in web/script.js |
| Status labels | statuses array in web/script.js |
| Colors, layout | web/style.css |
| Font | Poppins from Google Fonts, linked in web/index.html |
const tips = [
"Read the rules at discord.gg/yourserver",
"Press F1 to open the help menu",
"Use /report to contact staff",
]The default tips mention features such as F1 menus and /report that ESX does
not ship. Replace them with tips that are true on your server.
If you add new files (a background video, extra images), add them to the
files list in fxmanifest.lua, otherwise the client never downloads them.
Events
| Event | Side | Description |
|---|---|---|
esx:loadingScreenOff | Client (local, fired by es_extended / esx_multicharacter) | The loading screen was shut down. Use it to show your HUD. |
AddEventHandler("esx:loadingScreenOff", function()
-- show your HUD here
end)Common issues
- Two loading screens fight each other. Only start one resource with a
loadscreenentry. - Changes do not show up. Loading screen files are cached by the client.
Restart the server and clear the FiveM cache (
%localappdata%/FiveM/FiveM.app/data/cache) to test. - Black screen after loading. The loading screen closed but the player did not spawn. Check es_extended and esx_multicharacter errors in the F8 console.
Related
Frequently asked questions
Independent documentation
Last updated on
esx_whitelist
Set up esx_whitelist for ESX Legacy. Identifier and Discord role whitelist, admin-only mode, bypass list, in-game panel, commands, config and SQL.
esx_chat_theme
esx_chat_theme for ESX Legacy explained. What the ESX chat theme changes, how it hooks into the cfx chat resource, and how to customize or remove it.