qb-loading
qb-loading is a FiveM loadscreen. It renders while a joining player downloads and starts
resources, then dismisses itself. It contains no gameplay code, no Lua, and no server logic. The
entire resource is a manifest plus a static web page.
It is unrelated to qb-spawn and qb-multicharacter, which run after the loadscreen is gone.
The manifest at the commit linked above declares version 1.2.0.
Dependencies and start order
The manifest declares no dependencies and contains no client_scripts, server_scripts, or
shared_scripts. There is nothing to order against, because a loadscreen runs before normal
resources are usable.
The manifest keys that matter:
| Key | Value at this commit | Effect |
|---|---|---|
loadscreen | html/index.html | The page rendered during join |
loadscreen_cursor | 'yes' | The player gets a mouse cursor, needed for the settings toggles |
loadscreen_manual_shutdown | 'yes' | The screen does not auto-close. It stays until dismissed |
files | assets/**, html/* | Makes the assets fetchable by the page |
loadscreen_manual_shutdown 'yes' is the key to understand. With it set, FiveM will not tear the
screen down on its own. If nothing calls SHUTDOWN_LOADING_SCREEN_NUI, the player is left staring
at the loading screen after the game is ready.
Setup
- Add the resource folder to your server and
ensure qb-loadinginserver.cfg. - Replace
assets/images/1.pngwith your own carousel image, or add more and register anotherq-carousel-slideinhtml/index.html. - Replace
assets/audio/noncopyright.mp3with audio you have the right to use. - Edit the strings at the top of
html/app.js.
Configuration surface
There is no config.lua. All user-facing copy lives in the setup() return table at the top of
html/app.js.
At this commit the editable keys are:
| Key group | Keys | Purpose |
|---|---|---|
| Carousel copy | CarouselText1 to CarouselText4, CarouselSubText1 to CarouselSubText4 | Rotating text panel and its captions |
| Download panel | DownloadTitle, DownloadDesc | The text shown while resources download |
| Settings panel | SettingsTitle, AudioTrackDesc1, AutoPlayDesc2, PlayVideoDesc3 | Labels for the three player toggles |
| Keybind panel | KeybindTitle, Keybind1 to Keybind16 | The default keybind legend |
The shipped keybind legend describes a stock QBCore build. It is static text. Changing a key in qb-smallresources or any other resource does not update this list, so edit it whenever your keymap changes. See Commands and key mappings for how those bindings are actually registered.
Carousel or video background
html/index.html ships with the image carousel active and the video block commented out. To switch,
comment out the <q-carousel> block and uncomment the fixed-position <video> block below it, then
replace assets/video/freestockvideo.mp4.
External requests
html/index.html loads jQuery, Vue 3, and Quasar from public CDNs, plus Font Awesome and Google
Fonts stylesheets. Players on restricted networks, and servers whose players are offline-hostile,
will see an unstyled or partly broken screen. Vendoring those files into html/ and updating the
<script> and <link> tags removes the dependency on third-party availability.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| Loading screen never disappears | loadscreen_manual_shutdown is 'yes' and nothing called ShutdownLoadingScreenNui(). In a stock QBCore build qb-multicharacter makes that call from its client.lua. Confirm it is started and reaching that point |
| Screen is unstyled, no layout | The Quasar or Font Awesome CDN request failed. Check the loadscreen devtools console, or vendor the assets |
| Image or audio 404 | The file is not matched by the files block. assets/** and html/* are matched at this commit, note that html/* is one level deep only |
| Audio does not start | Browser autoplay policy, or the file was replaced with an unsupported codec. The shipped element uses autoplay loop on an mp3 |
Changes to app.js do not appear | The loadscreen is cached client side. Restart the client, not just the resource |
Proposed manual smoke test
Not yet executed. On staging:
- Join with a fresh client cache and confirm the screen renders with your own image and copy.
- Confirm the screen is dismissed once the character selection appears.
- Toggle each of the three settings switches and confirm audio, autoplay, and video respond.
- Join with the CDN hosts blocked and record how far the layout degrades.