So erstellst du einen FiveM-Ladebildschirm

Ein aktueller FiveM-Ladebildschirm ist eine NUI-Ressource. Die Deklaration erfolgt über loadscreen in fxmanifest.lua. Halte die erste Version lokal und klein: ein HTML-Dokument, ein Stylesheet und ein Skript. Füge Fortschritts- oder Serverübergabedaten erst hinzu, nachdem der grundlegende Bildschirm korrekt geöffnet und geschlossen wurde.

Die hier gezeigten Konfigurations- und Codebeispiele beziehen sich auf FiveM für GTA V Legacy. Enhanced hat andere Laufzeit- und Kompatibilitätsregeln; überprüfe die Legacy-zu-Enhanced-Änderungen von Cfx.re bevor du sie auf einen Enhanced-Server anwendest.

Sichere die vorhandene Ressource und behalte zuerst die standardmäßige automatische Abschaltung bei. Ein fehlerhaftes Skript für die manuelle Abschaltung kann dazu führen, dass Spieler auf dem Ladebildschirm verharren, nachdem das Spiel bereit ist.

Ressourcenstruktur

resources/[local]/my_loadscreen/
├── fxmanifest.lua
└── html/
    ├── index.html
    ├── style.css
    └── app.js

fxmanifest.lua:

fx_version 'cerulean'
game 'gta5'

author 'Your name'
description 'FiveM loading screen'
version '1.0.0'

loadscreen 'html/index.html'

files {
    'html/index.html',
    'html/style.css',
    'html/app.js'
}

Verwende für neue Ressourcen fxmanifest.lua. Ergänze keinen veralteten __resource.lua Fallback. Die offizielle Dokumentation der Direktiven findest du hier: Ressourcenmanifestreferenz.

Erstelle barrierefreies HTML

html/index.html:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <title>Connecting to Example RP</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <main>
    <h1>Connecting to Example RP</h1>
    <progress id="progress" value="0" max="1" aria-label="Loading progress"></progress>
    <p id="status" aria-live="polite">Loading server resources…</p>
  </main>
  <script src="app.js"></script>
</body>
</html>

Verwende Text, der über dem Hintergrund lesbar bleibt, reduzierte Bewegung berücksichtigt und nicht von automatisch startendem Audio abhängt. Komprimiere Bilder und Videos, bevor du sie verpackst; jeder Client muss die Ressource herunterladen.

Füge das Stylesheet hinzu

Speichere dies als html/style.css; es liefert das im HTML referenzierte Stylesheet:

body { margin: 0; min-height: 100vh; display: grid; place-items: center;
  background: #15212b; color: #fff; font: 20px/1.6 system-ui; }
main { width: min(620px, 85vw); }
progress { width: 100%; height: 20px; accent-color: #6cd6ba; }

Lies das dokumentierte Ladefortschritt-Ereignis

html/app.js:

const progress = document.getElementById('progress');
const status = document.getElementById('status');

window.addEventListener('message', (event) => {
  if (event.data?.eventName !== 'loadProgress') return;

  const value = Number(event.data.loadFraction);
  if (!Number.isFinite(value)) return;

  const clamped = Math.max(0, Math.min(1, value));
  progress.value = clamped;
  status.textContent = `Loading ${Math.round(clamped * 100)}%`;
});

Der offizielle Cfx.re Ladebildschirm-Anleitung dokumentiert loadProgress und die anderen Ereignisse, die diesem NUI-Frame zur Verfügung stehen. Behandle Ereignisdaten als Eingabe und aktualisiere Text mit textContent, nicht innerHTML.

Übergib nur sichere Handover-Daten

Ein serverseitiger playerConnecting -Handler kann kleine Werte übergeben mit deferrals.handover. FiveM stellt sie bereit als window.nuiHandoverData. Nutze dies für Anzeigewerte wie den Spielernamen. Übertrage niemals geheime Daten, Tokens, private Kennungen oder Daten, die Berechtigungen gewähren. Zum Einfügen spielergesteuerter Werte verwende textContent oder innerText.

Manuelles Herunterfahren nur bei Bedarf aktivieren

Wenn der Bildschirm nach dem Start von Client-Skripten ausgeblendet werden muss, füge diese Zeilen hinzu:

loadscreen_manual_shutdown 'yes'
client_script 'client.lua'

Das folgende Beispiel schließt ihn über client.lua, sobald die Netzwerksitzung startet. Wenn dein Framework zuerst eine Charakterauswahl erfordert, verwende stattdessen dessen dokumentiertes Ready-Signal:

CreateThread(function()
    while not NetworkIsSessionStarted() do
        Wait(100)
    end

    ShutdownLoadingScreenNui()
end)

Teste Wiederverbindungen, Ressourcen-Neustarts und einen langsamen Client. Wenn der Bildschirm hängen bleiben kann, entferne loadscreen_manual_shutdown und das Client-Skript, um zur automatischen Lebenszyklusverwaltung zurückzukehren.

Bereitstellen und überprüfen

1. Hinzufügen ensure my_loadscreen an der vorgesehenen Stelle in server.cfg.
2. Verwende refresh und ensure my_loadscreen auf einem Entwicklungsserver.
3. Verbinde dich mit einem sauberen Client und überprüfe F8 sowie die Serverkonsole.
4. Teste eine langsame Verbindung, eine erneute Verbindung, eine abgebrochene Verbindung und einen Serverneustart.
5. Überprüfe gängige Desktop-Auflösungen und einen leistungsschwachen Client, bevor du die Produktionsressource ersetzt.