Custom loading screen
Add the page
Section titled “Add the page”Place the page at branding/loading/index.html under the client resource root.
With resources.pack.path = "client", use:
client/└── branding/ └── loading/ ├── index.html ├── loading.css └── loading.jsThe client selects this page automatically. It opens at
resources://branding/loading/index.html before client scripts start.
Keep images, fonts, styles and scripts beside the page and use relative URLs,
such as ./logo.svg. A leading slash resolves from the branding root,
so /logo.svg refers to branding/logo.svg.
The page fills the game window and resizes automatically. It receives no mouse or keyboard input, so keep the design informational. A dark background covers the game while the browser loads and remains behind transparent parts of the page.
Display status and errors
Section titled “Display status and errors”Save this HTML as branding/loading/index.html:
<!doctype html><html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Loading</title> <link rel="stylesheet" href="./loading.css" /> <script src="./loading.js" defer></script> </head> <body aria-busy="true"> <main> <h1>Harbor</h1> <p id="loading-status" role="status" aria-live="polite">Loading...</p> </main> </body></html>Add loading.css beside it:
:root { color-scheme: dark; font-family: system-ui, sans-serif; background: #10131a; color: #f3f5fa;}
* { box-sizing: border-box; }html, body { width: 100%; height: 100%; margin: 0; }body { display: grid; place-items: center; }main { width: min(36rem, 90vw); padding: 2rem; text-align: center; }h1 { font-size: clamp(2rem, 5vw, 4rem); }
#loading-status { color: #b9c2d4; line-height: 1.5; white-space: pre-line; overflow-wrap: anywhere;}
body.error #loading-status { color: #ffb5a7; }In loading.js, listen for loading.status:
// @ts-check/// <reference types="@revomp/types-webview" />
(() => { const statusText = document.getElementById('loading-status'); if (!statusText) throw new Error('Missing loading status element');
revo.on('loading.status', (/** @type {{ text: string, error: boolean }} */ state) => { statusText.textContent = state.text; document.body.classList.toggle('error', state.error); document.body.setAttribute('aria-busy', String(!state.error)); });})();| Field | Meaning |
|---|---|
text |
Current loading, connection or error message. |
error |
true when the message describes a failure. |
The latest status is sent once the page and its bridge are ready, then whenever
it changes. Register the listener during page initialization, before waiting
for remote data or other asynchronous work. The deferred script above registers
it before DOMContentLoaded.
Use textContent to display the message as text. Preserve line breaks and allow
long messages to wrap. The example also clears the error style when a subsequent
status reports normal loading.
The page needs no separate readiness message. The client hides it when session startup completes and shows it again during reconnect or when an error needs to be displayed. It can reuse the same document when showing it again.
To keep loading visible while preparing the initial scene, use the client functions described in Loading screen.
Publish changes
Section titled “Publish changes”Publish the resources and restart the server to select the new release. Clients apply the updated page on their next launch or when reconnect installs the release. Changes limited to loading-screen HTML, CSS, scripts and images do not require a GTA restart.
Branding files use the same packaging and encryption settings as the other
client resources. Remove branding/loading/index.html from the next release
to restore the built-in screen.
Fallback and testing
Section titled “Fallback and testing”A missing custom page uses the built-in screen. Failed navigation, an HTTP error response or a document that takes longer than 15 seconds to load also switches to the built-in screen.
Fallback covers document loading. A successfully loaded page can still have
JavaScript errors or missing images and styles. If the design appears but its
status never updates, check that loading.js loaded and registered the
loading.status listener.
Check a fresh launch, reconnect and a startup failure. Confirm that long error messages remain readable and that the layout adapts when the game resolution changes. Keep essential files in the bundle so the loading screen can display without waiting for an external website.
For page errors, use CEF debugging. The
client logs also report
Could not load loading screen, Loading screen returned HTTP and
Loading screen did not finish loading.