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

Il y a des bogues importants lors de l'exécution de projets HTML5 sur iOS (quel que soit le navigateur). Nous recommandons d'utiliser la fonctionnalité d'exportation native de iOS à la place, car elle permet également d'obtenir de meilleures performances.

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.

Vous pouvez choisir le Type d'exportation pour sélectionner les fonctionnalités qui seront disponibles :

  • Regular : est le plus compatible avec tous les navigateurs, ne supporte pas les threads, ni GDNative.

  • Threads : le navigateur devra prendre en charge SharedArrayBuffer

  • GDNative : active le support GDNative mais rend le binaire plus gros et plus lent à charger.

Si vous prévoyez d'utiliser Compression VRAM, assurez-vous que Vram Texture Compression est activée pour les plateformes ciblées (activer à la fois For Desktop et For Mobile entraînera une exportation plus grosse, mais plus compatible).

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.

Avertissement

Export types autres que Regular ne sont pas encore pris en charge par la version C#.

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

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

Comme mentionné au-dessus de le multi-threading n'est disponible que si le Export Type approprié est défini et sa prise en charge par les navigateurs est encore limitée.

Avertissement

Nécessite un secure context. Les navigateurs commencent également à exiger que la page web soit servie avec des cross-origin isolation headers spécifique.

GDNative

Comme mentionné au-dessus GDNative n'est disponible que si le Export Type approprié est défini.

L'exportation copiera également les fichiers GDNative .wasm nécessaires dans le dossier de sortie (et doivent être téléchargés sur votre serveur avec votre jeu).

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

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

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.

HTML5 export templates may be built without support for the singleton to improve security. With such templates, and on platforms other than HTML5, calling JavaScript.eval will also return null. The availability of the singleton can be checked with the 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)