FiveM preso na tela de carregamento: causas e como debugar

Jogadores conectam, a barra enche, e então nada: a tela de carregamento fica para sempre, ou o jogo congela em uma tela preta. Este guia passa pelas causas na ordem que é mais rápido descartar, e mostra como usar F8 e o console do server para encontrar a que você tem.

#Primeiro: é everyone ou um jogador?

• Todos estão presos. A causa é no server: um recurso, o framework, ou um loadscreen.
• Um jogador está preso. Olhe para aquele cliente do jogador: cache, uma conexão lenta, mods, ou um build de jogo antigo. Comece com clearing the FiveM cache.

Junte-se uma vez você mesmo e pressione F8. Isso funciona na tela de carregamento também. Leia o que é impresso ali, e mantenha o console do server aberto do outro lado.

#1. Um erro de script no cliente

F8 lista erros de cliente. Qualquer linha assim durante o carregamento é uma forte pista:

SCRIPT ERROR: @my_script/client/main.lua:25: attempt to index a nil value (global 'ESX')

Um client script que trava em sua start thread pode deixar o spawn flow inacabado. Conserte o script nomeado no erro: os guias para reading a script error, ESX nil e QBCore nil cobrem os comuns. Depois reinicie o recurso e se junte novamente.

Teste por eliminação se nada for impresso: pare o recurso mais recentemente adicionado ou alterado, se junte novamente, e veja se o carregamento termina.

#2. Ninguém spawna o jogador

Após carregar, algo deve spawnar o jogador e desligar a tela de carregamento. Usualmente:

• spawnmanager faz em um servidor simples.
• O multicharacter e spawn selector de um framework o fazem em ESX e QBCore.

Verifique que esses recursos começam, na ordem certa, e que apenas um deles lida com spawning. Um conflito típico é um spawnmanager padrão auto-spawning o jogador enquanto um recurso de multicharacter também quer. Tenha certeza de que os recursos de base começam antes do framework, como em the right ensure order:

ensure oxmysql
ensure ox_lib
ensure es_extended        # or qb-core / qbx_core
ensure spawnmanager
ensure esx_multicharacter # or qb-multicharacter / qbx_core's own

Se um recurso de multicharacter trava, olhe no console do server para um erro de banco de dados dele: o carregamento de character lê o banco de dados, e uma falha SQL deixa o jogador esperando. Veja oxmysql connection error e SQL table doesn't exist.

#3. Um loadscreen customizado que nunca fecha

Server loadscreens são recursos declarados no seu manifest:

fx_version 'cerulean'
game 'gta5'

loadscreen 'html/index.html'
loadscreen_manual_shutdown 'yes'

files { 'html/**/*' }

Com loadscreen_manual_shutdown 'yes', FiveM não fecha o loadscreen sozinho. Um client script tem que fazer, chamando os shutdown natives uma vez que o jogador está pronto:

ShutdownLoadingScreen()
ShutdownLoadingScreenNui()

Se um recurso de loadscreen tem a opção manual shutdown e ninguém chama esses, a tela fica para sempre. Ou remova loadscreen_manual_shutdown, ou tenha certeza que seu spawn flow os chama. Teste parando o recurso de loadscreen e se juntando novamente.

Um loadscreen que está quebrado, que carrega um arquivo externo que é inalcançável, ou que toca um vídeo muito grande pode também bloquear ou desacelerar a tela. Mantenha-a leve e local.

#4. Streaming grande e downloads

Entrar faz download de todos os arquivos streamed que o jogador ainda não tem. Um server com muitos veículos grandes, mapas e pacotes de roupa pode levar minutos na primeira conexão, e a tela de carregamento mostra nada acontecendo se o download é lento. Sinais:

• O F8 ou tela de carregamento mostra downloads em progresso.
• Funciona para jogadores que retornam mas não para novos.
• O problema fica pior depois que você adiciona um pacote de assets.

Correções: reduza o tamanho e a contagem de assets streamed (veja oversized assets), hospede o server em uma conexão com largura de banda suficiente, e peça aos jogadores que esperem o primeiro download terminar.

#5. Problemas de game build ou versão de server

Se o server força um game build, um jogador em um build mais antigo ou diferente pode falhar ao entrar limpar. Verifique sv_enforceGameBuild em server.cfg contra o DLC que seus assets precisam. Veja sv_enforceGameBuild. Um artifact de server desatualizado também pode causar entradas estranhas: update your FiveM server artifacts.

#6. O framework não carrega o character

Jogadores spawnam, mas o framework nunca termina de carregar o jogador. No console do server procure por:

• um erro de banco de dados enquanto carrega o jogador ou character
• um erro de es_extended, qb-core ou qbx_core no evento player-loaded
• um script que faz hook daquele evento e lança, parando outros handlers

Se você vir um erro ali, conserte-o, e se junte novamente. Um inventory quebrado ou um job script quebrado também pode falhar dentro do player-loaded flow, então verifique os mais recentemente adicionados primeiro.

#Uma rotina de debug

1. Se junte e pressione F8. Anote cada erro.
2. Leia o console do server durante a entrada.
3. Pare o recurso mais recentemente alterado, se junte novamente.
4. Pare o recurso de loadscreen, se junte novamente.
5. Ainda preso para everyone: comece apenas com os recursos de base e adicione o resto de volta em grupos.

Dica: se você adiciona recursos em grupos de cinco ou dez, você encontra o ruim com poucos restarts em vez de testar 80 recursos um por um.

#Checklist