Exporter pour le Web

L'exportation HTML5 permet de publier les jeux réalisés avec le moteur Godot dans le navigateur. Cela nécessite le support de WebAssembly et WebGL dans le navigateur de l'utilisateur.

Important

Utilisez la console de développement intégrée au navigateur, généralement ouverte avec F12, pour afficher les informations de débogage comme les erreurs JavaScript, moteur et WebGL.

Attention

There are significant bugs when running HTML5 projects on iOS (regardless of the browser). We recommend using iOS' native export functionality instead, as it will also result in better performance.

WebGL 2

Jusqu'à ce que le moteur de rendu OpenGL ES 3 soit supprimé de Godot en faveur de Vulkan, l'exportation HTML5 utilise WebGL 2 lorsque l'option GLES3 est sélectionnée.

Avertissement

L'utilisation de WebGL 2 n'est pas recommandée en raison de son retrait prévu de Godot sans remplacement.

WebGL 2 n'est pas supporté dans tous les navigateurs. Firefox et Chromium (Chrome, Opera) sont les navigateurs les plus populaires, Safari et Edge ne fonctionnent pas. Sous iOS, tous les navigateurs sont basés sur WebKit (i.e. Safari), donc ils ne fonctionneront pas non plus.

Le moteur de rendu WebGL 2 de Godot a des problèmes avec la 3D et n'est plus maintenu.

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.

You can choose the Export Type to select which features will be available:

  • Regular: is the most compatible across browsers, will not support threads, nor GDNative.

  • Threads: will require the browser to support SharedArrayBuffer

  • GDNative: enables GDNative support but makes the binary bigger and slower to load.

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

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.

Avertissement

Export types other then Regular are not yet supported by the C# version.

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

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

Astuce

Consultez la liste des issues(problèmes) HTML5 ouvertes sur Github pour voir si la fonctionnalité qui vous intéresse a déjà une issue. Sinon, ouvrez une pour communiquer votre préoccupation.

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.

Sujets

As mentioned above multi-threading is only available if the appropriate Export Type is set and support for it across browsers is still limited.

Avertissement

Requires a secure context. Browsers are also starting to require that the web page is served with specific cross-origin isolation headers.

GDNative

As mentioned above GDNative is only available if the appropriate Export Type is set.

The export will also copy the required GDNative .wasm files to the output folder (and must be uploaded to your server along with your game).

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

Chrome restreint la façon dont les sites Web peuvent jouer de l'audio. Il peut être nécessaire pour le joueur de cliquer ou de toucher ou d'appuyer sur une touche pour activer l'audio.

Voir aussi

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

Avertissement

Access to microphone requires a secure context.

Réseau

Low level networking is not implemented due to lacking support in browsers.

Currently, only HTTP client, HTTP requests, WebSocket (client) and WebRTC are supported.

The HTTP classes also have several restrictions on the HTML5 platform:

  • 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

Clipboard

Clipboard synchronization between engine and the operating system requires a browser supporting the Clipboard API, additionally, due to the API asynchronous nature might not be reliable when accessed from GDScript.

Avertissement

Requires a secure context.

Gamepads

Gamepads will not be detected until one of their button is pressed. Gamepads might have the wrong mapping depending on the browser/OS/gamepad combination, sadly the Gamepad API does not provide a reliable way to detect the gamepad information necessary to remap them based on model/vendor/OS due to privacy considerations.

Avertissement

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

Limitations du langage de shader

Lors de l'exportation d'un projet GLES2 vers HTML5, WebGL 1.0 sera utilisé. WebGL 1.0 ne prend pas en charge les boucles dynamiques, donc les shaders qui les utilisent ne fonctionneront pas.

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.

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'étant jamais utilisé par défaut.

La page HTML dessine le jeu à sa taille maximale dans la fenêtre du navigateur. De cette façon, il peut être inséré dans un <iframe> avec la taille du jeu, comme c'est courant sur la plupart des sites d'hébergement de jeux web.

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.

Prudence

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

La distribution des fichiers avec une compression côté serveur est recommandée spécialement pour les fichiers .pck et .wasm, qui sont généralement de grande taille. Le module WebAssembly comprime particulièrement bien, avec environ un quart de la taille d'origine avec la compression gzip.

Hosts that provide on-the-fly compression: GitHub Pages (gzip)

Hosts that don't provide on-the-fly compression: itch.io, GitLab Pages (supports manual gzip precompression)

Appel de JavaScript depuis un script

Dans les versions Web, le singleton JavaScript est implémenté. If offre une seule méthode appelée eval qui fonctionne de manière similaire à la fonction JavaScript du même nom. Il prend une chaîne comme argument et l'exécute en tant que code JavaScript. Cela permet d’interagir avec le navigateur selon des façons qui ne seraient pas possibles avec les langages de scripts intégrés à Godot.

func my_func():
    JavaScript.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 :

  • Un number JavaScript est retourné en tant que GDScript float

  • Un boolean JavaScript est retourné en tant que GDScript bool

  • Un string JavaScript est retournée en tant que GDScript String

  • JavaScript ArrayBuffer, TypedArray et DataView sont retournés en tant que GDScript PoolByteArray

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

Toute autre valeur JavaScript est retournée comme null.

Les modèles d'exportation HTML5 peuvent être compilé sans support du singleton pour améliorer la sécurité. Avec de tels modèles, et sur des plateformes autres que HTML5, appeler JavaScript.eval renverra également null. La disponibilité du singleton peut être vérifiée avec le JavaScript feature tag :

func my_func3():
    if OS.has_feature('JavaScript'):
        JavaScript.eval("""
            console.log('The JavaScript singleton is available')
        """)
    else:
        print("The JavaScript 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.

La méthode eval accepte également un deuxième argument facultatif, booléen, qui spécifie si le code doit être exécuté dans le contexte d'exécution global, la valeur par défaut étant faux pour éviter de polluer l'espace de nom global :

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