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.
Examples
Section titled “Examples”Image background with your own logo
Section titled “Image background with your own logo”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",},Solid color with new theme colors
Section titled “Solid color with new theme colors”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,},Hosted video and a hosted playlist
Section titled “Hosted video and a hosted playlist”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.
Minimal screen
Section titled “Minimal screen”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.
Full server setup
Section titled “Full server setup”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 audio or hosted audio
Section titled “Local audio or hosted audio”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:00and the seek bar does nothing.
Large files
Section titled “Large files”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. KeepvideoMutedset totrue. - 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
.mp3at 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/andmusic/once you have your own. Files that are not referenced inconfig.jsare 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.
Music autoplay restrictions
Section titled “Music autoplay restrictions”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.
When something is missing
Section titled “When something is missing”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 |
Player count
Section titled “Player count”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_maxclientsin yourserver.cfg. - If live numbers cannot be received, the values of
server.currentandserver.totalare used. Settotalto 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.
Troubleshooting
Section titled “Troubleshooting”| 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 |
Finding a syntax error
Section titled “Finding a syntax error”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.
