FiveM bloccato sulla schermata di caricamento: cause e come debuggare

I giocatori si connettono, la barra si riempie, e poi niente: la schermata di caricamento rimane su per sempre, o il gioco si blocca su uno schermo nero. Questa guida esamina le cause nell'ordine più rapido per escluderle, e mostra come usare F8 e la console del server per trovare quella che hai tu.

#Per primo: è tutti o un giocatore?

• Tutti sono bloccati. La causa è sul server: una risorsa, il framework, o un loadscreen.
• Un giocatore è bloccato. Guarda il client di quel giocatore: cache, una connessione lenta, mod, o una build di gioco vecchia. Inizia con pulire la cache FiveM.

Unisciti una volta tu stesso e premi F8. Questo funziona anche sulla schermata di caricamento. Leggi cosa è stampato lì, e tieni la console del server aperta dall'altro lato.

#1. Un errore di script sul client

F8 elenca gli errori del client. Qualsiasi riga come questa durante il caricamento è un indizio forte:

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

Uno script client che si blocca nel suo thread di inizio può lasciare il flusso di spawn non finito. Correggi lo script nominato nell'errore: le guide per lettura di un errore di script, ESX nil e QBCore nil coprono i comuni. Poi riavvia la risorsa e unisciti di nuovo.

Testa per eliminazione se nulla è stampato: ferma la risorsa più recentemente aggiunta o modificata, unisciti, e vedi se il caricamento finisce.

#2. Nessuno spawnea il giocatore

Dopo il caricamento, qualcosa deve spawnare il giocatore e spegnere la schermata di caricamento. Solitamente:

• spawnmanager lo fa in un server semplice.
• Il multicharacter e spawn selector di un framework lo fanno su ESX e QBCore.

Controlla che queste risorse si avvino, nell'ordine giusto, e che solo una di loro gestisca lo spawning. Un conflitto tipico è uno spawnmanager di default che auto-spawna il giocatore mentre una risorsa multicharacter vuole anche farlo. Assicurati che le risorse base si avviino prima del framework, come in l'ordine ensure giusto:

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 una risorsa multicharacter si blocca, guarda la console del server per un errore di database da essa: il caricamento del personaggio legge il database, e un fallimento SQL lascia il giocatore ad aspettare. Vedi errore di connessione oxmysql e la tabella SQL non esiste.

#3. Un loadscreen personalizzato che non si chiude mai

I loadscreen del server sono risorse dichiarate nel loro manifest:

fx_version 'cerulean'
game 'gta5'

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

files { 'html/**/*' }

Con loadscreen_manual_shutdown 'yes', FiveM non chiude il loadscreen da solo. Uno script client deve farlo, chiamando i nativi di spegnimento una volta che il giocatore è pronto:

ShutdownLoadingScreen()
ShutdownLoadingScreenNui()

Se una risorsa loadscreen ha l'opzione manual shutdown e nessuno chiama questi, lo schermo rimane su per sempre. O rimuovi loadscreen_manual_shutdown, o assicurati che il tuo flusso di spawn li chiami. Testa fermando la risorsa loadscreen e unendoti di nuovo.

Un loadscreen che è rotto, che carica un file esterno che non è raggiungibile, o che riproduce un video molto grande può anche bloccare o rallentare lo schermo. Mantienilo leggero e locale.

#4. Streaming grande e download

Unirsi scarica tutti i file in streaming che il giocatore non ha ancora. Un server con molti grandi veicoli, mappe e clothing pack può richiedere minuti alla prima connessione, e la schermata di caricamento non mostra nulla che accade se il download è lento. Segni:

• L'F8 o la schermata di caricamento mostra download in corso.
• Funziona per i giocatori che ritornano ma non per i nuovi.
• Il problema peggiora dopo che aggiungi un pack di asset.

Soluzioni: riduci la dimensione e il conteggio degli asset in streaming (vedi asset sovradimensionati), ospita il server su una connessione con abbastanza larghezza di banda, e chiedi ai giocatori di aspettare che il primo download finisca.

#5. Problemi di build del gioco o versione del server

Se il server forza una build del gioco, un giocatore su una build più vecchia o diversa potrebbe non riuscire a unirsi pulitamente. Controlla sv_enforceGameBuild in server.cfg contro il DLC che i tuoi asset richiedono. Vedi sv_enforceGameBuild. Un artefatto server obsoleto può anche causare unioni strane: aggiorna i tuoi artefatti FiveM.

#6. Il framework non carica il personaggio

I giocatori spawnano, ma il framework non finisce mai di caricare il giocatore. Nella console del server guarda:

• un errore di database durante il caricamento del giocatore o del personaggio
• un errore da es_extended, qb-core o qbx_core sull'evento player-loaded
• uno script che aggancia quell'evento e lancia, fermando altri handler

Se vedi un errore lì, correggilo, e unisciti di nuovo. Un inventario rotto o uno script di lavoro rotto possono anche fallire all'interno del flusso player-loaded, quindi controlla i più recentemente aggiunti per primo.

#Una routine di debug

1. Unisciti e premi F8. Nota ogni errore.
2. Leggi la console del server durante l'unione.
3. Ferma la risorsa più recentemente modificata, unisciti.
4. Ferma la risorsa loadscreen, unisciti.
5. Ancora bloccato per tutti: inizia solo con le risorse base e aggiungi il resto di nuovo in gruppi.

Suggerimento: se aggiungi risorse in gruppi di cinque o dieci, trovi quella cattiva con pochi riavvii invece di testare 80 risorse una per una.

#Checklist