es_loadingscreen

A standalone FiveM loading screen with configurable branding, media slideshow, music, side-panel cards, and player profile integration.

Features

• FiveM loadscreen target (dist/index.html) with loadscreen_manual_shutdown.
• Branding: server name, tagline, logo, background image/video, glow color.
• Media slideshow: auto-detects image{n}.jpg/png/webp or explicit Media.Items.
• Background video support (optional, muted and looping).
• Music playlist: auto-detects music{n}.mp3/ogg or explicit Music.Tracks with per-track start times.
• Audio waveform visualizer and in-screen music controls.
• Rotating tips with configurable interval.
• Side panel cards: gallery, news, and events (reorderable).
• Player badge: displays the joining player's name, Steam profile link, and optional avatar fetched from playerdb.co.
• Live player count (current / max) on the toolbar.
• User toggles for music, glow, snow, and profile badge (where enabled).
• Snow overlay and configurable vignette.
• Manual shutdown on playerSpawned or es_loadingscreen:playerLoaded.

Requirements

• A GTA V / FiveM server.
• Bun for building the UI (the web/ directory uses bun.lock).

Installation

1. Clone or copy this repository into your server's resources/ folder:

   resources/[eco]/es_loadingscreen
   

2. Build the UI:

   cd web
   bun install
   bun run build

   This writes the production files to ../dist/.
3. Make sure dist/ contains index.html and assets/.
4. Add to your server.cfg:

   ensure es_loadingscreen
   

5. Start your server.

The legacy ui/ folder is not loaded by fxmanifest.lua in this version. Use web/ for source edits and dist/ as the runtime output.

Configuration

All runtime configuration is in config.lua. Asset paths are relative to dist/assets/.

Section	Purpose
Config.ServerName / Config.ServerTagline / Config.Logo	Header branding
Config.Background	Fallback background image
Config.Links	Discord / website pills shown in the top-left
Config.Media	Background image/video slideshow (AutoDetect, BaseName, Extensions, Items, Interval, Video)
Config.Music	Music playback (Enabled, Volume, AutoDetect, Tracks, Url)
Config.Tips	Rotating loading tips
Config.SidePanel	Enable/order news, events, and gallery cards
Config.Gallery	Auto-load images from dist/assets/gallery or explicit Items
Config.PlayerBadge	Show the joining player's Steam name/avatar
Config.Snow / Config.Vignette / Config.GlowColor	Visual effects
Config.Settings	Allow music, glow, and snow toggles
Config.HideVanillaBusySpinner	Disables the default FiveM spinner

To customize assets without editing config.lua manually, place files in dist/assets/ matching the BaseName + Extensions pattern (for example image.jpg, image1.png, music.mp3). Alternatively, edit files under web/public/assets/ and rerun bun run build.

Architecture

es_loadingscreen/
├── fxmanifest.lua          # Resource manifest; loadscreen target is dist/index.html
├── config.lua              # Shared configuration (Config global)
├── client/main.lua         # Sends config to NUI, polls server, shuts down on spawn
├── server.lua              # Scans gallery directory, returns player count, fetches Steam avatar
├── web/                    # Svelte 5 + Vite source
│   ├── src/
│   │   ├── App.svelte      # Main loading screen UI and NUI message handling
│   │   ├── lib/            # Config merge, playlists, color/audio helpers
│   │   └── dev/            # Dev harness with mock config/progress
│   ├── public/assets/      # Source assets for the build
│   └── dist/ output at ../dist
└── dist/                   # Production build consumed by FiveM

• fxmanifest.lua declares loadscreen 'dist/index.html', loadscreen_cursor 'yes', loadscreen_manual_shutdown 'yes', and loadscreen_hide_vanilla_blur 'yes'.
• The client requests galleryImages and playerProfile from the server, then sends a merged config payload to the loadscreen via SendLoadingScreenMessage.
• The server scans dist/assets/gallery for images using io.popen, resolves the player's steam: identifier, and optionally calls https://playerdb.co/api/player/steam/{steam64} to retrieve an avatar.
• The Svelte UI listens for NUI messages (config, playerCount, playerProfile) and builds the media/music playlists from the merged config.
• Loading completion is driven by playerSpawned or es_loadingscreen:playerLoaded; the client calls ShutdownLoadingScreenNui() once.

Limitations

• dist/ is a generated build output. You must run bun run build in web/ after any source or asset change in web/public/.
• The legacy ui/ directory is present but not used by the current manifest.
• Background video autoplay may be blocked by browser autoplay policies and will fall back to the image slideshow.
• Steam avatar lookup depends on the public playerdb.co service and a valid steam: identifier; it will fail silently if the service is unreachable or the player has no public Steam profile.
• Server-side gallery scanning uses io.popen with dir (Windows) or find (Linux) and may not work in heavily sandboxed Lua runtimes.
• The UI loads Google Fonts from fonts.googleapis.com; if the server/client has no outbound internet, fallback fonts are used.
• This resource is for GTA V / FiveM only (fx_version 'cerulean', game 'gta5').

License

This project is licensed under the MIT License.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Cfx, FiveM, Rockstar Games, or Take-Two Interactive. All trademarks and copyrights are property of their respective owners.