Installation — ns-loading

Install

1. Copy the ns-loading folder into your server's resources folder (any sub-folder such as resources/[ui]/ works).

2. Add this line to server.cfg:

   ensure ns-loading
   

   Copy

3. Only one loading screen can be active. Remove or stop any other resource that declares loadscreen in its manifest.

4. Edit html/config.js (see Configuration) and restart the server.

Optional: to hide FiveM's small busy spinner in the bottom-right corner, add this to server.cfg:

setr sv_showBusySpinnerOnLoadingScreen false

Loading screens are downloaded by players when they connect. After changing files, restart the resource or server. Players may need to reconnect to see changes.

Player name & count (handover)

The screen can greet the player by name ("Welcome, Alex") and show how many players are on the server (a hero stat with live: 'players'). This needs a small server script, which is included and enabled by default:

1. fxmanifest.lua contains:

   server_script 'server/handover.lua'
   

   Copy

   Comment the line out if you don't want the name and player count.

2. Make sure handover.showPlayerName is true in config.js.

The script passes only the player's name and the player count (players, maxPlayers from sv_maxclients) through FiveM's official deferrals.handover, and the page reads them from window.nuiHandoverData. The name is always shown as plain text (never HTML) and is cut to 32 characters. Without the script, the configured hero.eyebrow is shown.

Don't add private data (tokens, identifiers, IPs) to the handover: anything handed over can be read by the player's client.

Team from Discord

server/discord-team.lua (enabled in fxmanifest.lua by default) fills the Team tab straight from your Discord server, using your own bot: everyone with one of your staff roles is listed with their Discord name, profile picture, role name and role colour. Promote someone on Discord and they appear on the loading screen at the next refresh.

1. Developer Portal → your bot → Bot → Privileged Gateway Intents → turn on Server Members Intent. The bot must be in your server.

2. server.cfg, with set (not setr) so the token never leaves the server:

   set ns_loading_discord_token "YOUR_BOT_TOKEN"
   

   Copy

3. In server/discord-team.lua, set guildId and list your staff roles in display order. Get IDs with Discord → Settings → Advanced → Developer Mode, then right-click → Copy ID:

   roles = {
       { id = '123456789012345678', label = { en = 'Founder', tr = 'Kurucu' } },
       { id = '234567890123456789' },   -- no label = the role's name on Discord
       { name = 'Moderator' },          -- or match by exact role name
   },
   

   Copy

4. Keep both server_script 'server/handover.lua' and server_script 'server/discord-team.lua' enabled in fxmanifest.lua, then restart the resource. The server console prints how many staff members were loaded, or what is wrong (bad token, missing intent, unknown role…).

• A member with several staff roles is listed once, under the first matching role. Bots are skipped. Server-specific avatars are preferred (serverAvatars). Without an avatar, the initials are shown.
• The list is refreshed every refreshMinutes (default 10). If Discord can't be reached, the last list is kept.
• The bot token is used only by the server script. Players receive only the public name, avatar link and role.
• When the Discord list is available it replaces the team from remote.url and config.js, which stay as the fallback.
• Without ns_loading_discord_token the script only prints Discord team: disabled once and does nothing else. To remove it completely, comment out server_script 'server/discord-team.lua'.

Manual shutdown

The screen fades out (UI and music) when the game is ready instead of disappearing instantly. This is enabled by default with these two lines in fxmanifest.lua:

loadscreen_manual_shutdown 'yes'
client_script 'client/shutdown.lua'

The helper waits until the game's own loading screen is dismissed (by your spawn manager or framework), sends a fade message, then calls ShutdownLoadingScreenNui(). A safety timeout (120 s) guarantees nobody gets stuck. The timings are at the top of client/shutdown.lua.

Turn it off (comment out both lines) if your framework or multicharacter resource already calls ShutdownLoadingScreenNui() itself (many do), or if players get stuck on the loading screen. FiveM then closes the screen automatically, which is the most reliable behaviour.

Testing in FiveM

1. Install as above and ensure ns-loading.
2. Connect to your server. Check that:
   • the screen appears with your branding, and the percentage starts at -- (standby) then follows real progress;
   • the status line changes through the phases;
   • music (if enabled) plays or shows "Press play for music", and the controls work with the mouse;
   • links open in your browser;
   • the screen closes normally when the game finishes loading.
3. To debug, open FiveM's NUI devtools (type nui_devtools in the F8 console; the loading-screen frame is listed there while it is open). Look for [ns-loading] warnings. Faster still: reproduce the issue in the browser preview, which runs the same code.
4. Test on a second, lower-end PC or with motion.performance: 'low' if your community has weaker machines.

Troubleshooting