Loading-screen message contracts

Loading-screen events are browser message payloads, not Lua network events. Read event.data.eventName. For total progress, use the documented loadFraction; counting arbitrary log or initialization messages cannot produce a reliable overall percentage.

The table covers all eleven event pages in the pinned upstream loading-screen manual. The official loading-screen guide supplies the lifecycle, handover and manual-shutdown contract. These messages describe loading; they do not establish that framework character data is ready.

All documented messages

Every row also has eventName with the exact event name shown.

Event	Additional fields	How to use it
`loadProgress`	`loadFraction: number` from 0 to 1	Update total progress; validate a finite number before assigning it.
`onLogLine`	`message: string`	Show a bounded status line as text, not HTML.
`startDataFileEntries`	`count: number`	Begin a data-file phase; this is not the total count of every future loading event.
`onDataFileEntry`	`name: string`, `type: number`, `isNew: boolean`	Observe one entry; it can also occur during initialization functions.
`performMapLoadFunction`	`idx: number`	Identify the current map-load function observation, not a percentage.
`endDataFileEntries`	None	End that data-file phase, not necessarily the whole connection.
`startInitFunction`	`type: string`	Begin an initialization-function group.
`startInitFunctionOrder`	`type: string`, `order: number`, `count: number`	Begin an ordered batch; multiple batches can share a type.
`initFunctionInvoking`	`type: string`, `name: string`, `idx: number`	Observe the function about to run.
`initFunctionInvoked`	`type: string`, `name: string`	Observe its completion; do not assume the batch is complete.
`endInitFunction`	`type: string`	End that initialization group.

Each payload is documented under its corresponding pinned source page . Unknown messages should be ignored without throwing; newer clients may send messages your UI does not use.

A complete minimal loading screen

Create a resource with this fxmanifest.lua:


fx_version 'cerulean'
game 'gta5'
loadscreen 'html/index.html'
files { 'html/index.html', 'html/loading.js' }

Use this html/index.html:


<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Joining the development server</title></head>
<body>
  <h1>Joining the development server</h1>
  <label for="progress">Reported loading progress</label>
  <progress id="progress" max="1" value="0"></progress>
  <p id="status" role="status">Waiting for loading information.</p>
  <script src="loading.js"></script>
</body>
</html>

In html/loading.js, update only fields you understand:


const progress = document.querySelector('#progress');
const status = document.querySelector('#status');
window.addEventListener('message', ({ data }) => {
  if (!data || typeof data !== 'object') return;
  if (data.eventName === 'loadProgress' && Number.isFinite(data.loadFraction)) {
    progress.value = Math.min(1, Math.max(0, data.loadFraction));
  } else if (data.eventName === 'onLogLine' && typeof data.message === 'string') {
    status.textContent = data.message.slice(0, 240);
  } else if (data.eventName === 'initFunctionInvoking' && typeof data.name === 'string') {
    status.textContent = `Initializing: ${data.name.slice(0, 120)}`;
  }
});

Start the resource on a development server and reconnect a client. This minimal version leaves the default lifetime behavior intact; it does not enable manual shutdown and risk waiting forever for a client script that failed to start. Do not publish initialization logs or handover data to a third-party telemetry service without considering their contents.

Test failures without fabricating engine evidence

In a browser-only fixture, dispatch controlled MessageEvent objects to check missing data, unknown event names, NaN, progress outside the allowed range and a status string containing HTML-like characters. The progress element should stay bounded and the text should remain text. That validates DOM handling only; an actual reconnect is required to establish that the engine sends the expected messages on your artifact.

For handover names, render with textContent and do not expose the provided server address unnecessarily. For an intentional fade-out, review loadscreen_manual_shutdown, SendLoadingScreenMessage and ShutdownLoadingScreenNui in the advanced NUI guide. A value of 1 on the progress bar is not a substitute for the game’s documented shutdown lifecycle.