Développement HTML5

Defold permet de créer des builds de jeux pour la plateforme HTML5 à partir du menu habituel de création de bundles, comme pour les autres plateformes. De plus, le jeu obtenu est intégré à une page HTML classique dont vous pouvez personnaliser l’apparence grâce à un système de modèles simple.

Le fichier game.project contient les paramètres propres à HTML5 :

Taille du tas

La prise en charge de HTML5 dans Defold repose sur Emscripten (voir http://en.wikipedia.org/wiki/Emscripten). En résumé, il crée un espace mémoire isolé pour le tas dans lequel l’application s’exécute. Par défaut, le moteur alloue une quantité généreuse de mémoire (256 Mo). Cela devrait être largement suffisant pour un jeu classique. Dans le cadre de vos optimisations, vous pouvez choisir d’utiliser une valeur plus petite. Pour cela, suivez ces étapes :

1. Définissez heap_size à la valeur souhaitée. Elle doit être exprimée en mégaoctets.
2. Créez votre bundle HTML5 (voir ci-dessous)

Tester un build HTML5

Pour être testé, un build HTML5 nécessite un serveur HTTP. Defold en crée un pour vous si vous sélectionnez Project ▸ Build HTML5.

Pour tester votre bundle, il vous suffit de l’envoyer sur votre serveur HTTP distant ou de créer un serveur local, par exemple avec Python dans le dossier du bundle. Python 2 :

python -m SimpleHTTPServer

Python 3 :

python -m http.server

ou

python3 -m http.server

Créer un bundle HTML5

Créer du contenu HTML5 avec Defold est simple et suit la même procédure que pour toutes les autres plateformes prises en charge : sélectionnez Project ▸ Bundle... ▸ HTML5 Application... dans le menu :

Les bundles HTML5 prennent en charge deux architectures WebAssembly :

• wasm-web - le moteur WebAssembly classique, sans threads.
• wasm_pthread-web - un moteur WebAssembly qui peut utiliser des threads.

Vous pouvez inclure l’une des architectures ou les deux. Lorsque les deux sont incluses, le chargeur sélectionne wasm_pthread-web si le navigateur et l’environnement d’hébergement le prennent en charge, et utilise wasm-web dans le cas contraire. Consultez le manuel de Bob pour connaître les noms canoniques des cibles.

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Les bundles HTML5 de Defold nécessitent un navigateur moderne prenant en charge WebAssembly. Internet Explorer 11 n’est pas pris en charge.

Lorsque vous cliquez sur le bouton Create bundle, vous êtes invité à sélectionner un dossier dans lequel créer votre application. Une fois l’exportation terminée, vous y trouverez tous les fichiers nécessaires à l’exécution de l’application.

Problèmes connus et limitations

• Rechargement à chaud - Le rechargement à chaud ne fonctionne pas dans les builds HTML5. Les applications Defold doivent exécuter leur propre serveur web miniature pour recevoir les mises à jour de l’éditeur, ce qui n’est pas possible dans un build HTML5.
• Chrome
  • Lenteur des builds de débogage - Dans les builds de débogage pour HTML5, nous vérifions tous les appels graphiques WebGL afin de détecter les erreurs. Cette vérification est malheureusement très lente lors des tests dans Chrome. Vous pouvez la désactiver en définissant le champ Engine Arguments de game.project à --verify-graphics-calls=false.
• Prise en charge des manettes - Consultez la documentation sur les manettes pour connaître les particularités de HTML5 et les mesures que vous pourriez devoir prendre.

Personnaliser un bundle HTML5

Lorsque vous générez une version HTML5 de votre jeu, Defold fournit une page web par défaut. Elle référence des ressources de style et de script qui déterminent la présentation de votre jeu.

À chaque exportation de l’application, ce contenu est entièrement recréé. Si vous souhaitez personnaliser l’un de ces éléments, vous devez modifier les paramètres de votre projet. Pour cela, ouvrez game.project dans l’éditeur Defold et faites défiler jusqu’à la section html5 :

Vous trouverez plus d’informations sur chaque option dans le manuel des paramètres du projet.

Dans game.project, vous pouvez désactiver le bouton Fullscreen et le lien Made with Defold. Defold fournit un thème sombre et un thème clair pour index.html. Le thème clair est défini par défaut, mais vous pouvez le changer en modifiant le fichier Custom CSS. Vous pouvez également choisir parmi quatre modes de mise à l’échelle prédéfinis dans le champ Scale Mode.

Modes Downscale Fit et Fit

Avec le mode Fit, la taille du canevas est modifiée pour afficher tout le canevas du jeu à l’écran en conservant ses proportions d’origine. La seule différence avec Downscale Fit est que la taille ne change que si la zone intérieure de la page web est plus petite que le canevas d’origine du jeu ; le canevas n’est pas agrandi lorsque la page web est plus grande que le canevas d’origine.

Mode Stretch

Avec le mode Stretch, la taille du canevas est modifiée pour remplir entièrement la zone intérieure de la page web.

Mode No Scale

Avec le mode No Scale, la taille du canevas est exactement celle que vous avez définie dans la section [display] du fichier game.project.

Jetons

Nous utilisons le langage de modèles Mustache pour créer le fichier index.html. Lorsque vous créez un build ou un bundle, les fichiers HTML et CSS passent par un compilateur capable de remplacer certains jetons par des valeurs qui dépendent des paramètres de votre projet. Ces jetons sont toujours entourés d’accolades doubles ou triples ({{TOKEN}} ou {{{TOKEN}}}), selon que les séquences de caractères doivent être échappées ou non. Cette fonctionnalité peut être utile si vous modifiez fréquemment les paramètres de votre projet ou si vous prévoyez de réutiliser ce contenu dans d’autres projets.

Toute valeur de game.project peut servir de jeton. Par exemple, si vous souhaitez utiliser la valeur Width de la section Display :

Ouvrez game.project sous forme de texte et vérifiez [section_name] ainsi que le nom du champ que vous souhaitez utiliser. Vous pouvez ensuite l’utiliser comme jeton : {{section_name.field}} ou {{{section_name.field}}}.

Par exemple, en JavaScript dans le modèle HTML :

function doSomething() {
    var x = {{display.width}};
    // ...
}

Nous proposons également les jetons personnalisés suivants :

DEFOLD_SPLASH_IMAGE

Insère le nom du fichier de l’image de démarrage, ou false si html5.splash_image est vide dans game.project

{{#DEFOLD_SPLASH_IMAGE}}
		background-image: url("{{DEFOLD_SPLASH_IMAGE}}");
{{/DEFOLD_SPLASH_IMAGE}}

exe-name

Le nom du projet sans les symboles non autorisés

DEFOLD_CUSTOM_CSS_INLINE

C’est ici que nous insérons directement le contenu du fichier CSS indiqué dans les paramètres de votre game.project.

<style>
{{{DEFOLD_CUSTOM_CSS_INLINE}}}
</style>

DEFOLD_SCALE_MODE_IS_DOWNSCALE_FIT

Ce jeton vaut true si html5.scale_mode vaut Downscale Fit.

DEFOLD_SCALE_MODE_IS_FIT

Ce jeton vaut true si html5.scale_mode vaut Fit.

DEFOLD_SCALE_MODE_IS_NO_SCALE

Ce jeton vaut true si html5.scale_mode vaut No Scale.

DEFOLD_SCALE_MODE_IS_STRETCH

Ce jeton vaut true si html5.scale_mode vaut Stretch.

DEFOLD_HEAP_SIZE

La taille du tas indiquée dans game.project par html5.heap_size, convertie en octets.

DEFOLD_ENGINE_ARGUMENTS

Les arguments du moteur indiqués dans game.project par html5.engine_arguments, séparés par le symbole ,.

build-timestamp

L’horodatage du build actuel, en secondes.

Paramètres supplémentaires

Si vous créez un modèle personnalisé, vous pouvez modifier les paramètres du chargeur du moteur en affectant des valeurs à l’objet global CUSTOM_PARAMETERS. Le modèle intégré fournit un bloc <script id="engine-setup"> volontairement vide pour ces personnalisations.

Par exemple :

    <script id="engine-setup" type="text/javascript">
        CUSTOM_PARAMETERS.disable_context_menu = false;
        CUSTOM_PARAMETERS.unsupported_webgl_callback = function() {
            console.log("Oh-oh. WebGL not supported...");
        };
    </script>

CUSTOM_PARAMETERS peut notamment contenir les champs suivants :

'archive_location_filter':
    Filter function that will run for each archive path.

'unsupported_webgl_callback':
    Function that is called if WebGL is not supported.

'engine_arguments':
    List of arguments (strings) that will be passed to the engine.

'custom_heap_size':
    Number of bytes specifying the memory heap size.

'disable_context_menu':
    Disables the right-click context menu on the canvas element if true.

'retry_time':
    Pause in seconds before retry file loading after error.

'retry_count':
    How many attempts we do when trying to download a file.

'can_not_download_file_callback':
    Function that is called if you can't download file after 'retry_count' attempts.

'resize_window_callback':
    Function that is called when resize/orientationchanges/focus events happened

'start_success':
    Function that is called just before main is called upon successful load.

'update_progress':
    Function that is called as progress is updated. Parameter progress is updated 0-100.

Opérations sur les fichiers en HTML5

Les builds HTML5 prennent en charge les opérations sur les fichiers telles que sys.save(), sys.load() et io.open(), mais leur traitement interne diffère de celui des autres plateformes. Lorsque JavaScript s’exécute dans un navigateur, il n’existe pas de véritable notion de système de fichiers et l’accès aux fichiers locaux est bloqué pour des raisons de sécurité. Emscripten (et donc Defold) utilise à la place IndexedDB, une base de données intégrée au navigateur qui stocke les données de manière persistante, pour créer un système de fichiers virtuel dans le navigateur. La différence importante par rapport à l’accès au système de fichiers sur les autres plateformes est qu’un léger délai peut s’écouler entre l’écriture dans un fichier et l’enregistrement effectif de la modification dans la base de données. La console de développement du navigateur permet généralement d’inspecter le contenu d’IndexedDB.

Transmettre des arguments à un jeu HTML5

Il est parfois nécessaire de fournir des arguments supplémentaires à un jeu avant ou pendant son démarrage. Il peut s’agir, par exemple, d’un identifiant d’utilisateur, d’un jeton de session ou du niveau à charger au démarrage du jeu. Vous pouvez procéder de plusieurs façons, dont certaines sont décrites ici.

Arguments du moteur

Vous pouvez spécifier des arguments supplémentaires pour le moteur lors de sa configuration et de son chargement. Ces arguments supplémentaires peuvent être récupérés à l’exécution avec sys.get_config_string(). Affectez les arguments directement à CUSTOM_PARAMETERS.engine_arguments dans le bloc engine-setup de index.html :

    <script id="engine-setup" type="text/javascript">
        CUSTOM_PARAMETERS.engine_arguments = [
            "--config=example.foo1=bar1",
            "--config=example.foo2=bar2"
        ];
    </script>

L’affectation d’un nouveau tableau remplace tous les arguments du moteur configurés dans game.project. Pour conserver ces arguments et en ajouter un autre, utilisez plutôt CUSTOM_PARAMETERS.engine_arguments.push("--config=example.foo3=bar3").

Vous pouvez également ajouter --config=example.foo1=bar1, --config=example.foo2=bar2 au champ Engine Arguments de la section HTML5 de game.project. Les valeurs séparées par des virgules sont ajoutées à CUSTOM_PARAMETERS.engine_arguments dans le fichier dmloader.js généré.

À l’exécution, vous récupérez les valeurs ainsi :

local foo1 = sys.get_config_string("example.foo1")
local foo2 = sys.get_config_string("example.foo2")
print(foo1) -- bar1
print(foo2) -- bar2

Arguments de requête dans l’URL

Vous pouvez transmettre des arguments dans les paramètres de requête de l’URL de la page et les lire à l’exécution :

https://www.mygame.com/index.html?foo1=bar1&foo2=bar2

local url = html5.run("window.location")
print(url)

Une fonction utilitaire complète pour récupérer tous les paramètres de requête sous forme de table Lua :

local function get_query_parameters()
    local url = html5.run("window.location")
    -- get the query part of the url (the bit after ?)
    local query = url:match(".*?(.*)")
    if not query then
        return {}
    end

    local params = {}
    -- iterate over all key value pairs
    for kvp in query:gmatch("([^&]+)") do
        local key, value = kvp:match("(.+)=(.+)")
        params[key] = value
    end
    return params
end

function init(self)
    local params = get_query_parameters()
    print(params.foo1) -- bar1
end

Optimisations

Les jeux HTML5 ont généralement des exigences strictes concernant la taille du téléchargement initial, le temps de démarrage et l’utilisation de la mémoire, afin de garantir un chargement rapide et un bon fonctionnement sur les appareils peu puissants et les connexions Internet lentes. Pour optimiser un jeu HTML5, il est recommandé de vous concentrer sur les points suivants :

• Utilisation de la mémoire
• Taille du moteur
• Taille du jeu

FAQ

Q : Pourquoi mon application HTML5 se fige-t-elle sur l’écran de démarrage dans Chrome ?

R : Dans certains cas, il n’est pas possible d’exécuter un jeu localement dans le navigateur à partir du système de fichiers. Lorsque vous lancez le jeu depuis l’éditeur, un serveur web local le sert au navigateur. Vous pouvez, par exemple, utiliser SimpleHTTPServer en Python :

$ python -m SimpleHTTPServer [port]

Q : Pourquoi mon jeu plante-t-il avec l’erreur « Unexpected data size » pendant le chargement ?

R : Cela se produit généralement lorsque vous utilisez Windows, créez un build et l’enregistrez dans un commit Git. Si la configuration des fins de ligne dans Git est incorrecte, Git modifiera vos fins de ligne et donc également la taille des données. Suivez ces instructions pour résoudre le problème : https://docs.github.com/en/free-pro-team@latest/github/using-git/configuring-git-to-handle-line-endings