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 scriptMainLoop
.
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 classeEngine()
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. VoirEngineConfig
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.
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.