XS-LoadingScreen

Requirements

Nothing. No framework, no database, no ox_lib. It runs the same on Qbox, QBCore, ESX or a bare server.

A character selector is optional. If you run one, it closes the loading screen the moment it opens — Qbox, qb-multicharacter, XS-MultiCharacter and most others already do.

Installation

1. Drop the folder into your resources.
2. Add ensure XS-LoadingScreen to your server.cfg.
3. Stop or remove your old loading screen. A server runs one, and if another is still started, that is the one players see.
4. Open html/config.js, put your name, links and rules in, and restart.

To hide FiveM's own spinner in the corner, add setr sv_showBusySpinnerOnLoadingScreen false to your server.cfg.

Setting it up

Everything players see comes from html/config.js, and every line in it has a comment. Your own files go in html/media/:

• html/media/ — your logo. Square images look best. Leave logo empty and a badge with your initials is drawn instead.
• html/media/backgrounds/ — photos for the slideshow
• html/media/videos/ — a background video
• html/media/music/ — songs and their covers
• html/media/staff/ — staff photos
• html/media/gallery/ — gallery images

Colours are two values in theme: accent for buttons, highlights and the loading bar, and accent2 for the second colour in the gradients. dim darkens the background so the cards stay readable over a bright video.

Video or photos

Set background.type to 'photos' or 'video'.

Photos crossfade with a slow zoom. List them in photos, and photoSeconds sets how long each one stays up. Screenshots from your own city work best.

Video has to be an .mp4 with H.264 video. .webm and H.265 (HEVC) files do not play in FiveM. Every player downloads the file when they connect, so keep it small.

Save it with fast start on and it starts playing straight away. In HandBrake that is the Web Optimized box. With ffmpeg, this fixes a file you already have without re-encoding it:

ffmpeg -i trailer.mp4 -c copy -movflags +faststart trailer-fast.mp4

The photos show while the video loads, and stay up if it cannot play. If your video has black bars, raise videoZoom to about 1.2 to crop them off.

Music

Drop .mp3 or .ogg files in html/media/music and list them in music.tracks. A cover is optional:

{ title: 'Night Drive', artist: 'Your Artist', file: 'media/music/night-drive.mp3', cover: 'media/music/night-drive.jpg' }

It starts on its own at volume, and whatever volume a player picks is remembered for their next join. With no tracks listed, the player hides itself. Keep videoSound off if you use music, or the two play over each other.

Keybinds

The keyboard lights up every key listed in keyboard.binds. Hovering or clicking one names what it does:

binds: { F1: 'Phone', M: 'Radial menu', TAB: 'Scoreboard' }

Keys are named F1 to F12, 0 to 9, A to Z, TAB, CAPS, SHIFT, CTRL, ALT, SPACE, ENTER, BACKSPACE, ESC, the arrows as UP, DOWN, LEFT and RIGHT, and the symbol keys as themselves. Set showOnStart to false to start with the keyboard hidden. Players can still open it from the Keybinds button.

Tabs

The panel on the right is the list in tabs. Add, remove or reorder them as you like. Each one has a type:

• rules — numbered rules, each a title and a line of text
• staff — a name, a role, a colour for their badge and an optional photo
• gallery — images with captions. Clicking one opens it full screen
• updates — dated notes in a timeline
• features — what your server has, each with an icon
• text — plain paragraphs, for anything else

**bold** works in any text. The tips under the loading bar are in tips and change every tipSeconds.

When it closes

Set in config.lua:

• Config.CloseOn = 'multicharacter' (the default) — your character selector closes it when it opens. If nothing has closed it Config.MaxWait seconds after the player joins, it closes itself, so nobody is left stuck on it.
• Config.CloseOn = 'spawn' — it closes once the player is in the world. Use this with no character selector.

Config.FadeOut is how long the fade out takes, in milliseconds. Other resources can close it too:

TriggerEvent('XS-LoadingScreen:close')
exports['XS-LoadingScreen']:Close()

Troubleshooting

The video does not play, only the photos

The file is a .webm or an H.265 mp4, and FiveM plays neither. Use an .mp4 with H.264 video, and check the path in video matches the file in html/media/videos.

My old loading screen still shows

Another resource with a loading screen is still started. A server runs one, so stop or remove the old one.

It stays up after the character selector opens

Your selector does not close loading screens. Set Config.CloseOn = 'spawn', or call exports['XS-LoadingScreen']:Close() from the selector. It closes itself after Config.MaxWait either way.

No music plays

No tracks are listed in music.tracks, or a path is wrong. The files go in html/media/music, and each path in the config starts with media/music/.

A button says the link is not set up

The link does not start with https://. Only web links are opened, and the placeholder links in the config go nowhere until you replace them.

There is a spinner in the corner

That one is FiveM's own. Add setr sv_showBusySpinnerOnLoadingScreen false to your server.cfg.

Updating

1. Keep a copy of html/config.js, config.lua and your files in html/media/.
2. Replace the resource folder.
3. Put your config and media back, and restart.

There is no database, so there is nothing else to move over.

Support

Bugs and questions go to the Discord. Include your server's console output — the resource prints the reason when it refuses to do something, and that line is usually the whole answer.

XS-LoadingScreen on GitHub