Customizing the Web export HTML page

Rather than the default HTML page that comes with the export templates, it is also possible to use a custom HTML page. This allows drastic customization of the final web presentation and behavior. The path to the custom HTML page is specified in the export options as Html/Custom Html Shell.

The default HTML page is available in the Godot Engine repository at /misc/dist/html/full-size.html. Some simple use-cases where customizing the default page is useful include:

• Loading files from a different directory
• Loading a .zip file instead of a .pck file as main pack
• Loading engine files from a different directory than the main pack file
• Adding a click-to-play button so games can be started in full-screen mode
• Loading some extra files before the engine starts, so they are available in the file system later
• Passing custom “command line” arguments, e.g. -s to start a MainLoop script

Another sample HTML page is available at /misc/dist/html/fixed-size.html. This page uses a fixed size canvas with an output widget below. However, the F12 browser console should be preferred as it can display additional information, such as WebGL errors.

Placeholder substitution

When exporting the game, several placeholders in the HTML page are replaced with values depending on the export:

The HTML file must evaluate the JavaScript file $GODOT_BASENAME.js. This file defines a global Engine object used to start the engine, see below for details.

The boot splash image is exported as $GODOT_BASENAME.png and can be used e.g. in <img /> elements.

$GODOT_DEBUG_ENABLED can be useful to optionally display e.g. an output console or other debug tools.

$GODOT_HEAD_INCLUDE is replaced with the string specified by the export option Html/Head Include.

The Engine object

The JavaScript global object Engine is defined by $GODOT_BASENAME.js and serves as an interface to the engine start-up process.

The API is based on and requires basic understanding of Promises.

The object itself has only the following methods:

Engine.``load(basePath)

Load the engine from the passed base path.

Engine.``unload()

Unload the engine to free memory.

This is called automatically once the engine is started unless explicitly disabled using engine.setUnloadAfterInit().

Engine.``isWebGLAvailable([majorVersion = 1])

Check whether WebGL is available.

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.

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.

Starting an Engine instance

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.

To start such an instance, the global Engine object must be loaded, then the engine instance must be initialized and finally started.

engine.``init([basePath])

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

engine.``preloadFile(file[, path])

Load a file so it is available in the file system once the instance runs. Must be called before starting the instance.

engine.``start([arg1, arg2, …])

Starts the instance of the engine, using the passed strings as command line arguments. This allows great control over how the engine is started, but usually the other methods starting with engine.start are simpler and should be used instead.

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.

engine.``startGame(mainPack)

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

If the engine isn’t loaded yet, the base path of the passed URL will be used to load the engine.

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

Configuring start-up behaviour

Beside starting the engine, other methods of the engine instance allow configuring the behavior:

engine.``setUnloadAfterInit(enabled)

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

This frees browser memory by unloading files that are no longer needed once the instance is initialized. However, if more instances of the engine will be started, the Engine will have to be loaded again.

Enabled by default.

engine.``setCanvas(canvasElem)

Specify a canvas to use.

By default, the first canvas element on the page is used for rendering.

engine.``setCanvasResizedOnStart(enabled)

Specifies whether the canvas will be resized to the width and height specified in the project settings on start.

Enabled by default.

engine.``setLocale(locale)

By default, the engine will try to guess the locale to use from the JavaScript environment. It is usually preferable to use a server-side user-specified locale, or at least use the locale requested in the HTTP Accept-Language header. This method allows specifying such a custom locale string.

For example, with PHP:

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

See also

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.

By default, the base name of the loaded engine files is used. This method allows specifying another name.

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

Customizing the presentation

The following methods are used to implement the presentation:

engine.``setProgressFunc(callback)

Set the callback for displaying download progress.

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

If the total is 0, it couldn’t be calculated. Possible reasons include:

• Files are delivered with server-side chunked compression
• Files are delivered with server-side compression on Chromium
• Not all file downloads have started yet (usually on servers without 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.

function printStdout(text) {
    console.log(text);
}
engine.setStdoutFunc(printStdout);

This method should usually only be used in debug pages. The $GODOT_DEBUG_ENABLED placeholder can be used to check for this.

By default, console.log() is used.

engine.``setStderrFunc(callback)

Specify the standard error stream callback.

function printStderr(text) {
    console.warn("Error: " + text);
}
engine.setStderrFunc(printStderr);

This method should usually only be used in debug pages. The $GODOT_DEBUG_ENABLED placeholder can be used to check for this.

By default, console.warn() is used.

Accessing the Emscripten Module

If you know what you’re doing, you can access the runtime environment (Emscripten’s Module) as engine.rtenv. Check the official Emscripten documentation for information on how to use it: https://kripken.github.io/emscripten-site/docs/api_reference/module.html