# 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](/docs/resources/qb-spawn) and
[qb-multicharacter](/docs/resources/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

1. Add the resource folder to your server and `ensure qb-loading` in `server.cfg`.
2. Replace `assets/images/1.png` with your own carousel image, or add more and register another
   `q-carousel-slide` in `html/index.html`.
3. Replace `assets/audio/noncopyright.mp3` with audio you have the right to use.
4. 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`](https://github.com/qbcore-fivem/qb-loading/blob/6b13442b9e7cd1bcbe0be8dd2b4604f07a999cb2/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](/docs/resources/qb-smallresources) or any other resource does not update this
list, so edit it whenever your keymap changes. See
[Commands and key mappings](/docs/guides/keybindings) 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](/docs/resources/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:

1. Join with a fresh client cache and confirm the screen renders with your own image and copy.
2. Confirm the screen is dismissed once the character selection appears.
3. Toggle each of the three settings switches and confirm audio, autoplay, and video respond.
4. Join with the CDN hosts blocked and record how far the layout degrades.

If you want a different design instead of editing the bundled HTML, compare
[loading screens on RPScripts](https://rpscripts.net/product-category/fivem-loadingscreens/) and apply the
same external-request and start-order checks as above. RPScripts and qbcore.net are operated by the same owner.

## Sources

- [fxmanifest.lua](https://github.com/qbcore-fivem/qb-loading/blob/6b13442b9e7cd1bcbe0be8dd2b4604f07a999cb2/fxmanifest.lua)
- [html/index.html](https://github.com/qbcore-fivem/qb-loading/blob/6b13442b9e7cd1bcbe0be8dd2b4604f07a999cb2/html/index.html)
- [html/app.js](https://github.com/qbcore-fivem/qb-loading/blob/6b13442b9e7cd1bcbe0be8dd2b4604f07a999cb2/html/app.js)
- [Resource manifest reference](https://docs.fivem.net/docs/scripting-reference/resource-manifest/resource-manifest/)
