Personnalisation de la page HTML d’exportation Web

Plutôt que la page HTML par défaut qui vient avec les modèles d’exportation, il est également possible d’utiliser une page HTML personnalisée. Cela permet une personnalisation totale de la présentation web finale et du comportement. Le chemin d’accès à la page HTML personnalisée est spécifié dans les options d’exportation Html/Custom Html Shell.

La page HTML par défaut est disponible dans le dépôt du moteur Godot à l’adresse /misc/dist/html/full-size.html. Quelques cas d’utilisation simples où il est utile de personnaliser la page par défaut inclus :

  • Chargement de fichiers à partir d’un autre répertoire
  • Chargement d’un fichier .zip au lieu d’un fichier .pck comme paquet principal
  • Chargement des fichiers du moteur à partir d’un répertoire différent de celui du fichier pack principal
  • Adding a click-to-play button so games can be started in full-screen mode
  • Chargement de certains fichiers supplémentaires avant le démarrage du moteur, de sorte qu’ils soient disponibles dans le système de fichiers plus tard
  • Passer des arguments de « ligne de commande » personnalisés, par exemple -s pour démarrer un script de boucle principale

Un autre exemple de page HTML est disponible à l’adresse /misc/dist/html/fixed-size.html.Cette page utilise un canevas de taille fixe avec un widget de sortie ci-dessous. Cependant, la console de navigation F12 doit être préférée car elle peut afficher des informations supplémentaires, telles que des erreurs WebGL.

Substitution de caractères génériques

Lors de l’exportation du jeu, plusieurs chaînes caractères substituables de la page HTML sont remplacées par des valeurs dépendantes de l’exportation :

Chaîne substituable Remplacé par
$GODOT_BASENAME Nom de base des fichiers exportés sans suffixes, par exemple jeu lors de l’exportation de jeu.html
$GODOT_DEBUG_ENABLED true si en débogage, false sinon
$GODOT_HEAD_INCLUDE Chaîne personnalisée à inclure juste avant la fin de l’élément HTML <head>

Le fichier HTML doit évaluer le fichier JavaScript $GODOT_BASENAME.js. Ce fichier définit un objet global Engine utilisé pour démarrer le moteur, voir ci-dessous pour plus de détails.

L’image de démarrage est exportée en tant que $GODOT_BASENAME.png et peut être utilisée par exemple dans des éléments <img />.

$GODOT_DEBUG_ENABLED peut être utile pour afficher facultativement par exemple une console de sortie ou d’autres outils de débogage.

$GODOT_HEAD_INCLUDE est substitué par la chaîne de caractères spécifiée par l’option d’exportation Html/Head Include.

L’objet Engine

L’objet global JavaScript Engine est défini par $GODOT_BASENAME.js et sert d’interface pour le processus de démarrage du moteur.

L’API est basée sur et nécessite une compréhension de base de Promises.

L’objet lui-même n’a que les méthodes suivantes :

Engine.load(basePath)

Charge le moteur à partir du chemin de base transmis.

Arguments:
  • basePath (string) – Base path of the engine to load.
Renvoie:

Promesse qui résout une fois le moteur est chargé.

Engine.unload()

Unload the engine to free memory.

Ceci est appelé automatiquement une fois que le moteur est démarré à moins d’être explicitement désactivé en utilisant engine.setUnloadAfterInit().

Engine.isWebGLAvailable([majorVersion = 1])

Check whether WebGL is available.

Arguments:
  • majorVersion (number) – The major WebGL version to check for. Defaults to 1 for WebGL 1.0.
Renvoie:

« true » si la version majeure donnée de WebGL est disponible, « false » sinon.

Engine.setWebAssemblyFilenameExtension(extension)

When loading the engine, the filename extension of the WebAssembly module is assumed to be wasm. This function allows usage of an alternate extension.

Engine.setWebAssemblyFilenameExtension('dat');
// Load 'mygame.dat' as WebAssembly module.
Engine.load('mygame');

This is useful for outdated hosts that only accept uploads of files with certain filename extensions.

Arguments:
  • extension (string) – Filename extension without preceding dot.

Note

Depending on the host, using an alternate filename extension can prevent some start-up optimizations. This occurs when the file is delivered with a MIME-type other than application/wasm.

Démarrage d’une instance Engine

Engine() also acts a class:

class Engine()

An instance of the engine that can be started, usually a game.

Instantiate the class using the new operator:

var engine = new Engine();

This yields an Engine() instance, referred to as engine with a lower-case e from here.

Pour démarrer une telle instance, l’objet global Engine doit être chargé, puis l’instance engine doit être initialisée et enfin lancée.

engine.init([basePath])

Initialize the instance. The instance can then be started with one of the start functions, usually engine.startGame().

Arguments:
  • basePath (string) – The base path to the engine, same as in Engine.load(). Must be passed only if the engine hasn’t been loaded yet.
Renvoie:

Renvoie une promesse qui se résout une fois le moteur chargé.

engine.preloadFile(file[, path])

Chargez un fichier pour qu’il soit disponible dans le système de fichiers une fois l’instance lancée. Doit être appelé avant de démarrer l’instance.

Arguments:
  • file – Si le type est string, le fichier sera chargé à partir de ce chemin. Si le type est ArrayBuffer ou une vue sur un, le tampon sera utilisé comme contenu du fichier.
  • path (string) – Chemin par lequel le fichier sera disponible. Obligatoire si le fichier` n’est pas une chaîne de caractères. S’il n’est pas passé, le chemin est dérivé de l’URL du fichier chargé.
Renvoie:

Promesse qui se résout une fois que le fichier est préchargé.

engine.start([arg1, arg2, ])

Démarre l’instance du moteur, en utilisant les chaînes passées comme arguments en ligne de commande. Cela permet un grand contrôle sur la façon dont le moteur est démarré, mais habituellement les autres méthodes commençant par engine.start sont plus simples et devraient être utilisées à la place.

If the instance has not yet been initialized with engine.init(), it will be.

The engine must be loaded beforehand.

Requires that the engine has been loaded, and that a canvas can be found on the page.

Arguments:
  • variadic (string) – Arguments de ligne de commande.
Renvoie:

Promesse qui se résout une fois le moteur démarré.

engine.startGame(mainPack)

Initializes the engine if not yet initialized and starts the game with the main pack loaded from the passed URL.

Si le moteur n’est pas encore chargé, le chemin de base de l’URL passée sera utilisé pour charger le moteur.

This function ignores overrides of filenames and their extensions to start only the main pack passed as argument.

Arguments:
  • mainPack (string) – Path to the main pack to start. Also used as base path to load the engine if not loaded already.
Renvoie:

Promesse qui se résout une fois le jeu démarré.

Configuration du comportement de démarrage

Outre le démarrage du moteur, d’autres méthodes de l’instance du moteur permettent de configurer le comportement :

engine.setUnloadAfterInit(enabled)

Specify whether the Engine will be unloaded automatically after the instance is initialized.

Cela libère la mémoire du navigateur en déchargeant les fichiers qui ne sont plus nécessaires une fois l’instance initialisée. Cependant, si d’autres instances du moteur doivent être démarrées, le moteur devra être à nouveau chargé.

Enabled by default.

Arguments:
  • enabled (boolean) – « true » si le moteur doit être déchargé après l’initialisation, « false » sinon.
engine.setCanvas(canvasElem)

Specify a canvas to use.

Par défaut, le premier élément de canevas de la page est utilisé pour le rendu.

Arguments:
  • canvasElem (HTMLCanvasElement) – The canvas to use.
engine.setCanvasResizedOnStart(enabled)

Spécifie si le canevas sera redimensionné à la largeur et à la hauteur spécifiées dans les paramètres du projet au démarrage.

Enabled by default.

Arguments:
  • enabled (boolean) – « true » si le canevas doit être redimensionnée au départ, « false » sinon.
engine.setLocale(locale)

Par défaut, le moteur essaiera de deviner quelle version de langue utiliser à partir de l’environnement JavaScript. Il est généralement préférable d’utiliser une version de langue spécifiée par l’utilisateur côté serveur, ou du moins d’utiliser la version de langue demandée dans l’en-tête HTTP Accept-Language. Cette méthode permet de spécifier une telle version personnalisée.

For example, with PHP:

engine.setLocale(<?php echo Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']); ?>);
Arguments:
  • locale (string) – Locale.

Voir aussi

List of locales.

engine.setExecutableName(execName)

Specify the virtual filename of the executable.

A real executable file doesn’t exist for the HTML5 platform. However, a virtual filename is stored by the engine for compatibility with other platforms.

Par défaut, le nom de base des fichiers moteur chargés est utilisé. Cette méthode permet de spécifier un autre nom.

This affects the output of OS.get_executable_path() and the automatically started main pack, ExecutableName.pck.

Arguments:
  • execName (string) – Executable name.

Personnalisation de la présentation

Les méthodes suivantes sont utilisées pour implémenter la présentation :

engine.setProgressFunc(callback)

Set the callback for displaying download progress.

Arguments:
  • callback (function) – Callback called once per frame with two number arguments: bytes loaded so far, and total bytes to load.
function printProgress(current, total) {
    console.log("Loaded " + current + " of " + total + " bytes");
}
engine.setProgressFunc(printProgress);

Si le total est 0, il ne pouvait pas être calculé. Les raisons possibles sont :

  • Les fichiers sont délivrés avec une compression par tronçons réalisée par le serveur
  • Les fichiers sont délivrés avec une compression côté serveur sur Chromium
  • Les téléchargements de fichiers n’ont pas encore tous démarré (en général sur des serveurs sans multi-threading)

Note

For ease of use, the callback is only called once per frame, so that usage of requestAnimationFrame() is not necessary.

engine.setStdoutFunc(callback)

Specify the standard output stream callback.

Arguments:
  • callback (function) – Callback function called with one argument, the string to print.
function printStdout(text) {
    console.log(text);
}
engine.setStdoutFunc(printStdout);

Cette méthode ne devrait généralement être utilisée que dans les pages de débogage. Le conteneur $GODOT_DEBUG_ENABLED` peut être utilisé pour vérifier cela.

Par défaut, console.log()` est utilisé.

engine.setStderrFunc(callback)

Specify the standard error stream callback.

Arguments:
  • callback (function) – Callback function called with one argument, the string to print.
function printStderr(text) {
    console.warn("Error: " + text);
}
engine.setStderrFunc(printStderr);

Cette méthode ne devrait généralement être utilisée que dans les pages de débogage. Le conteneur $GODOT_DEBUG_ENABLED` peut être utilisé pour vérifier cela.

Par défaut, console.warn()` est utilisé.

Accès au Module Emscripten en cours

Si vous savez ce que vous faites, vous pouvez accéder à l’environnement d’exécution (le Module d’Emscripten) avec engine.rtenv. Consultez la documentation d’Emscripten pour plus d’information sur son utilisation : https://kripken.github.io/emscripten-site/docs/api_reference/module.html