HTML5 shell class reference

Projects exported for the Web expose the Engine class to the JavaScript environment, that allows fine control over the engine’s start-up process.

This API is built in an asynchronous manner and requires basic understanding of Promises.

Engine

The Engine class provides methods for loading and starting exported projects on the Web. For default export settings, this is already part of the exported HTML page. To understand practical use of the Engine class, see Custom HTML page for Web export.

Static Methods

Promise Engine.load ( string basePath )
void Engine.unload ( )
boolean Engine.isWebGLAvailable ( [ number majorVersion=1 ] )
void Engine.setWebAssemblyFilenameExtension ( string extension )

Instance Properties

Emscripten Module engine.rtenv

Instance Methods

Engine Engine ( )
Promise engine.init ( [ string basePath ] )
Promise engine.preloadFile ( string|ArrayBuffer file [, string path ] )
Promise engine.start ( [ string arg1, string arg2, … ] )
Promise engine.startGame ( string execName, string mainPack )
void engine.setUnloadAfterInit ( boolean enabled )
void engine.setCanvas ( HTMLCanvasElement canvasElem )
void engine.setCanvasResizedOnStart ( boolean enabled )
void engine.setLocale ( string locale )
void engine.setExecutableName ( string execName )
void engine.setProgressFunc ( function callback )
void engine.setStdoutFunc ( function callback )
void engine.setStderrFunc ( function callback )

Static Method Descriptions

Engine.load(basePath)

Load the engine from the specified base path.

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

Promise which resolves once the engine is loaded.
Engine.unload()

Unload the engine to free memory.

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

Engine.isWebGLAvailable([majorVersion = 1])

Check whether WebGL is available. Optionally, specify a particular version of WebGL to check for.

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

true if the given major version of WebGL is available, false otherwise.
Engine.setWebAssemblyFilenameExtension(extension)

Set an alternative filename extension for the WebAssembly module. By default it is assumed to be wasm.

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

Instance Property Descriptions

engine.rtenv

The runtime environment provided by Emscripten’s Module. For more information refer to the official documentation on Emscripten.

Instance Method Descriptions

class Engine()

Create a new instance of the Engine class.

engine.init([basePath])

Initialize the engine instance. Optionally, pass the base path to the engine to load it, if it hasn’t been loaded yet. See Engine.load().

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

Promise that resolves once the engine is loaded and initialized.
engine.preloadFile(file[, path])

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

Arguments:
  • file (string|ArrayBuffer) –

    If type is string, the file will be loaded from that path.

    If type is ArrayBuffer or a view on one, the buffer will used as the content of the file.

  • path (string) – Path by which the file will be accessible. Required, if file is not a string. If not passed, the path is derived from the URL of the loaded file.
Returns:

Promise that resolves once the file is loaded.
engine.start([arg1, arg2, …])

Start the instance of the engine, using the passed strings as command line arguments. engine.startGame() can be used in typical cases instead.

This will initialize the instance if it is not initialized. For manual initialization, see engine.init(). The engine must be loaded beforehand.

Fails if a canvas cannot be found on the page.

Arguments:
  • variadic (string) – Command line argument.
Returns:

Promise that resolves once the engine started.
engine.startGame(execName, mainPack)

Start the game instance using the given executable URL and main pack URL.

This will initialize the instance if it is not initialized. For manual initialization, see engine.init().

This will load the engine if it is not loaded. The base path of the executable URL will be used as the engine base path.

Arguments:
  • execName (string) – Executable name in a form of URL, omitting filename extension.
  • mainPack (string) – URL of the main pack to start the game.
Returns:

Promise that resolves once the game started.
engine.setUnloadAfterInit(enabled)

Specify whether the engine will be unloaded automatically after the instance is initialized. Enabled by default.

Arguments:
  • enabled (boolean) – true if the engine shall be unloaded after initializing, false otherwise.
engine.setCanvas(canvasElem)

Specify a canvas HTML element to use. By default, the first canvas element on the page is used for rendering.

Arguments:
  • canvasElem (HTMLCanvasElement) – The canvas element to use.
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.

Arguments:
  • enabled (boolean) – true if the canvas shall be resized on start, false otherwise.
engine.setLocale(locale)

Specify a language code to select the proper localization for the game.

See also

Complete list of supported locales.

Arguments:
  • locale (string) – Language code.
engine.setExecutableName(execName)

Specify the virtual filename of the executable. By default, the base name of the loaded engine files is used.

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

Arguments:
  • execName (string) – Executable name.
engine.setProgressFunc(callback)

Specify a callback function for displaying download progress. The callback function is called once per frame, so that the usage of requestAnimationFrame() is not necessary.

If the callback function receives a total amount of bytes as 0, this means that it is impossible to calculate. 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)
Arguments:
  • callback (function) – The callback function must accept two numeric arguments: the amount of bytes loaded so far, and the total number of bytes to load.
engine.setStdoutFunc(callback)

Specify a callback function for handling the standard output stream. This method should usually only be used in debug pages. By default, console.log() is used.

Arguments:
  • callback (function) – The callback function must accept one string argument: the message to print.
engine.setStderrFunc(callback)

Specify a callback function for handling the standard error stream. This method should usually only be used in debug pages. By default, console.warn() is used.

Arguments:
  • callback (function) – The callback function must accept one string argument: the message to print.