Tela de carregamento personalizada para FiveM: loadscreen, fxmanifest e shutdown

Uma tela de carregamento é uma pequena página web que os jogadores veem enquanto os arquivos do servidor são baixados. É um recurso normal com um manifesto e um arquivo HTML. Este guia cobre os arquivos, o manifesto, fechar a tela você mesmo e mantê-la leve.

#O recurso

Crie uma pasta com o HTML e seus ativos:

resources/[ui]/my_loadscreen/
  fxmanifest.lua
  index.html
  css/style.css
  js/app.js
  img/background.jpg
  audio/music.ogg

#O fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

loadscreen 'index.html'

files {
    'index.html',
    'css/style.css',
    'js/app.js',
    'img/background.jpg',
    'audio/music.ogg',
}

Duas coisas importam aqui:

• loadscreen 'index.html' nomeia a página que FiveM mostra.
• Todo arquivo que a página usa, incluindo o HTML em si, deve estar em files. Um arquivo que não está listado retorna 404 e a tela é em branco ou quebrada naquela parte. Um padrão como 'img/*' é permitido para listar uma pasta inteira.

Adicione a server.cfg:

ensure my_loadscreen

#Um index.html minimal

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="css/style.css">
</head>
<body>
  <h1>Welcome to my server</h1>
  <div id="bar"><div id="fill"></div></div>
  <audio id="music" src="audio/music.ogg" autoplay loop></audio>
  <script src="js/app.js"></script>
</body>
</html>

Use caminhos relativos, como acima. A página roda no navegador do jogo, então você pode usar HTML, CSS e JavaScript normais. Para uma barra de progresso, a página recebe mensagens enquanto o jogo carrega:

window.addEventListener('message', (e) => {
  if (e.data.eventName === 'loadProgress') {
    document.getElementById('fill').style.width = (e.data.loadFraction * 100) + '%'
  }
})

#Apenas uma tela de carregamento

FiveM mostra uma única tela de carregamento. Se dois recursos declaram um loadscreen, apenas um é usado, e qual pode mudar entre inicios. Então:

• Remova ou pare qualquer outro recurso de tela de carregamento de server.cfg.
• Quando você quer testar um novo, comente a linha antiga em vez de iniciar ambos.

#Feche a tela você mesmo

Por padrão, FiveM fecha a tela de carregamento quando a sessão do jogo está pronta. Um script de multicaráter ou spawn frequentemente precisa que a tela fique aberta mais, para esconder o mundo até que o personagem seja escolhido. Para isso, o manifesto desativa o fechamento automático:

loadscreen_manual_shutdown 'yes'

Depois um script cliente deve fechá-lo:

-- client.lua
CreateThread(function()
    -- wait until your own condition: player spawned, character chosen...
    while not NetworkIsPlayerActive(PlayerId()) do
        Wait(100)
    end

    ShutdownLoadingScreenNui()
end)

ShutdownLoadingScreenNui fecha a página NUI de sua tela de carregamento. Um script que lida com o spawn, como um script de multicaráter, frequentemente a chama, ou os nativos atrás disso, para você. Verifique aquele script primeiro, depois adicione sua própria chamada apenas se nada mais fizer.

Atenção: se você definer loadscreen_manual_shutdown 'yes' e nada chamar o shutdown, os jogadores ficam na tela de carregamento para sempre. Se isso acontecer, veja players stuck on the loading screen.

#Música e vídeo: mantenha-os leves

Tudo em files é baixado por cada jogador. Uma tela de carregamento pesada torna a espera mais longa, o que é o oposto do objetivo.

• Música: use .ogg ou .mp3, alguns minutos no máximo, e um bitrate moderado. Uma faixa de 3 MB está bem, uma de 60 MB não. Adicione um botão de mudo, e defina o volume baixo no código, já que um início alto incomoda os jogadores.
• Vídeo: curto e em loop, em .webm ou .mp4, baixa resolução e baixo bitrate. Melhor ainda, use uma boa imagem de fundo, que é muito menor.
• Imagens: comprima-as. Um fundo de 200 a 400 KB se parece com um de 8 MB na maioria das telas.
• Fontes e bibliotecas: coloque-as no recurso. Carregá-las da internet em entrada torna a página mais lenta, e falha se o host estiver inativo.

Já que os jogadores baixam esses arquivos para cada nova versão, não as mude frequentemente. Quando um jogador ainda vê a página antiga após uma atualização, peça para clear the FiveM cache.

#Opcional: um cursor

Se você quer que o jogador clique na tela de carregamento, para regras ou um menu, adicione o seguinte ao manifesto:

loadscreen_cursor 'yes'

#Problemas comuns

• Tela em branco, sem estilo. Um arquivo está faltando de files, ou um caminho no HTML está errado.
• A tela padrão mostra. O recurso não está iniciado, ou a linha loadscreen está faltando.
• Nunca fecha. Você definou loadscreen_manual_shutdown 'yes' e nenhum script chama ShutdownLoadingScreenNui().
• Música não toca. Verifique o caminho do arquivo e o formato. Teste a página em um navegador normal primeiro.

#Checklist