Skip to content

Examples and troubleshooting

Each example below replaces the matching section of config.js. The rest of the file can stay as it is. See Configuration for every option.

Add images/background.jpg and images/logo.png first.

background: {
type: "image",
image: "images/background.jpg",
overlay: "images/backdrop.png",
video: "images/background.mp4",
videoMuted: true,
color: "#0B0B0B",
blur: 0,
},
logo: {
enabled: true,
type: "image",
title: "My Server",
subtitle: "Roleplay",
image: "images/logo.png",
},

The image and video are not shown. The files in images/ are still part of the resource download, so delete large files you no longer use (see Large files).

theme: {
mainColor: "#4DA3FF",
secondaryColor: "#FFD166",
},
background: {
type: "color",
image: "images/background.png",
overlay: "",
video: "images/background.mp4",
videoMuted: true,
color: "#101826",
blur: 0,
},

Nothing large is stored in the resource. Players load the media from your own web host.

background: {
type: "video",
image: "images/background.png",
overlay: "images/backdrop.png",
video: "https://cdn.example.com/loading/city-loop.mp4",
videoMuted: true,
color: "#0B0B0B",
blur: 0,
},
music: {
enabled: true,
autoplay: true,
volume: 0.3,
loop: true,
shuffle: true,
tracks: [
{
title: "Night Drive",
artist: "Example Artist",
cover: "images/music-cover.png",
url: "https://cdn.example.com/loading/night-drive.mp3",
},
{
title: "Local Song",
artist: "Example Artist",
cover: "images/music-cover.png",
url: "music/local-song.mp3",
},
],
},

The second track shows that local files and links can be mixed in one playlist.

Hide every optional piece. The background, the loading bar and the player count pill stay.

logo: { enabled: false, type: "text", title: "", subtitle: "", image: "" },
music: { enabled: false, autoplay: false, volume: 0.4, loop: true, shuffle: false, tracks: [] },
links: [],
staff: [],
rules: [],
updates: [],
keybinds: { enabled: false, binds: [] },
server: { name: "My Server", location: "", current: 0, total: 64 },

With all panels empty, the button bar at the top disappears too.

A complete example of the panels with your own content.

links: [
{ type: "Discord", link: "https://discord.gg/your-invite" },
{ type: "Web Site", link: "https://your-server.example" },
],
server: {
name: "My Server",
location: "Los Santos",
current: 0,
total: 64,
},
staff: [
{
type: "Founder",
name: "Alex",
image: "images/staff/alex.png",
desc: "Owner of the server.",
links: [{ type: "Discord", link: "https://discord.gg/your-invite" }],
},
{
type: "Management",
name: "Jordan",
image: "images/staff/jordan.png",
desc: "Handles applications and support.",
links: [{ type: "Twitter", link: "https://twitter.com/jordan" }],
},
],
rules: [
{
title: "General Rules",
desc: "Rules for every player.",
content: [
{ title: "Respect everyone", content: "Treat all players and staff with respect." },
{ title: "Stay in character", content: "Keep your character in role in the city." },
],
},
],
updates: [
{
title: "Patch Note #1",
date: new Date("2026-04-01").getTime(),
version: "v1.0.0",
subtitle: "Opening day",
content: "The server is open. Read the rules before you play.",
desc: "Launch",
},
],
keybinds: {
enabled: true,
binds: [
{ key: "F1", label: "Open phone" },
{ key: "F2", label: "Open inventory" },
{ key: "e", label: "Interact" },
],
},
Local file in music/ Direct https:// link
Setup Copy the file, use "music/name.mp3" Use the full link of the audio file
Works if your web host is down Yes No, the song does not play
Adds to the resource download Yes, every player downloads it No
Changing a song Replace the file, restart the resource Change the file on your host, no restart needed if the link stays the same
Seek bar Works Works for normal files. Not for live streams

Tips for hosted audio:

  • The link must go straight to the audio file, usually ending in .mp3. A page that contains a player does not work. This includes YouTube watch pages, streaming site pages and the share pages of file storage services.
  • The link must be public. If it asks the visitor to log in, it will not play.
  • Use https://.
  • Some links stop working after a while, for example attachment links from chat apps. Use a host you control for a long-lived server.
  • For a live radio stream the length is unknown, the timer stays at 0:00 and the seek bar does nothing.

Every file in images/ and music/ is part of the resource. A player’s game downloads these files when they join, and again whenever you change them. Large files make the first connection slower, and the loading screen cannot do anything about it.

The shipped sample files give a feeling for the size:

File Approximate size
images/background.mp4 8.6 MB
images/backdrop.png 4.2 MB
music/Questions-First.mp3 8.9 MB
images/music-cover.png 0.7 MB

Suggestions for keeping downloads small:

  • Video: use a short loop (roughly 10 to 30 seconds) in .mp4, no larger than 1080p, and remove the audio track. Keep videoMuted set to true.
  • Images: save photos as compressed JPG files where you can. Resize them to the size they are shown at. A full-screen background does not need to be larger than 1920 by 1080.
  • Audio: use .mp3 at 128 to 192 kbps. A song of a few minutes is then around 3 to 5 MB.
  • Staff photos: a card is small, so around 600 pixels on the long side is plenty.
  • Delete unused sample files from images/ and music/ once you have your own. Files that are not referenced in config.js are still downloaded.
  • For very large media, host the file on your own web server and use the https:// link instead of storing it in the resource.

If you use the default video background, the video file is the biggest part of the download. Switching to type: "color" or a compressed image removes it.

With autoplay: true the player tries to start the music as soon as the screen opens. The game’s built-in browser can refuse to play sound until the player interacts with the page. When that happens:

  • The player shows as paused.
  • The music starts on the player’s first mouse click or key press anywhere on the screen.
  • The player can also press the play button.

You cannot force sound to start without interaction. If you want no surprise sound at all, set autoplay: false. Keep volume moderate (the default is 0.4), because the music starts at that level for every player.

The music belongs to the loading screen. It stops when the loading screen closes.

The screen is built so that a missing file or a deleted section never leaves it blank.

What is missing What the player sees
Background image (type: "image") The background video, if video is set. Otherwise the solid color
Background video The solid color
Overlay image No overlay
Logo image The text logo (title and subtitle)
Music cover A speaker icon in place of the cover
Staff photo A gray block with the first letter of the name
Music file or link The player is shown, but the song does not play. Check the path and spelling
A list you emptied (staff, rules, updates) Its button disappears
A field you deleted A built-in value is used

The pill under the logo shows current / total.

  • The numbers come from your running server and refresh every few seconds while the loading screen is open.
  • The slot limit is the value of sv_maxclients in your server.cfg.
  • If live numbers cannot be received, the values of server.current and server.total are used. Set total to your real slot count so the fallback looks right.
  • To remove only the location text, set location: "".
  • No framework is needed for this. It works the same on standalone servers, ESX, QBCore and Qbox.

Working with spawn and multicharacter scripts

Section titled “Working with spawn and multicharacter scripts”

Leave the manifest at its default unless you have a problem. FiveM then closes the loading screen when the player’s session starts. If your character selection or spawn screen appears too late and the player briefly sees the game world, use the optional manual shutdown described in Installation.

With manual shutdown on:

  • The loading screen, including its music, stays up until a script closes it.
  • The loading bar can sit at or near 100 percent while it waits.
  • If you remove or stop the script that closes it, players stay on the loading screen.
Problem Likely cause What to do
A different loading screen appears Another loading screen resource is also started Remove the other resource from server.cfg. Only one loading screen can be active
My changes do not show The server was not restarted, or you did not reconnect Run refresh, then restart kivo-loading-screen, then disconnect and join again
I see placeholder content (sample staff, sample links) instead of mine config.js has a syntax error, so none of your settings load Check the file for a missing comma, a missing quote or a missing bracket. See below
The background is a plain dark color type is "color", or the file path is wrong Check the path and capitalization. Make sure the file is inside images/
type: "image" shows the video instead images/background.png does not exist, so the screen falls back to the video Add your image and point image at it, or set video to ""
The video does not play Wrong format, or a broken link Use .mp4 or .webm. Test the link in a browser. The screen falls back to the solid color
No music Autoplay was refused, wrong url, volume is 0, enabled is false, or tracks is empty Click the play button. Check the path and spelling. Make sure the file is in a folder served by the resource
Music plays but the seek bar does not move The link is a live stream Expected. Streams have no length
Buttons and links cannot be clicked The cursor setting in fxmanifest.lua was removed Keep the line loadscreen_cursor 'yes' in the manifest
A panel button is missing Its list is empty, its nav entry is false, or (Keybinds) enabled is false Add entries or switch the option on
A social button has no icon The type is not one of the five valid names Use Discord, Web Site, TikTok, Instagram or Twitter exactly as written
A social link does nothing when clicked The address does not start with http:// or https:// Write the full address
A staff card shows only a letter The photo path is wrong or the file is missing Check the path and capitalization. The third sample card uses a file that is not shipped
The loading screen never closes loadscreen_manual_shutdown 'yes' is active and no script closes the screen Make a spawn or multicharacter script close it, or comment the line out again
The loading screen closes before character selection Manual shutdown is off and your script needs it on Turn on manual shutdown, see Installation
First connection is slow Large files in images/ or music/ See Large files

The most common mistake is a missing comma between two entries.

Wrong:

links: [
{ type: "Discord", link: "https://discord.gg/your-invite" }
{ type: "Web Site", link: "https://your-server.example" },
],

Right:

links: [
{ type: "Discord", link: "https://discord.gg/your-invite" },
{ type: "Web Site", link: "https://your-server.example" },
],

Other frequent mistakes:

  • Curly quotes “like this” copied from a document. Use straight quotes "like this".
  • A missing closing }, ] or quote.
  • Deleting the first line window.KivoConfig = { or the final }.
  • Writing a date as plain text instead of new Date("2026-01-01").getTime().

A code editor such as Visual Studio Code marks these errors in red. If you cannot find the problem, put back the original config.js and re-apply your changes one section at a time.