Work in progress

The content of this page was not yet updated for Godot 4.2 and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

Page HTML custom pour un export Web

Bien que les modèles d'exportation Web fournissent une page HTML par défaut entièrement capable de lancer le projet sans autre personnalisation, il peut être utile de créer une page HTML personnalisée. Bien que le jeu lui-même ne puisse pas encore être contrôlé directement de l'extérieur, une telle page permet de personnaliser le processus d'initialisation du moteur.

Quelques cas pratique où une telle page puisse être utile :

  • Chargement de fichiers à partir d'un répertoire différent de la page ;

  • Chargement d'un fichier .zip au lieu d'un fichier .pck comme paquet principal ;

  • Chargement du moteur à partir d'un répertoire différent de celui du fichier du pack principal ;

  • Ajout d'un bouton click-to-play pour que les jeux puissent être lancés en mode plein écran ;

  • Chargement de quelques fichiers supplémentaires avant le démarrage du moteur, en les rendant disponibles dans le système de fichiers du projet dès que possible ;

  • Passer des arguments de ligne de commande personnalisés, par exemple -s pour démarrer un script MainLoop.

La page HTML par défaut est disponible dans le dépôt du moteur Godot à /misc/dist/html/full-size.html mais le modèle suivant peut être utilisé comme un exemple beaucoup plus simple :

<!DOCTYPE html>
<html>
    <head>
        <title>My Template</title>
        <meta charset="UTF-8">
    </head>
    <body>
        <canvas id="canvas"></canvas>
        <script src="$GODOT_URL"></script>
        <script>
            var engine = new Engine($GODOT_CONFIG);
            engine.startGame();
        </script>
    </body>
</html>

Configuration

Comme le montre l'exemple ci-dessus, il s'agit principalement d'un document HTML ordinaire, avec quelques espaces réservés qui doivent être remplacés lors de l'exportation, un élément html <canvas>, et du code JavaScript simple qui appelle la classe Engine().

Les seuls caractères de remplacement requis sont :

  • $GODOT_URL : Le nom du fichier JavaScript principal, qui fournit la classe Engine() nécessaire au démarrage du moteur et qui doit être inclus dans le HTML sous la forme d'un <script>. Le nom est généré à partir de l'Export Path pendant le processus d'exportation.

  • $GODOT_CONFIG : Un objet JavaScript, contenant les options d'exportation et pouvant être surchargé par la suite. Voir EngineConfig pour la liste complète des surcharges.

The following optional placeholders will enable some extra features in your custom HTML template.

  • $GODOT_PROJECT_NAME : Le nom du projet tel que défini dans les paramètres du projet. C'est une bonne idée de l'utiliser comme <title> dans votre modèle.

  • $GODOT_HEAD_INCLUDE : Une chaîne de charactère customisée à inclure dans le document HTML, juste avant la fin du tag <head>. Elle est spécifié dans les options d'export dans la section Html / Head Include . Même si vous avez le contrôle total de la page HTML que vous créez, cette variable peut être utile pour configurer une partie des éléments tagué head depuis l'éditeur Godot. Par exemple, pour différents préreglages d'export Web.

Quand la page custom est prête, elle peut être sélectionné dans les options d'exports dans la section Html / Custom Html Shell.

../../../_images/html5_export_options.png

Démarrage du projet

To be able to start the game, you need to write a script that initializes the engine — the control code. This process consists of three steps, but as shown here, most of them can be skipped depending on how much customization is needed.

Voir la référence de la classe shell HTML5, pour la liste complète des méthodes et options disponibles.

Tout d'abord, le moteur doit être chargé, puis il doit être initialisé, et après cela, le projet peut enfin être lancé. Vous pouvez effectuer chacune de ces étapes manuellement et avec un grand contrôle. Cependant, dans le cas le plus simple, il suffit de créer une instance de la classe Engine() avec la configuration exportée, puis d'appeler la méthode engine.startGame en surchargeant éventuellement les paramètres EngineConfig.

const engine = new Engine($GODOT_CONFIG);
engine.startGame({
    /* optional override configuration, eg. */
    // unloadAfterInit: false,
    // canvasResizePolicy: 0,
    // ...
});

This snippet of code automatically loads and initializes the engine before starting the game. It uses the given configuration to load the engine. The engine.startGame method is asynchronous and returns a Promise. This allows your control code to track if the game was loaded correctly without blocking execution or relying on polling.

Si votre projet doit avoir un contrôle particulier sur les arguments de démarrage et les fichiers de dépendances, la méthode engine.start peut être utilisée à la place. Notez que cette méthode ne précharge pas automatiquement le fichier pck, vous voudrez donc probablement le précharger manuellement (et tout autre fichier supplémentaire) via la méthode engine.preloadFile.

En option, vous pouvez également utiliser manuellement engine.init pour effectuer des actions spécifiques après l'initialisation du module, mais avant le démarrage du moteur.

Ce processus est un peu plus complexe, mais vous permet de contrôler totalement le processus de démarrage du moteur.

const myWasm = 'mygame.wasm';
const myPck = 'mygame.pck';
const engine = new Engine();
Promise.all([
    // Load and init the engine
    engine.init(myWasm),
    // And the pck concurrently
    engine.preloadFile(myPck),
]).then(() => {
    // Now start the engine.
    return engine.start({ args: ['--main-pack', myPck] });
}).then(() => {
    console.log('Engine has started!');
});

Pour charger le moteur manuellement, la méthode statique Engine.load() doit être appelée. Comme cette méthode est statique, plusieurs instances de moteur peuvent être créées si elles partagent le même wasm.

Note

Des instances multiples ne peuvent pas être créées par défaut, car le moteur est immédiatement déchargé après son initialisation. Pour empêcher cela, utilisez l'option unloadAfterInit. Il est toujours possible de décharger le moteur manuellement en appelant la méthode statique Engine.unload(). Le déchargement du moteur libère la mémoire du navigateur en déchargeant les fichiers qui ne sont plus nécessaires une fois l'instance initialisée.

Personnaliser le comportement

Dans l'environnement web, plusieurs méthodes peuvent être utilisés pour garantir que le jeu fonctionne comme prévu.

Si vous ciblez une version spécifique de WebGL ou que voulez juste vérifier que WebGL est disponible tout court, vous pouvez appeler la méthode Engine.isWebGLAvailable(). Elle prends optionnellement un argument qui permet de faire un test pour une version majeur spécifique de WebGL.

Alors que le véritable fichier exécutable n'existe pas dans l'environnement Web, le moteur de jeu stocke seulement un nom de fichier virtuel, formé du nom de base des fichiers chargé du moteur. Cette valeur affecte les données de sorties de la méthode OS.get_executable_path() et défini le nom du paquet principal automatiquement démarré. L'option de substitution executable peut être utilisée pour remplacer cette valeur.

Personnalisation de la présentation

Plusieurs options de configuration peuvent être utilisées pour personnaliser davantage l'aspect et le comportement du jeu sur votre page.

Par défaut, le premier élément du canvas sur la page est utilisé pour le rendu graphique. Pour utiliser un élément canvas différent, la méthode canvas peut être utilisée. Elle nécessite une référence à l'élément DOM lui-même.

const canvasElement = document.querySelector("#my-canvas-element");
engine.startGame({ canvas: canvasElement });

La façon dont le moteur redimensionne le canevas peut être configurée via l’option de remplacement :js:attr:'canvasResizePolicy'.

Si le chargement de votre jeu prend un certain temps, il peut être utile d'afficher une interface de chargement personnalisée qui suit la progression. Cela peut être réalisé avec la méthode onProgress qui permet de mettre en place une fonction de rappel qui sera appelée régulièrement au fur et à mesure que le moteur charge de nouveaux octets.

function printProgress(current, total) {
    console.log("Loaded " + current + " of " + total + " bytes");
}
engine.startGame({ onProgress: printProgress });

Sachez que dans certains cas, total peut être 0. Cela signifie qu'il ne peut pas être calculé.

Si votre jeu prend en charge plusieurs langues, l'option de substitution locale peut être utilisée pour forcer un paramètre régional spécifique, à condition que vous disposiez d'un string de code de langue valide. Il peut être intéressant d'utiliser une logique côté serveur pour déterminer les langues préférées d'un utilisateur. Ainsi, le code de langue peut être extrait de l'en-tête HTTP Accept-Language, ou déterminé par un service GeoIP.

Débogage

Pour déboguer les projets exportés, il peut être utile de lire la sortie standard et les flux d'erreurs générés par le moteur. Ceci est similaire à la sortie affichée dans la fenêtre de la console de l'éditeur. Par défaut, les fichiers standard console.log et console.warn sont utilisés respectivement pour la sortie et le flux d'erreurs. Ce comportement peut être personnalisé en définissant vos propres fonctions pour traiter les messages.

Utilisez l'option de remplacement onPrint pour définir une fonction de rappel pour le flux de sortie, et l'option de remplacement onPrintError pour définir une fonction de rappel pour le flux d'erreur.

function print(text) {
    console.log(text);
}
function printError(text) {
    console.warn(text);
}
engine.startGame({ onPrint: print, onPrintError: printError });

When handling the engine output, keep in mind that it may not be desirable to print it out in the finished product.