ENDE
Documentation

Pepper Loadingscreen

Free loading screen with real loading progress, video, player welcome and info cards – standalone.

Overview

Pepper Loadingscreen shows a short intro video when players connect, flowing seamlessly into a loop. On top of it you get the server name, a subtitle, real loading progress with loading phases, a welcome with player name and player count, rotating info cards and tips. You set everything up in html/config.js (or html/custom.js) – any framework.

Features

  • Intro video → seamless loop, both replaceable (WebM or image)
  • Real loading progress with bar, percentage and text per loading phase
  • Welcome with player name and player count on connect
  • Rotating info cards and tips with counter and timer bar, optional QR code (e.g. for your Discord)
  • 3 layouts: classic, center, side
  • German and English with automatic language selection, accent color, darkening, video sound
  • html/custom.js for your own settings that survive updates
  • Standalone, no dependencies; no script runs in game

Requirements

Dependency Required/optional What for Link
FiveM server (fx_version 'cerulean') required Any recent build https://runtime.fivem.net/artifacts/fivem/
Framework not needed Works with ESX, QBCore, Qbox or no framework –
OneSync not needed – –
Database not needed Stores nothing – no database, no oxmysql –
Multicharacter script optional May close the loading screen itself (see "Multicharacter") –

Installation

  1. Download the resource from the Cfx.re Portal (https://portal.cfx.re/assets/granted-assets).
  2. Extract it to resources/[pepper]/pepper_loadingscreen. Do not rename the folder.
  3. Remove other loading screens – FiveM only shows one. Delete them from server.cfg and from resources.
  4. Add it to your server.cfg:
    ensure pepper_loadingscreen
  5. Adjust html/config.js (or copy html/custom.example.js to html/custom.js) and restart the server. There is no database and there are no items.

First test

  1. Connect to the server – the intro video starts and flows into the loop.
  2. The loading bar with percentage runs, the text changes with the loading phases (game data, map, scripts, session).
  3. Check the welcome "Welcome, <name>" and the player count.
  4. Change serverName in html/config.js, restart pepper_loadingscreen and reconnect – only then do you see the change.

Configuration

File Controls
html/config.js All settings and texts (language, layout, color, video, progress, welcome, cards, QR code, tips)
html/custom.js Your own values that override config.js – never shipped by updates (template custom.example.js)
html/media/ Videos and still image (intro.webm, loop.webm, poster.jpg)
html/style.css Look, for deeper changes
fxmanifest.lua loadscreen_manual_shutdown for multicharacter scripts

General, video and progress

window.PEPPER_LOADINGSCREEN = {
  locale: "auto",
  layout: "classic",
  accentColor: "#e5484d",
  video: { intro: "media/intro.webm", loop: "media/loop.webm", poster: "media/poster.jpg", sound: false, volume: 0.3, shade: 0.25 },
  // …
};
Option Default Description
locale "auto" "auto" (player's language, otherwise English), "de" or "en"
layout "classic" "classic" (bottom), "center" (centered) or "side" (left sidebar)
accentColor "#e5484d" Accent color (lines, dots, tip bar)
video.intro "media/intro.webm" Plays once – WebM or image, "" = off
video.loop "media/loop.webm" Loops afterwards – WebM or image, "" = off
video.poster "media/poster.jpg" Still image until the video plays or if it does not load
video.sound / video.volume false / 0.3 Video sound on/off, volume 0–1
video.shade 0.25 Darkening 0–1 for readability
progress.enabled / percent / phases true Loading bar, percentage, text per loading phase

Welcome, cards, QR code and tips

Option Default Description
welcome.name / welcome.players true / true Welcome with player name, player count (from sv_maxclients)
cards.enabled / cards.interval true / 10 Info cards on/off, seconds per card
qr.url "" Link for the QR code, e.g. your Discord, "" = off
tips.enabled / tips.interval / tips.shuffle true / 8 / false Tips on/off, seconds per tip, random order
locales.<language> de, en Server name, subtitle, loading texts and phases, welcome ({name}), player count ({players}, {max}), cards, QR text, tips

Your own video

Use WebM (VP9 or VP8) – FiveM can not play MP4 with H.264. Recommended: 1920×1080, 30 fps, ideally under 10 MB (players download the files when connecting). Convert it e.g. with HandBrake (preset "WebM") or ffmpeg:

ffmpeg -i video.mp4 -c:v libvp9 -b:v 5M -an loop.webm

Put the file into html/media/ and enter it, e.g. loop: "media/my-video.webm". Only one video? Set intro: "" and use your video as loop. An image (.jpg, .png, .webp) works instead of a video, too.

Own settings that survive updates

Copy html/custom.example.js to html/custom.js and only enter what differs from config.js. Lists such as tips or cards are replaced as a whole.

window.PEPPER_LOADINGSCREEN_CUSTOM = {
  qr: { url: "https://discord.gg/your-server" },
  locales: { de: { serverName: "Mein Server" }, en: { serverName: "My Server" } },
};

Multicharacter

By default FiveM closes the loading screen automatically. If your multicharacter script closes it itself (ShutdownLoadingScreenNui), uncomment this line in fxmanifest.lua:

loadscreen_manual_shutdown 'yes'

Commands and permissions

Pepper Loadingscreen has no commands, no keys and no permissions. It is only visible while connecting; on the server, server/handover.lua passes the player name and player count to the loading screen once per connect.

FAQ

The video is black or missing?

The file is MP4 or the path is wrong – use WebM (VP9/VP8) and check the path in config.js. Until the video plays, the loading screen shows the still image from video.poster.

The old loading screen still shows up?

Remove the other loading screen from server.cfg and resources and clear your FiveM cache. FiveM only shows one loading screen.

My changes are not visible?

Restart the resource and reconnect – loading screens are downloaded when connecting.

The loading screen closes too early or too late?

If your multicharacter script closes the loading screen itself, uncomment loadscreen_manual_shutdown 'yes' in fxmanifest.lua (see "Multicharacter"). Without such a script, leave the line commented out.

Does it work with my framework?

Yes. The loading screen is standalone and works with ESX, QBCore, Qbox and any other framework.

Does it cost performance in game?

No. No script runs in game; measured at 0.00 ms. Only on the server a small script passes the name and player count on connect.

Does it interfere with my queue or whitelist?

No. The server script only uses deferrals.handover and no deferrals.defer(), so queue and whitelist scripts stay untouched.

The welcome or player count is missing?

Both come from the server script on connect. Check that server/handover.lua is still listed in fxmanifest.lua and welcome.name / welcome.players are true. Without the data both lines stay hidden.

Can I use an image instead of a video?

Yes. Enter an image path (.jpg, .png, .webp) as loop and set intro: "".

How do I change the color and the layout?

accentColor sets the accent color, layout picks classic, center or side. For more, edit html/style.css.

How do I change texts, tips and info cards?

Under locales.de and locales.en in config.js (or in your custom.js). With locale: "auto" every player gets German or English matching their game language.

How do I update Pepper Loadingscreen?

New versions appear in the Cfx.re Portal (Granted Assets) and are announced in Discord. With html/custom.js your settings survive the update; otherwise back up html/config.js and your own videos from html/media/ first.

Support

Questions or bugs? Open a ticket in our Discord: https://discord.gg/6NaFJWKDYu – link your purchase with /verify first.

Permanently tested on the Pepper Scripts dev server.

Changelog

Current version 1.1.0: real loading progress, welcome with player count, info cards, QR code, three layouts, automatic language selection and custom.js. All changes are listed in the CHANGELOG.md in the resource folder.

Found a mistake? Report it on Discord.