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 <https://poki.com/>__ 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.
Export file name
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
Since Godot 4.3, audio playback is done using the Web Audio API on the web platform. This Sample playback mode allows for low latency even when the project is exported without thread support, but it has several limitations:
Gli AudioEffect (effetti audio) non sono supportati.
Reverberation and doppler effects are not supported.
Procedural audio generation is not supported.
L'audio posizionale potrebbe non funzionare sempre correttamente, a seconda delle proprietà del nodo.
To use Godot's own audio playback system on the web platform, you can change the default playback mode using the Audio > General > Default Playback Type.web project setting, or change the Playback Type property to Stream on an AudioStreamPlayer, AudioStreamPlayer2D or AudioStreamPlayer3D node. This leads to increased latency (especially when thread support is disabled), but it allows the full suite of Godot's audio features to work.
Opzioni di esportazione
If a runnable web export template is available, a button appears between the Stop scene and Play edited Scene buttons in the editor to quickly open the game in the default browser for testing.
If your project uses GDExtension, Extension Support needs to be enabled.
If you plan to use VRAM compression make sure that VRAM Texture Compression is enabled for the targeted platforms (enabling both For Desktop and For Mobile will result in a bigger, but more compatible export).
If a path to a Custom HTML shell file is given, it will be used instead of the default HTML page. See Pagina HTML personalizzata per l'esportazione Web.
Head Include is appended into the <head> element of the generated
HTML page. This allows to, for example, load webfonts and third-party
JavaScript APIs, include CSS, or run JavaScript code.
The window size will automatically match the browser window size by default. If you want to use a fixed size instead regardless of the browser window size, change Canvas Resize Policy to None. This allows controlling the window size with custom JavaScript code in the HTML shell. You can also set it to Project to make it behave closer to a native export, according to the project settings.
Importante
Each project must generate their own HTML file. On export, several text placeholders are replaced in the generated HTML file specifically for the given export options. Any direct modifications to that HTML file will be lost in future exports. To customize the generated file, use the Custom HTML shell option.
Supporto per thread ed estensioni
If Thread Support is enabled, the exported project will be able to make use of multithreading to improve performance. This also allows for low-latency audio playback when the playback type is set to Stream (instead of the default Sample that is used in web exports). Enabling this feature requires the use of cross-origin isolation headers, which are described in the Distribuire i file section below.
If Extensions Support is enabled, GDExtensions will be able to be loaded. Note that GDExtensions still need to be specifically compiled for the web platform to work. Like thread support, enabling this feature requires the use of cross-origin isolation headers.
Exporting as a Progressive Web App (PWA)
If Progressive Web App > Enable is enabled, it will have several effects:
Configure high-resolution icons, a display mode and screen orientation. These are configured at the end of the Progressive Web App section in the export options. These options are used if the user adds the project to their device's homescreen, which is common on mobile platforms. This is also supported on desktop platforms, albeit in a more limited capacity.
Allow the project to be loaded without an Internet connection if it has been loaded at least once beforehand. This works thanks to the service worker that is installed when the project is first loaded in the user's browser. This service worker provides a local fallback when no Internet connection is available.
Note that web browsers can choose to evict the cached data if the user runs low on disk space, or if the user hasn't opened the project for a while. To ensure data is cached for a longer duration, the user can bookmark the page, or ideally add it to their device's home screen.
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
Browser vendors are making more and more functionalities only available in secure contexts, this means that such features are only be available if the web page is served via a secure HTTPS connection (localhost is usually exempt from such requirement).
Elaborazione nello sfondo
The project will be paused by the browser when the tab is no longer the active
tab in the user's browser. This means functions such as _process() and
_physics_process() will no longer run until the tab is made active again by
the user (by switching back to the tab). This can cause networked games to
disconnect if the user switches tabs for a long duration.
This limitation does not apply to unfocused browser windows. Therefore, on the user's side, this can be worked around by running the project in a separate window instead of a separate tab.
Full screen and mouse capture
Browsers do not allow arbitrarily entering full screen. The same goes for
capturing the cursor. Instead, these actions have to occur as a response to
a JavaScript input event. In Godot, this means entering full screen from within
a pressed input event callback such as _input or _unhandled_input.
Querying the Input singleton is not sufficient, the relevant
input event must currently be active.
For the same reason, the full screen project setting doesn't work unless the engine is started from within a valid input event handler. This requires customization of the HTML page.
Audio
Some browsers restrict autoplay for audio on websites. The easiest way around this limitation is to request the player to click, tap or press a key/button to enable audio, for instance when displaying a splash screen at the start of your game.
Vedi anche
Google offers additional information about their Web Audio autoplay policies.
Apple's Safari team also posted additional information about their Auto-Play Policy Changes for macOS.
Avvertimento
Access to microphone requires a secure context.
Avvertimento
Since Godot 4.3, by default Web exports will use samples instead of streams to play audio.
This is due to the way browsers prefer to play audio and the lack of processing power available when exporting Web games with the Use Threads export option off.
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.