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.

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.

Version WebGL¶

En fonction de votre choix de moteur de rendu, Godot peut cibler WebGL 1.0 (GLES2) ou WebGL 2.0 (GLES3).

WebGL 1.0 est l'option recommandée si vous souhaitez que votre projet soit pris en charge par tous les navigateurs avec les meilleures performances.

Le moteur de rendu GLES3 de Godot vise les appareils haut de gamme, et les performances obtenues avec WebGL 2.0 peuvent être médiocres. Certaines fonctionnalités ne sont pas spécifiquement prises en charge par WebGL 2.0.

En outre, si la plupart des navigateurs prennent en charge WebGL 2.0, ce n'est pas encore le cas pour Safari. La prise en charge de WebGL 2.0 est prévue dans Safari 15 pour macOS, et n'est pas encore disponible pour aucun navigateur iOS (tous basés sur WebKit comme Safari). Voir Can I use WebGL 2.0 pour plus de détails.

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 : requière que le navigateur supporte SharedArrayBuffer. Voir Can I use SharedArrayBuffer pour plus de détails.
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 other than 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

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.

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

Tâches Parallèles¶

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¶

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.

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.

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)

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)