Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Pagina HTML personalizzata per l'esportazione Web

Sebbene i modelli di esportazione Web forniscano una pagina HTML predefinita perfettamente in grado di avviare il progetto senza ulteriori personalizzazioni, potrebbe essere utile creare una pagina HTML personalizzata. Sebbene il gioco in sé non possa ancora essere facilmente controllato direttamente dall'esterno, una pagina di questo tipo consente di personalizzare il processo di inizializzazione del motore.

Alcuni casi d'uso in cui è utile personalizzare la pagina predefinita includono:

Caricare file da una cartella diversa da quella della pagina;
Caricare un file .zip invece di un file .pck come pacchetto principale;
Caricare il motore da una cartella diversa da quella del file pacchetto principale;
Aggiungere un pulsante "clicca per giocare" in modo che i giochi si possano avviare in modalità a schermo intero;
Caricare alcuni file in più prima dell'avvio del motore, rendendoli disponibili nel file system del progetto il prima possibile;
Passare argomenti personalizzati alla riga di comando, ad esempio -s per avviare uno script MainLoop.

La pagina HTML predefinita è disponibile nel repository di Godot Engine all'indirizzo /misc/dist/html/full-size.html, ma il seguente modello può servire da esempio molto più semplice:

<!DOCTYPE html>
<html>
    <head>
        <title>My Template</title>
        <meta charset="UTF-8">
    </head>
    <body>
        <canvas id="canvas"></canvas>
        <script src="$GODOT_URL"></script>
        <script>
            var engine = new Engine($GODOT_CONFIG);
            engine.startGame();
        </script>
    </body>
</html>

Configura

Come mostrato dall'esempio precedente, si tratta per lo più di un regolare documento HTML, con pochi segnaposto da sostituire durante l'esportazione, un elemento html <canvas> e un po' di semplice codice JavaScript che richiama la classe Engine().

Gli unici segnaposto richiesti sono:

$GODOT_URL: il nome del file JavaScript principale, che fornisce la classe Engine() necessaria per avviare il motore e che deve essere inclusa nell'HTML come elemento <script>. Il nome viene generato dal Percorso di esportazione durante il processo di esportazione.
$GODOT_CONFIG: Un oggetto JavaScript, che contiene le opzioni di esportazione e può essere successivamente sovrascritto. Consulta EngineConfig per l'elenco completo di sovrascritture.

I seguenti segnaposto facoltativi abiliteranno alcune funzionalità in più nel modello HTML personalizzato.

$GODOT_PROJECT_NAME: Il nome del progetto come definito nell'impostazione del Nome Impostazioni del progetto > Applicazione > Configurazione. È una buona idea usarlo come <title> nel tuo template.
$GODOT_HEAD_INCLUDE: una stringa personalizzata da includere nel documento HTML subito prima della fine del tag <head>. È personalizzabile nelle opzioni di esportazione nella sezione Html / Head Include. Sebbene c'è il pieno controllo sulla pagina HTML creata, questa variabile può servire per configurare parti dell'elemento HTML head dall'editor Godot, ad esempio per diverse preimpostazioni di esportazione Web.
$GODOT_SPLASH: il percorso all'immagine utilizzata come schermata di avvio come definito nell'impostazione Image in Impostazioni del progetto > Applicazione > Schermata di avvio.
$GODOT_SPLASH_COLOR Il colore di sfondo della schermata di avvio come definito nell'impostazione BG Color in Impostazioni del progetto > Applicazione > Schermata di avvio, convertito in un codice colore esadecimale.
$GODOT_SPLASH_CLASSES Questo segnaposto fornisce una stringa di nomi di impostazioni e relativi valori, che influiscono sulla schermata di avvio. Questa stringa è pensata all'uso come un insieme di nomi di classi CSS, che consentono di definire lo stile dell'immagine iniziale in base alle impostazioni del progetto. Sono fornite le seguenti impostazioni da Impostazioni del progetto > Applicazione > Schermata di avvio, rappresentate dai nomi di classe mostrati di seguito, a seconda del valore booleano dell'impostazione:
- Mostra immagine: show-image--true, show-image--false
- Stretch Mode: fullsize--true (if not Disabled), fullsize--false
- Usa filtro: use-filter--true, use-filter--false

Quando la pagina personalizzata è pronta, è possibile selezionarla nelle opzioni di esportazione nella sezione Html / Shell HTML personalizzata.

../../../_images/html5_export_options.png

Avvio del progetto

Per poter avviare il gioco, è necessario scrivere uno script che inizializzi il motore, ovvero il codice di controllo. Questa procedura si compone di tre passaggi, ma come mostrato qui, la maggioranza di essi si può saltare a seconda di quanta personalizzazione è richiesta.

Consultare il riferimento alla classe shell HTML5 per l'elenco completo dei metodi e delle opzioni disponibili.

Per prima cosa, il motore deve essere caricato, poi inizializzato e finalmente il progetto può essere avviato. È possibile eseguire ognuno di questi passaggi manualmente e con un ottimo controllo. Tuttavia, nel caso più semplice, tutto ciò che basta fare è creare un'istanza della classe Engine() con la configurazione esportata e poi chiamare il metodo engine.startGame, eventualmente sovrascrivendo i parametri di EngineConfig.

const engine = new Engine($GODOT_CONFIG);
engine.startGame({
    /* optional override configuration, eg. */
    // unloadAfterInit: false,
    // canvasResizePolicy: 0,
    // ...
});

Questo frammento di codice carica e inizializza automaticamente il motore prima di avviare il gioco. Utilizza la configurazione specificata per caricare il motore. Il metodo engine.startGame è asincrono e restituisce una Promise. Questo consente al codice di controllo di verificare se il gioco è stato caricato correttamente senza bloccare l'esecuzione o basarsi sul polling.

Nel caso in cui il progetto richieda un controllo speciale sugli argomenti di avvio e sui file di dipendenza, è possibile utilizzare il metodo engine.start. Si noti che questo metodo non precarica automaticamente il file pck, quindi probabilmente sarà necessario precaricarlo (insieme a qualsiasi altro file in più) manualmente tramite il metodo engine.preloadFile.

Facoltativamente, è possibile anche usare manualmente engine.init per effettuare azioni specifiche dopo l'inizializzazione del modulo, ma prima dell'avvio del motore.

Questo processo è un po' più complesso, ma dà il pieno controllo sul processo di avvio del motore.

const myWasm = 'mygame.wasm';
const myPck = 'mygame.pck';
const engine = new Engine();
Promise.all([
    // Load and init the engine
    engine.init(myWasm),
    // And the pck concurrently
    engine.preloadFile(myPck),
]).then(() => {
    // Now start the engine.
    return engine.start({ args: ['--main-pack', myPck] });
}).then(() => {
    console.log('Engine has started!');
});

Per caricare manualmente il motore, è necessario chiamare il metodo statico Engine.load(). Poiché questo metodo è statico, è possibile generare più istanze del motore se condividono lo stesso wasm.

Nota

Normalmente non è possibile generare più di un'istanza, poiché il motore viene scaricato immediatamente dopo l'inizializzazione. Per evitare che ciò accada, utilizzare l'opzione di sovrascrittura unloadAfterInit. È comunque possibile scaricare manualmente il motore in seguito chiamando il metodo statico Engine.unload(). Scaricare il motore libera memoria nel browser, scaricando i file non più necessari una volta inizializzata l'istanza.

Personalizzare il comportamento

Nell'ambiente Web si possono utilizzare vari metodi per garantire che il gioco funzioni come previsto.

Se si desidera una versione specifica di WebGL, o semplicemente verificare se WebGL è disponibile, è possibile chiamare il metodo Engine.isWebGLAvailable(). Accetta facoltativamente un argomento che consente di testare una specifica versione principale di WebGL.

Poiché il file eseguibile reale non esiste nell'ambiente Web, il motore memorizza solo un nome file virtuale, formato dal nome base dei file del motore caricati. Questo valore influenza il risultato del metodo OS.get_executable_path() e definisce il nome del pacchetto principale avviato automaticamente. È possibile usare l'opzione di sovrascrittura executable per sovrascrivere questo valore.

Personalizzare la presentazione

Sono disponibili diverse opzioni di configurazione per personalizzare ulteriormente l'aspetto e il comportamento del gioco sulla pagina.

Per impostazione predefinita, il primo elemento canvas è utilizzato nella pagina per il rendering. Per utilizzare un elemento canvas diverso, è possibile utilizzare l'opzione di sovrascrittura canvas. Richiede un riferimento all'elemento DOM stesso.

const canvasElement = document.querySelector("#my-canvas-element");
engine.startGame({ canvas: canvasElement });

Il modo in cui il motore ridimensiona il canvas si può configurare tramite l'opzione di sovrascrittura canvasResizePolicy.

Se il caricamento del gioco richiede un po' di tempo, potrebbe essere utile visualizzare un'interfaccia utente di caricamento personalizzata che ne mostra il progresso. Ciò si può ottenere con l'opzione di callback onProgress, che consente di impostare una funzione di callback che verrà chiamata regolarmente man mano che il motore carica nuovi byte.

function printProgress(current, total) {
    console.log("Loaded " + current + " of " + total + " bytes");
}
engine.startGame({ onProgress: printProgress });

Tenere presente che in alcuni casi total può essere 0. Ciò significa che non si può calcolare.

Se il gioco supporta più lingue, l'opzione di sovrascrittura locale può servire per forzare una lingua specifica, a condizione che si abbia una stringa di codice lingua valida. Potrebbe essere buono utilizzare una logica lato server per determinare quali lingue un utente potrebbe preferire. In questo modo, il codice lingua si può ricavare dall'intestazione HTTP Accept-Language o determinare da un servizio GeoIP.

Debugging

Per effettuare il debug dei progetti esportati, può essere utile leggere i flussi dall'output standard e di errore generati dal motore. Questo è simile all'output mostrato nella finestra della console dell'editor. Come predefinito, sono utilizzati i file standard console.log e console.warn rispettivamente per i flussi di output e di errore. È possibile personalizzare questo comportamento impostando le proprie funzioni per la gestione dei messaggi.

Utilizzare l'opzione di sovrascrittura onPrint per impostare una funzione di callback per il flusso di output e l'opzione di sovrascrittura onPrintError per impostare una funzione di callback per il flusso di errore.

function print(text) {
    console.log(text);
}
function printError(text) {
    console.warn(text);
}
engine.startGame({ onPrint: print, onPrintError: printError });

Quando si gestisce l'output del motore, tenere presente che potrebbe non essere opportuno stamparlo nel prodotto finale.