Como Criar uma Tela de Carregamento 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'
}

Recursos novos devem usar fxmanifest.lua. Não adicione o manifesto antigo __resource.lua como alternativa. As diretivas estão definidas na referência oficial de manifestos 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 guia oficial de telas de carregamento da Cfx.re documenta loadProgress e os demais eventos disponibilizados para esse frame de NUI. Trate os dados dos eventos como entrada e atualize o texto com textContent, não com innerHTML.

Passe apenas dados de handover seguros

Um manipulador de playerConnecting no servidor pode enviar valores pequenos usando deferrals.handover. O FiveM os disponibiliza em window.nuiHandoverData. Use isso para valores de exibição, como o nome do jogador; nunca inclua segredos, tokens, identificadores privados ou dados que concedam um direito de acesso. 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

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

Como Criar uma Tela de Carregamento do FiveM