HTML5 shell class reference
- Engine

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.