Como Criar uma Tela de Carregamento do FiveM

Uma tela de carregamento atual do FiveM é um recurso NUI declarado com loadscreen em fxmanifest.lua. Mantenha a primeira versão local e pequena: um documento HTML, uma folha de estilo e um script. Adicione dados de progresso ou de transferência do servidor somente depois que a tela básica abrir e fechar corretamente.

A configuração e os exemplos de código aqui são voltados ao FiveM para GTA V Legacy. O Enhanced tem regras diferentes de runtime e de compatibilidade; verifique as alterações de Legacy para Enhanced do Cfx.re antes de aplicá-las a um servidor Enhanced.

Faça backup do recurso existente e mantenha o desligamento automático padrão primeiro. Um script de desligamento manual com problemas pode deixar os jogadores olhando para a tela de carregamento depois que o jogo estiver pronto.

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

Novos recursos devem usar fxmanifest.lua. Não adicione um legado __resource.lua fallback. As diretivas são definidas na referência oficial do manifesto de recursos. e a referência do manifesto de recursos.

Crie HTML acessível

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>

Use texto que permaneça legível sobre o fundo, respeite o movimento reduzido e não dependa de áudio com reprodução automática. Comprima imagens e vídeos antes de empacotá-los; cada cliente precisa baixar o recurso.

Adicione a folha de estilo

Salve isto como html/style.css; ele fornece a folha de estilo referenciada pelo 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; }

Leia o evento de progresso de carregamento documentado

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

O oficial guia de tela de carregamento do Cfx.re documenta loadProgress e os outros eventos expostos a este frame NUI. Trate os dados do evento como entrada e atualize o texto com textContent, não innerHTML.

Passe apenas dados de handover seguros

Um handler playerConnecting pode passar pequenos valores com deferrals.handover. FiveM os expõe como window.nuiHandoverData. Use isso para exibir valores como um nome de jogador; nunca inclua segredos, tokens, identificadores privados ou dados que concedam um direito. Insira valores controlados pelo jogador com textContent ou innerText.

Habilite o desligamento manual apenas quando necessário

Se a tela precisar desaparecer após o início dos scripts do cliente, adicione estas linhas:

loadscreen_manual_shutdown 'yes'
client_script 'client.lua'

O exemplo abaixo o fecha de client.lua quando a sessão de rede começa. Se o seu framework exigir a seleção de personagem primeiro, use o sinal de pronto documentado em vez disso:

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

    ShutdownLoadingScreenNui()
end)

Teste reconexões, reinícios de recursos e um cliente lento. Se a tela puder ficar travada, remova loadscreen_manual_shutdown e o script do cliente para retornar ao gerenciamento automático do ciclo de vida.

Implante e verifique

1. Adicione ensure my_loadscreen no ponto pretendido em server.cfg.
2. Use refresh e ensure my_loadscreen em um servidor de desenvolvimento.
3. Conecte-se com um cliente limpo e inspecione o F8 e o console do servidor.
4. Teste uma conexão lenta, reconexão, conexão cancelada e reinício do servidor.
5. Verifique resoluções comuns de desktop e um cliente de baixo desempenho antes de substituir o recurso de produção.