Skip to content

Custom loading screen

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.js

The 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.

Save this HTML as branding/loading/index.html:

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:

loading.css
: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:

loading.js
// @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 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.

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.