Up to date

This page is up to date for Godot 4.3. If you still find outdated information, please open an issue.

Exportation pour le Web

Voir aussi

Cette page explique comment exporter un projet Godot vers HTML5. Si vous cherchez à compiler l’éditeur ou les binaires du modèle d'exportation depuis le code source, voyez plutôt Compilation pour le Web.

HTML5 export allows publishing games made in Godot Engine to the browser. This requires support for WebAssembly and WebGL 2.0 in the user's browser.

Attention

Projects written in C# using Godot 4 currently cannot be exported to the web. To use C# on web platforms, use Godot 3 instead.

Astuce

Use the browser-integrated developer console, usually opened with F12 (Cmd + Option + I on macOS), to view debug information like JavaScript, engine, and WebGL errors.

Voir aussi

See the list of open issues on GitHub related to the web export for a list of known bugs.

Export file name

We suggest users to export their Web projects with index.html as the file name. index.html is usually the default file loaded by web servers when accessing the parent directory, usually hiding the name of that file.

Attention

The Godot 4 Web export expects some files to be named the same name as the one set in the initial export. Some issues could occur if some exported files are renamed, including the main HTML file.

Version WebGL

Godot 4.0 and later can only target WebGL 2.0 (using the Compatibility rendering method). Forward+/Mobile are not supported on the web platform, as these rendering methods are designed around modern low-level graphics APIs. Godot currently does not support WebGPU, which is a prerequisite for allowing Forward+/Mobile to run on the web platform.

See Can I use WebGL 2.0 for a list of browser versions supporting WebGL 2.0. Note that Safari has several issues with WebGL 2.0 support that other browsers don't have, so we recommend using a Chromium-based browser or Firefox if possible.

Audio playback

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:

  • AudioEffects are not supported.

  • Reverberation and doppler effects are not supported.

  • Procedural audio generation is not supported.

  • Positional audio may not always work correctly depending on the node's properties.

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.

Options d'exportation

Si un modèle d'exportation Web fonctionnel est disponible, un bouton apparaît entre les boutons Arrêter la scène et Jouer la scène éditée dans l'éditeur pour ouvrir rapidement le jeu dans le navigateur par défaut pour le tester.

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).

Si un chemin d'accès à un fichier Custom HTML shell est fourni, il sera utilisé à la place de la page HTML par défaut. Voir Page HTML custom pour un export Web.

Head Include est ajouté à l'élément <head> de la page HTML générée. Cela permet, par exemple, de charger des polices Web et des API JavaScript tierces, d'inclure du CSS ou d'exécuter du code JavaScript.

Important

Chaque projet doit générer son propre fichier HTML. Lors de l'exportation, plusieurs caractères génériques de texte sont remplacés dans le fichier HTML généré spécifiquement pour les options d'exportation données. Toute modification directe du fichier HTML généré sera perdue dans les exportations futures. Pour personnaliser le fichier généré, utilisez l'option Custom HTML shell.

Thread and extension support

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 Distribuer les fichiers 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.

    • If the offline data is not available because it was evicted from the cache, you can configure an Offline Page that will be displayed in this case. The page must be in HTML format and will be saved on the client's machine the first time the project is loaded.

  • Ensure cross-origin isolation headers are always present, even if the web server hasn't been configured to send them. This allows exports with threads enabled to work when hosted on any website, even if there is no way for you to control the headers it sends.

    • This behavior can be disabled by unchecking Enable Cross Origin Isolation Headers in the Progressive Web App section.

Limites

Pour des raisons de sécurité et de confidentialité, de nombreuses fonctionnalités qui fonctionnent sans effort sur les plates-formes natives sont plus compliquées sur la plate-forme Web. Voici une liste de limitations dont vous devez être conscient lorsque vous portez un jeu Godot sur le web.

Important

Les fournisseurs de navigateurs rendent de plus en plus de fonctionnalités disponibles uniquement dans des contextes sécurisés, ce qui signifie que ces fonctionnalités ne sont disponibles que si la page web est servie via une connexion HTTPS sécurisée (localhost est généralement exempt de cette exigence).

Utilisation des cookies pour la persistance des données

Les utilisateurs doivent allow cookies (spécifiquement IndexedDB) si la persistance du système de fichiers user :// `` est souhaitée. Lors de l'exécution d'un jeu présenté dans une ``iframe, les cookies third-party doivent également être activés. Le mode de navigation incognito/privé empêche également la persistance.

La méthode OS.is_userfs_persistent() peut être utilisée pour vérifier si le système de fichiers user:// est persistant, mais peut donner des faux positifs dans certains cas.

Traitement en arrière-plan

Le projet sera mis en pause par le navigateur lorsque l'onglet n'est plus l'onglet actif dans le navigateur de l'utilisateur. Cela signifie que les fonctions telles que process() et process() ne seront plus exécutées jusqu'à ce que l'onglet soit rendu actif par l'utilisateur (en retournant à l'onglet). Cela peut entraîner la déconnexion des jeux en réseau si l'utilisateur change d'onglet pendant une longue période.

Cette limitation ne s'applique pas aux fenêtres de navigateur non focalisées. Par conséquent, du côté de l'utilisateur, il est possible de contourner ce problème en exécutant le projet dans une fenêtre distincte plutôt que dans un onglet séparé.

Capture plein écran et à la souris

Les navigateurs n'autorisent pas l'accès arbitraire en plein écran. Il en va de même pour la capture du curseur. Au lieu de cela, ces actions doivent se produire en réponse à un événement d'entrée JavaScript. Dans Godot, cela signifie qu'il faut entrer en plein écran à partir d'un rappel d'événement d'entrée pressé tel que _input ou _unhandled_input. Interroger le singleton Input n'est pas suffisant, l'événement d'entrée pertinent doit être actuellement actif.

Pour la même raison, le réglage du projet en plein écran ne fonctionne pas à moins que le moteur ne soit démarré à partir d'un gestionnaire d'événements d'entrée valide. Cela nécessite 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.

Voir aussi

Google offre des informations supplémentaires sur leur Web Audio autoplay politiques.

Apple's Safari team also posted additional information about their Auto-Play Policy Changes for macOS.

Avertissement

L'accès au microphone nécessite un:ref:secure context <doc_javascript_secure_contexts>.

Réseau

La mise en réseau de bas niveau n'est pas mise en œuvre en raison de l'absence de support dans les navigateurs.

Actuellement, seuls HTTP client, HTTP requests, WebSocket (client) et WebRTC sont supportés.

Les classes HTTP ont plusieurs restrictions sur la plate-forme HTML5 :

  • L'accès ou la modification du StreamPeer n'est pas possible

  • Le mode Threaded/Blocking n'est pas disponible

  • Ne peut pas progresser plus d'une fois par image, dès lors l'interrogation dans une boucle se figera

  • Pas de réponses fragmentées

  • La vérification de l'hôte ne peut pas être désactivée

  • Sujet à la politique de même origine

Presse-papiers

La synchronisation du presse-papiers entre le moteur et le système d'exploitation nécessite un navigateur prenant en charge Clipboard API, en outre, en raison de la nature asynchrone de l'API, cela pourrait ne pas être fiable lorsqu'on y accède depuis GDScript.

Avertissement

Requiert un secure context.

Manettes de jeu

Les manettes ne seront pas détectées jusqu'à ce qu'un de leurs boutons soit pressé. Les manettes de jeu peuvent avoir un mauvais mappage en fonction de la combinaison navigateur/OS/manette de jeu, malheureusement la Gamepad API ne fournit pas un moyen fiable de détecter les informations de manette de jeu nécessaires pour les remapper en fonction du modèle/vendeur/OS en raison de considérations de confidentialité.

Avertissement

Requiert un secure context.

Le boot splash n'est pas affiché

La page HTML par défaut n'affiche pas le boot splash pendant le chargement. Cependant, l'image est exportée au format PNG, donc pages HTML personnalisées peut l'afficher.

Distribuer les fichiers

L'exportation pour le Web génère plusieurs fichiers à transférer depuis un serveur Web, y compris une page HTML par défaut de présentation. Un fichier HTML personnalisé peut être utilisé, voir Page HTML custom pour un export Web.

Avertissement

If either thread support or extension support are enabled, the exported project will require SharedArrayBuffer. This requires a secure context, while also requiring the following CORS headers to be set when serving the files:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

If you don't control the web server or are unable to add response headers, check Progressive Web App > Enable in the export options. This applies a service worker-based workaround that allows the project to run by simulating the presence of these response headers. A secure context is still required in this case.

If the client doesn't receive the required response headers or the service worker-based workaround is not applied, the project will not run.

Le fichier .html généré peut être utilisé comme DirectoryIndex dans les serveurs Apache et peut être renommé, par exemple, index.html à tout moment. Son nom n'est jamais utilisé par défaut.

The HTML page draws the game at maximum size within the browser window. This way, it can be inserted into an <iframe> with the game's size, as is common on most web game hosting sites.

Les autres fichiers exportés sont transférés tels quels, à côté du fichier .html, noms inchangés. Le fichier .wasm est un module WebAssembly binaire implémentant le moteur. Le fichier .pck est le pack principal de Godot contenant votre jeu. Le fichier .js contient du code de démarrage et est utilisé par le fichier .html pour accéder au moteur. Le fichier .png contient l'image de démarrage. Il n'est pas utilisé dans la page HTML par défaut, mais est inclus pour pages HTML personnalisées.

Le fichier .pck est binaire, généralement fourni avec le MIME-type application/octet-stream. Le fichier .wasm est fourni sous la forme application/wasm.

Avertissement

La livraison du module WebAssembly (.wasm) avec un type MIME autre que application/wasm peut empêcher certaines optimisations de démarrage.

Delivering the files with server-side compression is recommended especially for the .pck and .wasm files, which are usually large in size. The WebAssembly module compresses particularly well, down to around a quarter of its original size with gzip compression. Consider using Brotli precompression if supported on your web server for further file size savings.

Hébergeurs qui fournissent une compression à la volée : Pages GitHub (gzip)

Hôtes qui ne fournissent pas de compression à la volée : itch.io, GitLab Pages (prend en charge la précompression manuelle gzip)

Astuce

The Godot repository includes a Python script to host a local web server. This script is intended for testing the web editor, but it can also be used to test exported projects.

Save the linked script to a file called serve.py, move this file to the folder containing the exported project's index.html, then run the following command in a command prompt within the same folder:

# You may need to replace `python` with `python3` on some platforms.
python serve.py --root .

On Windows, you can open a command prompt in the current folder by holding Shift and right-clicking on empty space in Windows Explorer, then choosing Open PowerShell window here.

This will serve the contents of the current folder and open the default web browser automatically.

Note that for production use cases, this Python-based web server should not be used. Instead, you should use an established web server such as Apache or nginx.

Interacting with the browser and JavaScript

See the dedicated page on how to interact with JavaScript and access some unique Web browser features.

Variables d'environnement

You can use the following environment variables to set export options outside of the editor. During the export process, these override the values that you set in the export menu.

HTML5 export environment variables

Export option

Environment variable

Cryptage / Clé de cryptage

GODOT_SCRIPT_ENCRYPTION_KEY