FiveM Loading Screen Lua Scripts & fxmanifest Explained

When you install a custom loading screen for your server, you aren't just dealing with HTML and CSS. FiveM requires specific configuration files to recognize your code as a valid "resource". In this guide, we will break down the FiveM loading screen Lua scripts and the fxmanifest.lua file so you understand exactly what they do.

The fxmanifest.lua File (The Blueprint)

Every single FiveM resource must contain an fxmanifest.lua file in its root directory. This file acts as a blueprint, telling the server what files exist and how the client should interact with them.

fx_version 'cerulean'
game 'gta5'

-- This tells FiveM to load index.html as the UI overlay
loadscreen 'index.html'

-- This enables the mouse cursor on the loading screen
loadscreen_cursor 'yes'

-- You MUST list every file you want the player to download
files {
    'index.html',
    'style.css',
    'script.js',
    'assets/background.webm',
    'assets/music.mp3'
}

Key Directives Explained

• fx_version: Defines the manifest schema version (usually 'cerulean' or 'adamant'). Always use modern versions.
• loadscreen 'index.html': This is the critical line. It tells FiveM, "Before the player spawns, open this webpage covering the whole screen."
• files { ... }: A list of every asset your HTML file uses. If your HTML tries to load music.mp3 but it is not listed here, it will fail to play because FiveM never sent it to the client.

Do I Need Other Lua Scripts?

For a basic, standalone loading screen, you do not need a client.lua or server.lua script. The loadscreen directive in the manifest handles all the heavy lifting automatically.

However, if you want your loading screen to interact with the game (for example, waiting for ESX/QbCore to load player data before fading out the screen), you might include a small client script to force the UI to close:

-- client.lua example (Optional)
RegisterNetEvent('QBCore:Client:OnPlayerLoaded')
AddEventHandler('QBCore:Client:OnPlayerLoaded', function()
    ShutdownLoadingScreenNui()
end)

Avoid the Errors

The number one reason custom loading screens fail is a syntax error in the fxmanifest.lua file. Missing a comma in the files array or having a typo in a filename will break the resource entirely.