Up to date

This page is up to date for Godot 4.2. 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, WebGL and SharedArrayBuffer 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.

Attention

Godot 4's HTML5 exports currently cannot run on macOS and iOS due to upstream bugs with SharedArrayBuffer and WebGL 2.0. We recommend using macOS and iOS native export functionality instead, as it will also result in better performance.

Godot 3's HTML5 exports are more compatible with various browsers in general, especially when using the GLES2 rendering backend (which only requires WebGL 1.0).

Version WebGL

Godot 4.0 and later can only target WebGL 2.0 (using the Compatibility rendering method). There is no stable way to run Vulkan applications on the web yet.

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.

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

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

To ensure low audio latency and the ability to use Thread in web exports, Godot 4 web exports always use 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, use coi-serviceworker as a workaround.

If the client doesn't receive the required response headers, the project will not run.

The generated .html file can be used as DirectoryIndex in Apache servers and can be renamed to e.g. index.html at any time. Its name is never depended on by default.

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.

Appel de JavaScript depuis un script

In web builds, the JavaScriptBridge singleton is implemented. It offers a single method called eval that works similarly to the JavaScript function of the same name. It takes a string as an argument and executes it as JavaScript code. This allows interacting with the browser in ways not possible with script languages integrated into Godot.

func my_func():
    JavaScriptBridge.eval("alert('Calling JavaScript per GDScript!');")

La valeur de la dernière déclaration JavaScript est convertie en une valeur GDScript et renvoyée par eval() dans certaines circonstances :

  • JavaScript number is returned as float

  • JavaScript boolean is returned as bool

  • JavaScript string is returned as String

  • JavaScript ArrayBuffer, TypedArray and DataView are returned as PackedByteArray

func my_func2():
    var js_return = JavaScriptBridge.eval("var myNumber = 1; myNumber + 2;")
    print(js_return) # prints '3.0'

Toute autre valeur JavaScript est retournée comme null.

HTML5 export templates may be built without support for the singleton to improve security. With such templates, and on platforms other than HTML5, calling JavaScriptBridge.eval will also return null. The availability of the singleton can be checked with the web feature tag:

func my_func3():
    if OS.has_feature('web'):
        JavaScriptBridge.eval("""
            console.log('The JavaScriptBridge singleton is available')
        """)
    else:
        print("The JavaScriptBridge singleton is NOT available")

Astuce

Les chaînes multi-lignes de GDScript, entourées de 3 guillemets """ comme dans my_func3() ci-dessus, sont utiles pour garder le code JavaScript lisible.

The eval method also accepts a second, optional Boolean argument, which specifies whether to execute the code in the global execution context, defaulting to false to prevent polluting the global namespace:

func my_func4():
    # execute in global execution context,
    # thus adding a new JavaScript global variable `SomeGlobal`
    JavaScriptBridge.eval("var SomeGlobal = {};", true)

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

Encryption / Encryption Key

GODOT_SCRIPT_ENCRYPTION_KEY