Cómo crear una pantalla de carga de FiveM

Una pantalla de carga actual de FiveM es un recurso NUI declarado con loadscreen en fxmanifest.lua. Mantén la primera versión local y pequeña: un documento HTML, una hoja de estilos y un script. Añade datos de progreso o de traspaso del servidor solo después de que la pantalla básica se abra y se cierre correctamente.

Los ejemplos de configuración y código aquí están dirigidos a FiveM para GTA V Legacy. Enhanced tiene diferentes reglas de tiempo de ejecución y compatibilidad; consulta los cambios de Legacy a Enhanced de Cfx.re antes de aplicarlos a un servidor Enhanced.

Haz una copia de seguridad del recurso existente y mantén primero el apagado automático predeterminado. Un script de apagado manual defectuoso puede dejar a los jugadores mirando la pantalla de carga después de que el juego esté listo.

Estructura del recurso

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'
}

Los nuevos recursos deben usar fxmanifest.lua. No añadas una __resource.lua de respaldo heredada. Las directivas se definen en la referencia del manifiesto de recursos.

Crea HTML accesible

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>

Usa texto que siga siendo legible sobre el fondo, respete el movimiento reducido y no dependa de audio de reproducción automática. Comprime imágenes y vídeos antes de empaquetarlos; cada cliente tiene que descargar el recurso.

Añade la hoja de estilos

Guarda esto como html/style.css; proporciona la hoja de estilos a la que hace referencia el HTML:

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; }

Lee el evento documentado de progreso de carga

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)}%`;
});

La guía oficial guía de pantalla de carga de Cfx.re documenta loadProgress y los otros eventos expuestos a este marco NUI. Trata los datos del evento como entrada y actualiza el texto con textContent, no innerHTML.

Pasa solo datos de transferencia seguros

Un controlador de playerConnecting del lado del servidor puede pasar valores pequeños con deferrals.handover. FiveM los expone como window.nuiHandoverData. Úsalo para valores de visualización como el nombre de un jugador; nunca incluyas secretos, tokens, identificadores privados o datos que otorguen un derecho. Inserta valores controlados por el jugador con textContent o innerText.

Habilita el apagado manual solo cuando sea necesario

Si la pantalla debe desvanecerse después de que comiencen los scripts del cliente, añade estas líneas:

loadscreen_manual_shutdown 'yes'
client_script 'client.lua'

El siguiente ejemplo la cierra desde client.lua cuando se inicia la sesión de red. Si tu framework requiere primero la selección de personaje, usa su señal de listo documentada en su lugar:

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

    ShutdownLoadingScreenNui()
end)

Prueba las reconexiones, los reinicios de recursos y un cliente lento. Si la pantalla se queda atascada, elimina loadscreen_manual_shutdown y el script del cliente para volver a la gestión automática del ciclo de vida.

Despliega y verifica

1. Añade ensure my_loadscreen en el punto deseado de server.cfg.
2. Usa refresh y ensure my_loadscreen en un servidor de desarrollo.
3. Conéctate con un cliente limpio e inspecciona la consola F8 y la del servidor.
4. Prueba una conexión lenta, una reconexión, una conexión cancelada y un reinicio del servidor.
5. Comprueba las resoluciones de escritorio comunes y un cliente de baja potencia antes de reemplazar el recurso de producción.