Custom loading screen for FiveM: loadscreen, fxmanifest and shutdown

A loading screen is a small web page that players see while the server's files download. It is a normal resource with a manifest and an HTML file. This guide covers the files, the manifest, closing the screen yourself and keeping it light.

#The resource

Create a folder with the HTML and its assets:

resources/[ui]/my_loadscreen/
  fxmanifest.lua
  index.html
  css/style.css
  js/app.js
  img/background.jpg
  audio/music.ogg

#The fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

loadscreen 'index.html'

files {
    'index.html',
    'css/style.css',
    'js/app.js',
    'img/background.jpg',
    'audio/music.ogg',
}

Two things matter here:

• loadscreen 'index.html' names the page FiveM shows.
• Every file the page uses, including the HTML itself, must be in files. A file that is not listed returns a 404 and the screen is blank or broken in that part. A pattern like 'img/*' is allowed to list a whole folder.

Add it to server.cfg:

ensure my_loadscreen

#A minimal index.html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="css/style.css">
</head>
<body>
  <h1>Welcome to my server</h1>
  <div id="bar"><div id="fill"></div></div>
  <audio id="music" src="audio/music.ogg" autoplay loop></audio>
  <script src="js/app.js"></script>
</body>
</html>

Use relative paths, as above. The page runs in the game's browser, so you can use normal HTML, CSS and JavaScript. For a progress bar, the page receives messages while the game loads:

window.addEventListener('message', (e) => {
  if (e.data.eventName === 'loadProgress') {
    document.getElementById('fill').style.width = (e.data.loadFraction * 100) + '%'
  }
})

#Only one loading screen

FiveM shows a single loading screen. If two resources declare a loadscreen, only one is used, and which one can change between starts. So:

• Remove or stop any other loading screen resource from server.cfg.
• When you want to test a new one, comment the old line out instead of starting both.

#Closing the screen yourself

By default FiveM closes the loading screen when the game session is ready. A multicharacter or spawn script often needs the screen open longer, to hide the world until the character is chosen. For that, the manifest turns the automatic close off:

loadscreen_manual_shutdown 'yes'

Then a client script must close it:

-- client.lua
CreateThread(function()
    -- wait until your own condition: player spawned, character chosen...
    while not NetworkIsPlayerActive(PlayerId()) do
        Wait(100)
    end

    ShutdownLoadingScreenNui()
end)

ShutdownLoadingScreenNui closes the NUI page of your loading screen. A script that handles the spawn, like a multicharacter script, often calls it, or the natives behind it, for you. Check that script first, then add your own call only if nothing else does.

Warning: if you set loadscreen_manual_shutdown 'yes' and nothing calls the shutdown, players stay on the loading screen forever. If that happens, see players stuck on the loading screen.

#Music and video: keep them light

Everything in files is downloaded by each player. A heavy loading screen makes the wait longer, which is the opposite of the goal.

• Music: use .ogg or .mp3, a few minutes at most, and a moderate bitrate. A 3 MB track is fine, a 60 MB track is not. Add a mute button, and set the volume low in the code, since a loud start annoys players.
• Video: short and looped, in .webm or .mp4, small resolution and a low bitrate. Better still, use a good background image, which is much smaller.
• Images: compress them. A background of 200 to 400 KB looks the same as one of 8 MB on most screens.
• Fonts and libraries: put them in the resource. Loading them from the internet at join makes the page slower, and it fails if the host is down.

Since players download these files for every new version, do not change them often. When a player still sees the old page after an update, ask them to clear the FiveM cache.

#Optional: a cursor

If you want the player to click on the loading screen, for rules or a menu, add the following to the manifest:

loadscreen_cursor 'yes'

#Common problems

• Blank screen, no style. A file is missing from files, or a path in the HTML is wrong.
• The default screen shows. The resource is not started, or the loadscreen line is missing.
• It never closes. You set loadscreen_manual_shutdown 'yes' and no script calls ShutdownLoadingScreenNui().
• Music does not play. Check the file path and the format. Test the page in a normal browser first.

#Checklist