Cómo Crear una Pantalla de Carga 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 recursos nuevos deben utilizar fxmanifest.lua. No añadas un __resource.lua antiguo como alternativa. Las directivas se definen en la referencia oficial 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 de pantallas de carga de Cfx.re documenta loadProgress y los demás eventos expuestos a este marco NUI. Trata los datos de los eventos como entradas y actualiza el texto con textContent, no con innerHTML.

Pasa solo datos de transferencia seguros

Un manejador de playerConnecting del lado del servidor puede pasar valores pequeños mediante deferrals.handover. FiveM los expone como window.nuiHandoverData. Utilízalo para valores de visualización, como el nombre de un jugador; nunca incluyas secretos, tokens, identificadores privados ni datos que concedan derechos de acceso. Inserta los valores controlados por jugadores 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

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

Cómo crear una pantalla de carga de FiveM