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

De nombreux navigateurs, spécifiquement les navigateurs basés sur Chromium, ne chargeront pas les projets exportés quand **ouvert localement ** par le protocole file: //. Pour contourner cela, utilisez un serveur local.

Astuce

Python offre une méthode simple pour démarrer un serveur local. Utilisez python -m SimpleHTTPServer avec Python 2 ou python -m http.server avec Python 3 pour servir le répertoire de travail actuel à http://localhost:8000`.

WebGL 2

Jusqu’à ce que le rendu OpenGL ES 3 soit supprimé de Godot en faveur de Vulkan, l’export 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.

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.

Utilisation des cookies pour la persistance des données

Les utilisateurs doivent autoriser les 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 tiers 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.

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.

Lecture audio automatique

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.

HTTPClient et HTTPRequest.

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

Le fichier exporté .html ne doit pas être réutilisé

Lors de l’exportation, plusieurs espaces de textes réservés sont remplacés dans le fichier HTML généré spécifiquement selon les options d’exportation données. Il ne doit pas être réutilisé pour d’autres exportations.

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.

Fonctionnalité non implémentée

La fonctionnalité suivante est actuellement indisponible sur la plate-forme HTML5 :

  • Sujets
  • GDNative
  • C#
  • Synchronisation du presse-papiers entre moteur et système d’exploitation
  • Réseaux autres que HTTPClient et WebSocketClient

Astuce

Vérifiez la liste des questions HTML5 ouverte sur Github pour voir si la fonctionnalité qui vous intéresse a déjà un problème. Sinon, ouvrez-en une pour communiquer votre préoccupation.

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 Personnalisation de la page HTML d’exportation 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.

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.

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 Personnalisation de la page HTML d’exportation 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.

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 ``nombre``JavaScript est retourné en tant que GDScript float
  • Un booléen JavaScript est retourné en tant que GDScript bool
  • Une ``chaîne``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’export HTML5 peuvent être composés sans le support du singleton. Avec de tels modèles, et sur les plate-formes autres que HTML5, appeler JavaScript.eval renverra null également. La disponibilité du singleton peut être vérifiée avec l’étiquette de fonctionnalité:

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 `MyGlobal`
    JavaScript.eval("var SomeGlobal = {};", true)