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...
Esportazione per il Web
Vedi anche
Questa pagina descrive come esportare un progetto Godot per HTML5. Se si desidera invece compilare i binari dell'editor o dei modelli di esportazione dal codice sorgente, consultare Compilare per il Web.
L'esportazione in HTML5 consente di pubblicare i giochi realizzati con Godot Engine sul browser. Ciò richiede il supporto per WebAssembly e WebGL 2.0 nel browser dell'utente.
Attenzione
Al momento non è possibile esportare i progetti scritti in C# sul web. Consultare questo post sul blog per ulteriori informazioni.
Per usare C# su piattaforme web, usare invece Godot 3.
Suggerimento
Utilizzare la console per sviluppatori integrata nel browser, solitamente aperta con F12 o Ctrl + Shift + I (Cmd + Option + I su macOS), per visualizzare le informazioni di debug come errori JavaScript, del motore e WebGL.
Se la scorciatoia non funziona, è perché Godot sta catturando l'input. È comunque possibile aprire la console per sviluppatori accedendo al menu del browser.
Nota
A causa di problemi di sicurezza con SharedArrayBuffer dovuti a vari exploit, l'uso di più thread per la piattaforma Web ha diversi svantaggi, tra cui la necessità di intestazioni specifiche lato server e un isolamento completo tra origini (ovvero nessuna pubblicità, né integrazioni di terze parti sul sito Web che ospita il gioco).
Da Godot 4.3 in poi, è supportata l'esportazione del gioco su un singolo thread, risolvendo così questo problema. Sebbene abbia le proprie pecche (non può utilizzare i thread e non è performante come l'esportazione su più thread), richiede meno preparazione per l'installazione. È inoltre più compatibile con piattaforme come itch.io o publisher su web come Poki o CrazyGames. L'esportazione a singolo thread funziona molto bene anche su macOS e iOS, dove le esportazioni su più thread hanno sempre avuto problemi di compatibilità.
Per questi motivi, è il metodo preferito e ormai predefinito per esportare i propri giochi sul Web.
Per ulteriori informazioni, consulta questo post del blog sull'esportazione Web a thread singolo.
Vedi anche
Consulta l'elenco dei problemi aperti su GitHub riguardo l'esportazione web per un elenco dei bug noti.
Nome del file esportato
Consigliamo agli utenti di esportare i propri progetti Web con index.html come nome file. index.html è solitamente il file predefinito caricato dai server Web quando si accede alla cartella principale, solitamente nascondendo il nome di tale file.
Attenzione
L'esportazione Web di Godot 4 prevede che alcuni file abbiano lo stesso nome impostato nell'esportazione iniziale. Potrebbero verificarsi problemi se alcuni file esportati sono poi rinominati, incluso il file HTML principale.
Versione di WebGL
Godot 4 può puntare solo a WebGL 2.0 (utilizzando il metodo di rendering Compatibilità). Forward+/Mobile non sono supportati sulla piattaforma web, poiché questi metodi di rendering sono progettati per le API grafiche moderne di basso livello. Attualmente Godot non supporta WebGPU, che è un prerequisito per consentire l'esecuzione di Forward+/Mobile sulla piattaforma web.
Consulta Can I use WebGL 2.0 per un elenco delle versioni dei browser che supportano WebGL 2.0. Tieni presente che Safari ha diversi problemi con il supporto di WebGL 2.0 che altri browser non hanno, quindi consigliamo di utilizzare un browser basato su Chromium o Firefox, se possibile.
Considerazioni per mobile
Un'esportazione Web si può eseguire su piattaforme mobili con alcune limitazioni. Sebbene le esportazioni native per Android e iOS offrano sempre prestazioni nettamente superiori, l'esportazione Web consente agli utenti di eseguire il progetto senza dover passare attraverso gli app store.
Ricorda che le prestazioni di CPU e GPU sono fondamentali quando si esegue un'applicazione sui dispositivi mobili. Questo è ancora più vero quando si esegue un progetto esportato per il Web (poiché è WebAssembly anziché codice nativo). Consulta la sezione Prestazioni della documentazione per consigli su come ottimizzare il tuo progetto. Se il tuo progetto è eseguito su piattaforme diverse dal Web, puoi utilizzare Tag di funzionalità per applicare impostazioni orientate alle prestazioni di fascia bassa quando il progetto esportato è eseguito per il Web.
Per velocizzare i tempi di caricamento sui dispositivi mobili, è consigliabile anche compilare un modello di esportazione ottimizzato con le funzionalità non utilizzate disabilitate. A seconda delle funzionalità utilizzate dal progetto, questo può ridurre significativamente le dimensioni del payload WebAssembly, rendendolo più veloce da scaricare e inizializzare (anche quando memorizzato nella cache).
Riproduzione audio
A partire da Godot 4.3, la riproduzione audio avviene tramite l'API Web Audio sulla piattaforma web. La modalità di riproduzione Sample consente una bassa latenza anche quando il progetto viene esportato senza supporto per più thread, ma ha diverse limitazioni:
Gli AudioEffect (effetti audio) non sono supportati.
Gli effetti riverbero e Doppler non sono supportati.
La generazione procedurale di audio non è supportata.
L'audio posizionale potrebbe non funzionare sempre correttamente, a seconda delle proprietà del nodo.
Per utilizzare il sistema di riproduzione audio di Godot sulla piattaforma web, è possibile cambiare la modalità di riproduzione predefinita tramite l'impostazione del progetto Audio > General > Default Playback Type.web oppure cambiare la proprietà Playback Type su Stream per un nodo AudioStreamPlayer, AudioStreamPlayer2D o AudioStreamPlayer3D. Ciò porta a un aumento della latenza (soprattutto quando il supporto per più thread è disabilitato), ma permette di far funzionare tutte le funzionalità audio di Godot.
Opzioni di esportazione
Se è disponibile un modello di esportazione web eseguibile, nell'editor compare un pulsante tra i pulsanti per arrestare la scena e eseguire la scena modificata, per aprire rapidamente il gioco nel browser predefinito e testarlo.
Se il tuo progetto utilizza GDExtension, è necessario abilitare il supporto per le estensioni.
Se si intende utilizzare la compressione VRAM, assicurarsi che la Compressione di texture nella VRAM sia abilitata per le piattaforme di destinazione (abilitare entrambe le opzioni, Per desktop e Per dispositivi mobili, produrrà un'esportazione più grande, ma più compatibile).
Se viene specificato il percorso di un file Shell HTML personalizzato, questo sarà utilizzato al posto della pagina HTML predefinita. Consultare Pagina HTML personalizzata per l'esportazione Web.
Includi in head viene aggiunto all'elemento <head> della pagina HTML generata. Ciò consente, ad esempio, di caricare font web e API JavaScript di terze parti, includere CSS o eseguire codice JavaScript.
Le dimensioni della finestra si adatteranno automaticamente alle dimensioni della finestra del browser, come predefinito. Se si desidera utilizzare una dimensione fissa, indipendente dalle dimensioni della finestra del browser, modificare Regole di ridimensionamento canvas in None. Ciò consente di controllare le dimensioni della finestra con codice JavaScript personalizzato nello shell HTML. È anche possibile impostarlo su Project per un comportamento più simile a un'esportazione nativa, secondo le impostazioni del progetto.
Importante
Ogni progetto deve generare il proprio file HTML. Durante l'esportazione, diversi segnaposto di testo vengono sostituiti nel file HTML generato seguendo le opzioni di esportazione selezionate. Qualsiasi modifica apportata direttamente a tale file HTML andrà persa nelle esportazioni successive. Per personalizzare il file generato, utilizzare l'opzione Shell HTML personalizzato.
Supporto per thread ed estensioni
Se Supporto di thread è abilitato, il progetto esportato sarà in grado di utilizzare il multithreading per migliorare le prestazioni. Ciò consente anche di riprodurre audio a bassa latenza quando il tipo di riproduzione è impostato su Stream (anziché sul valore predefinito Sample utilizzato nelle esportazioni web). Abilitare questa funzionalità richiede l'uso di intestazioni di isolamento cross-origin, descritte nella sezione Distribuire i file seguente.
Se Supporto di estensioni è abilitato, sarà possibile caricare le GDExtension. Si noti che le GDExtension devono comunque essere compilate specificamente per funzionare sulla piattaforma web. Come per il supporto per più thread, abilitare questa funzionalità richiede l'uso di intestazioni di isolamento cross-origin.
Esportare come Applicazione Web Progressiva (PWA)
Se Applicazione Web Progressiva > Abilita è abilitata, avrà diversi effetti:
Configura icone ad alta risoluzione, una modalità di visualizzazione e l'orientamento dello schermo. Queste impostazioni sono configurate alla fine della sezione Applicazione Web Progressiva nelle opzioni di esportazione. Tali opzioni sono utilizzate se l'utente aggiunge il progetto alla schermata iniziale del proprio dispositivo, una pratica comune sulle piattaforme mobili. Questa funzionalità è supportata anche su piattaforme desktop, seppur in modo più limitato.
Consente di caricare il progetto anche in assenza di connessione a Internet, purché sia stato caricato almeno una volta in precedenza. Ciò è possibile grazie al service worker che viene installato al primo caricamento del progetto nel browser dell'utente. Questo service worker fornisce un'alternativa di riserva locale in assenza di connessione a Internet.
Si noti che i browser web possono decidere di eliminare i dati memorizzati nella cache se lo spazio su disco dell'utente è insufficiente o se l'utente non ha aperto il progetto da un po' di tempo. Per garantire che i dati siano memorizzati nella cache per un periodo più lungo, l'utente può aggiungere la pagina ai segnalibri o, idealmente, alla schermata iniziale del proprio dispositivo.
Se i dati offline non sono disponibili perché sono stati rimossi dalla cache, è possibile configurare una Pagina offline che sarà visualizzata in questo caso. La pagina deve essere in formato HTML e sarà salvata sul computer del client al primo caricamento del progetto.
Assicurarsi che le intestazioni di isolamento tra origini siano sempre presenti, anche se il server web non è stato configurato per inviarle. Ciò consente alle esportazioni con più thread abilitati di funzionare se ospitate su qualsiasi sito web, anche se non è possibile controllare le intestazioni inviate.
È possibile disabilitare questo comportamento deselezionando Abilita intestazioni di isolamento tra origini nella sezione Progressive Web App.
Limitazioni
Per motivi di sicurezza e privacy, molte funzionalità che funzionano senza problemi sulle piattaforme native sono più complesse sulla piattaforma web. Di seguito è riportato un elenco di limitazioni da tenere in mente quando si porta un gioco di Godot sul web.
Importante
I produttori di browser stanno rendendo sempre più funzionalità disponibili solo in contesti sicuri, il che significa che tali funzionalità saranno disponibili solo se la pagina web viene servita tramite una connessione HTTPS sicura (localhost è solitamente esente da tale requisito).
Elaborazione nello sfondo
Il progetto verrà messo in pausa dal browser quando la scheda non è più quella attiva nel browser dell'utente. Ciò significa che funzioni come _process() e _physics_process() non saranno più eseguite finché l'utente non riattiverà la scheda (ritornandoci su). Questo potrebbe far disconnettere i giochi in rete se l'utente cambia scheda per un periodo prolungato.
Questa limitazione non si applica alle finestre del browser non in primo piano. Pertanto, dal lato utente, è possibile aggirarla eseguendo il progetto in una finestra separata anziché in una scheda separata.
Schermo intero e cattura del mouse
I browser non consentono di passare a schermo intero arbitrariamente. Lo stesso vale per catturare il cursore. Queste azioni devono invece avvenire in risposta a un evento di input JavaScript. In Godot, ciò significa passare a schermo intero all'interno di un callback per l'evento di pressione di un input, come _input o _unhandled_input. Non è sufficiente interrogare il singleton Input, l'evento interessato deve essere attualmente attivo.
Per lo stesso motivo, l'impostazione del progetto per lo schermo intero non funziona, a meno che il motore non sia avviato all'interno di un gestore valido di eventi di input. Ciò richiede la personalizzazione della pagina HTML.
Audio
Alcuni browser limitano la riproduzione automatica dell'audio sui siti web. Il modo più facile per aggirare questa limitazione è chiedere al giocatore di cliccare, toccare o premere un tasto/pulsante per abilitare l'audio, ad esempio quando appare una schermata iniziale all'avvio del gioco.
Vedi anche
Google offre ulteriori informazioni sulla propria policy relativa alla riproduzione automatica di audio sul web.
Il team Safari di Apple ha inoltre pubblicato ulteriori informazioni sulle modifiche alla policy di riproduzione automatica per macOS.
Avvertimento
L'accesso al microfono richiede un contesto sicuro.
Avvertimento
A partire da Godot 4.3, come predefinito, le esportazioni Web utilizzeranno campioni (sample) anziché flussi (stream) per riprodurre l'audio.
Ciò è dovuto al modo in cui i browser preferiscono riprodurre l'audio, nonché alla scarsa potenza di elaborazione disponibile quando si esportano giochi per il Web con l'opzione di esportazione Usa i thread disattivata.
Si prega di notare che gli effetti audio non sono ancora implementati per i campioni.
Networking
Il networking di basso livello non è implementato a causa della mancanza di supporto nei browser.
Attualmente sono supportati solo i client HTTP, le richieste HTTP, WebSocket (client) e WebRTC.
Le classi HTTP inoltre hanno diverse restrizioni sulla piattaforma HTML5:
Non è possibile accedere o modificare lo
StreamPeerLa modalità thread/bloccante non è disponibile
Non è possibile procedere più di una volta per frame, quindi il polling in un ciclo si bloccherà
Niente risposte frammentate
La verifica dell'host non può essere disabilitata
Soggetto alla politica sulla stessa origine
Appunti
La sincronizzazione degli appunti tra il motore e il sistema operativo richiede un browser che supporti la Clipboard API; inoltre, a causa della natura asincrona dell'API, l'accesso potrebbe non essere affidabile se effettuato tramite GDScript.
Avvertimento
Richiede un contesto sicuro.
Gamepad
I gamepad non saranno rilevati finché non sarà premuto uno dei loro pulsanti. I gamepad potrebbero avere una mappatura errata a seconda della combinazione di browser/sistema operativo/gamepad. Purtroppo, Gamepad API non fornisce un metodo affidabile per rilevare le informazioni necessarie per riassegnarli in base a modello/fornitore/OS, per motivi di privacy.
Avvertimento
Richiede un contesto sicuro.
Distribuire i file
L'esportazione per il web genera diversi file da servire da un server web, inclusa una pagina HTML predefinita per la presentazione. È possibile utilizzare un file HTML personalizzato, consultare Pagina HTML personalizzata per l'esportazione Web.
Avvertimento
Solo quando si esporta con Usa i thread, per garantire una bassa latenza audio e la possibilità di utilizzare Thread nelle esportazioni web, le esportazioni web di Godot 4 utilizzano SharedArrayBuffer. Ciò richiede un contesto sicuro, e richiede anche che le seguenti intestazioni CORS siano impostate quando si servono i file:
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
Se non si ha il controllo del server web o non si riesce ad aggiungere intestazioni di risposta, selezionare Progressive Web App > Abilita nelle opzioni di esportazione. Facendo così si applica una soluzione alternativa basata su un service worker che consente di eseguire il progetto simulando la presenza di queste intestazioni di risposta. In questo caso, è comunque necessario un contesto sicuro.
Se il client non riceve le intestazioni di risposta richieste o non è applicata la soluzione alternativa basata su un service worker, il progetto non verrà eseguito.
Il file .html generato può servire da DirectoryIndex nei server Apache e si può rinominare, ad esempio, index.html in qualsiasi momento. Il suo nome non è mai utilizzato normalmente.
La pagina HTML mostra il gioco alle massime dimensioni all'interno della finestra del browser. In questo modo, può essere inserito in un <iframe> con le stesse dimensioni del gioco, come avviene comunemente sulla maggior parte dei siti per i giochi web.
Gli altri file esportati sono serviti così come sono, accanto al file .html, con i nomi invariati. Il file .wasm è un modulo WebAssembly binario che implementa il motore. Il file .pck è il pacchetto principale di Godot contenente il gioco. Il file .js contiene il codice di avvio e è utilizzato dal file .html per accedere al motore. Il file .png contiene l'immagine di avvio.
Il file .pck è binario, solitamente fornito con il tipo MIME application/octet-stream. Il file .wasm è fornito come application/wasm.
Avvertimento
La distribuzione del modulo WebAssembly (.wasm) con un tipo MIME diverso da application/wasm può impedire alcune ottimizzazioni all'avvio.
Si consiglia di distribuire i file con compressione lato server, in particolare per i file .pck e .wasm, che solitamente hanno grandi dimensioni. Il modulo WebAssembly si comprime particolarmente bene, riducendo le dimensioni originali a circa un quarto con la compressione gzip. Si consiglia di utilizzare la precompressione Brotli, se supportata dal server web, per un ulteriore risparmio di spazio sui file.
Host che forniscono compressione al volo: GitHub Pages (gzip)
Host che non forniscono compressione al volo: itch.io, GitLab Pages (supporta la precompressione gzip manuale)
Suggerimento
Il repository di Godot include uno script Python per ospitare un server web locale. Questo script è pensato per testare l'editor web, ma si può utilizzare anche per testare i progetti esportati.
Salvare lo script collegato in un file con il nome serve.py, spostare questo file nella cartella contenente index.html del progetto esportato, quindi eseguire il seguente comando in un prompt dei comandi all'interno della stessa cartella:
# You may need to replace `python` with `python3` on some platforms.
python serve.py --root .
Su Windows, è possibile aprire un prompt dei comandi nella cartella attuale tenendo premuto Shift e facendo clic destro su uno spazio vuoto in Esplora risorse, poi scegliendo Apri finestra PowerShell qui.
Ciò servirà il contenuto della cartella attuale e aprirà automaticamente il browser Web predefinito.
Si noti che per i casi d'uso in produzione, non si dovrebbe usare questo server web basato su Python. È invece consigliabile usare un server web consolidato come Apache o nginx.
Interaggire con il browser e JavaScript
Consultare la pagina dedicata su come interagire con JavaScript e accedere ad alcune funzionalità esclusive del browser Web.
Variabili d'ambiente
È possibile utilizzare le seguenti variabili d'ambiente per impostare le opzioni di esportazione al di fuori dell'editor. Durante il processo di esportazione, queste variabili sovrascrivono i valori impostati nel menu di esportazione.
Opzioni di esportazione |
Variabile d'ambiente |
|---|---|
Crittografia / Chiave crittografica |
|
Risoluzione dei problemi
Eseguire l'esportazione in locale mostra invece un altro progetto
Se si utilizza la distribuzione con un clic in più progetti, si potrebbe notare che è visualizzato uno dei progetti distribuiti in precedenza anziché il progetto su cui stai lavorando attualmente. Ciò è dovuto alla cache del service worker, che attualmente non dispone di un meccanismo di cache busting automatico.
Come soluzione alternativa, è possibile rimuovere manualmente il service worker attuale in modo che la cache venga ripristinata. Ciò consente anche di registrare un nuovo service worker. Nei browser basati su Chromium, aprire gli Strumenti per sviluppatori premendo F12 o Ctrl + Shift + I (Cmd + Option + I su macOS), poi cliccare sulla scheda Applicazione in DevTools (potrebbe essere nascosta dietro un'icona a forma di chevron se il riquadro di devtools è stretto). Si può spuntare e ricaricare la pagina, oppure cliccare su accanto al service worker attualmente registrato, poi ricaricare la pagina.
Annullamento della registrazione del service worker nei DevTools dei browser basati su Chromium
La procedura è simile in Firefox. Aprire gli strumenti per sviluppatori premendo F12 o Ctrl + Shift + I (Cmd + Option + I su macOS), cliccare sulla scheda Applicazione in DevTools (potrebbe essere nascosta dietro un'icona a forma di chevron se il riquadro di devtools è stretto). Cliccare su accanto al service worker attualmente registrato, poi ricaricare la pagina.
Rimozione della registrazione del service worker nei DevTools di Firefox
Opzioni di esportazione
È possibile trovare un elenco completo delle opzioni di esportazione disponibili nel riferimento alla classe EditorExportPlatformWeb.