Schermata di caricamento personalizzata per FiveM: loadscreen, fxmanifest e shutdown

Una schermata di caricamento è una piccola pagina web che i giocatori vedono mentre i file del server vengono scaricati. È una risorsa normale con un manifest e un file HTML. Questa guida copre i file, il manifest, chiudere la schermata da solo e mantenerla leggera.

#La risorsa

Crea una cartella con l'HTML e i suoi asset:

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

#Il 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',
}

Due cose sono importanti qui:

• loadscreen 'index.html' nomina la pagina che FiveM mostra.
• Ogni file che la pagina usa, incluso l'HTML stesso, deve essere in files. Un file che non è elencato restituisce un 404 e la schermata è vuota o rotta in quella parte. Un pattern come 'img/*' è consentito per elencare un'intera cartella.

Aggiungilo a server.cfg:

ensure my_loadscreen

#Un index.html minimo

<!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>

Usa percorsi relativi, come sopra. La pagina viene eseguita nel browser del gioco, quindi puoi usare HTML, CSS e JavaScript normali. Per una barra di avanzamento, la pagina riceve messaggi mentre il gioco carica:

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

#Solo una schermata di caricamento

FiveM mostra una singola schermata di caricamento. Se due risorse dichiarano un loadscreen, solo una viene usata, e quale può cambiare tra gli avvii. Quindi:

• Rimuovi o ferma qualsiasi altra risorsa di schermata di caricamento da server.cfg.
• Quando vuoi testare una nuova, commenta la vecchia riga invece di avviare entrambe.

#Chiudere la schermata da solo

Per impostazione predefinita, FiveM chiude la schermata di caricamento quando la sessione di gioco è pronta. Uno script multicarattere o spawn spesso ha bisogno che la schermata rimanga aperta più a lungo, per nascondere il mondo fino a quando il personaggio è scelto. Per questo, il manifest disattiva la chiusura automatica:

loadscreen_manual_shutdown 'yes'

Quindi uno script client deve chiuderla:

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

    ShutdownLoadingScreenNui()
end)

ShutdownLoadingScreenNui chiude la pagina NUI della tua schermata di caricamento. Uno script che gestisce lo spawn, come uno script multicarattere, spesso lo chiama, o i nativi dietro di esso, per te. Controlla prima quello script, quindi aggiungi la tua chiamata solo se nient'altro lo fa.

Attenzione: se imposti loadscreen_manual_shutdown 'yes' e niente chiama lo shutdown, i giocatori rimangono sulla schermata di caricamento per sempre. Se succede, vedi giocatori bloccati sulla schermata di caricamento.

#Musica e video: mantienili leggeri

Tutto in files viene scaricato da ogni giocatore. Una schermata di caricamento pesante rende l'attesa più lunga, il che è l'opposto dell'obiettivo.

• Musica: usa .ogg o .mp3, pochi minuti al massimo, e un bitrate moderato. Una traccia di 3 MB va bene, una traccia di 60 MB no. Aggiungi un pulsante di disattivazione audio, e imposta il volume basso nel codice, poiché un avvio forte infastidisce i giocatori.
• Video: breve e in loop, in .webm o .mp4, risoluzione piccola e bitrate basso. Ancora meglio, usa una buona immagine di sfondo, che è molto più piccola.
• Immagini: comprimile. Uno sfondo di 200 a 400 KB sembra lo stesso di uno di 8 MB sulla maggior parte degli schermi.
• Font e librerie: mettile nella risorsa. Caricarle da Internet al join rende la pagina più lenta, e fallisce se l'host è giù.

Poiché i giocatori scaricano questi file per ogni nuova versione, non cambiarli spesso. Quando un giocatore vede ancora la vecchia pagina dopo un aggiornamento, chiedgli di cancellare la cache di FiveM.

#Opzionale: un cursore

Se vuoi che il giocatore clicchi sulla schermata di caricamento, per regole o un menu, aggiungi il seguente al manifest:

loadscreen_cursor 'yes'

#Problemi comuni

• Schermata vuota, nessuno stile. Un file è mancante da files, o un percorso nell'HTML è sbagliato.
• La schermata predefinita appare. La risorsa non è avviata, o la riga loadscreen è mancante.
• Non si chiude mai. Hai impostato loadscreen_manual_shutdown 'yes' e nessuno script chiama ShutdownLoadingScreenNui().
• La musica non si riproduce. Controlla il percorso del file e il formato. Testa la pagina in un browser normale prima.

#Checklist