diff --git a/_static/css/custom.css b/_static/css/custom.css index 392595c9a..9f0c4273c 100644 --- a/_static/css/custom.css +++ b/_static/css/custom.css @@ -248,32 +248,74 @@ hr, border-color: var(--hr-color); } -/* Doesn't seem to be used on Read the Docs online builds, but is present when building locally */ +/* JavaScript documentation directives */ .rst-content dl:not(.docutils) dt { background-color: var(--admonition-note-background-color); border-color: var(--admonition-note-title-background-color); color: var(--admonition-note-color); } - -/* JavaScript documentation directives */ +.rst-content dl:not(.docutils) dl dt { + background-color: var(--admonition-attention-background-color); + border-color: var(--admonition-attention-title-background-color); + color: var(--admonition-attention-color); +} +.rst-content dl:not(.docutils).class dt, +.rst-content dl:not(.docutils).function dt, +.rst-content dl:not(.docutils).method dt, +.rst-content dl:not(.docutils).attribute dt { + width: 100%; +} +.rst-content dl:not(.docutils).class > dt, +.rst-content dl:not(.docutils).function > dt, +.rst-content dl:not(.docutils).method > dt, +.rst-content dl:not(.docutils).attribute > dt { + font-size: 100%; + font-weight: normal; + margin-bottom: 16px; + padding: 6px 8px; +} .rst-content dl:not(.docutils) tt.descclassname, .rst-content dl:not(.docutils) code.descclassname { - color: var(--highlight-type2-color) + color: var(--highlight-type2-color); + font-weight: normal; } .rst-content dl:not(.docutils) tt.descname, .rst-content dl:not(.docutils) code.descname { - color: var(--highlight-function-color) + color: var(--highlight-function-color); + font-weight: normal; } .rst-content dl:not(.docutils) .sig-paren, .rst-content dl:not(.docutils) .optional { - color: var(--highlight-operator-color) + color: var(--highlight-operator-color); + font-weight: normal; + padding: 0 2px; } +.rst-content dl:not(.docutils) .optional { + font-style: italic; +} +.rst-content dl:not(.docutils) .sig-param, .rst-content dl:not(.docutils).class dt > em, -.rst-content dl:not(.docutils).function dt > em { - color: var(--code-literal-color) +.rst-content dl:not(.docutils).function dt > em, +.rst-content dl:not(.docutils).method dt > em { + color: var(--code-literal-color); + font-style: normal; + padding: 0 4px; +} +.rst-content dl:not(.docutils) .sig-param, +.rst-content dl:not(.docutils).class dt > .optional ~ em, +.rst-content dl:not(.docutils).function dt > .optional ~ em, +.rst-content dl:not(.docutils).method dt > .optional ~ em { + color: var(--highlight-number-color); + font-style: italic; } .rst-content dl:not(.docutils).class dt > em.property { - color: var(--highlight-keyword-color) + color: var(--highlight-keyword-color); +} +.rst-content dl:not(.docutils) dt a.headerlink { + color: var(--link-color); +} +.rst-content dl:not(.docutils) dt a.headerlink:visited { + color: var(--link-color-visited); } footer, diff --git a/tutorials/platform/customizing_html5_shell.rst b/tutorials/platform/customizing_html5_shell.rst index d87dc9561..47743f811 100644 --- a/tutorials/platform/customizing_html5_shell.rst +++ b/tutorials/platform/customizing_html5_shell.rst @@ -1,355 +1,201 @@ .. _doc_customizing_html5_shell: -Customizing the Web export HTML page +Custom HTML page for Web export ==================================== -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``. +While Web export templates provide a default HTML page fully capable of launching +the project without any further customization, it may be beneficial to create a custom +HTML page. While the game itself cannot be directly controlled from the outside, +such page allows to customize the initialization process for the engine. + +Some use-cases where customizing the default page is useful include: + +- Loading files from a different directory than the page; +- Loading a ``.zip`` file instead of a ``.pck`` file as the main pack; +- Loading the engine from a different directory than the main pack file; +- Adding a click-to-play button so that games can be started in the fullscreen mode; +- Loading some extra files before the engine starts, making them available in + the project file system as soon as possible; +- Passing custom command line arguments, e.g. ``-s`` to start a ``MainLoop`` script. 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: +`/misc/dist/html/full-size.html `__ +and can be used as a reference implementation. Another sample HTML page is available at +`/misc/dist/html/fixed-size.html `__. +It differs from the default one by having a fixed size canvas area and an output widget below it. - - 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 +.. note:: It is recommended to use developer tools provided by browser vendors to debug + exported projects. Output generated by the engine may be limited and does not + include WebGL errors. -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. +Setup +----- +As evident by the default HTML page, it is mostly a regular HTML document. To work with +Godot projects it needs to be fully realized, to have a control code that calls +the :js:class:`Engine` class, and to provide places for several placeholders, which are +replaced with their actual values during export. -Placeholder substitution ------------------------- +.. image:: img/html5_export_options.png -When exporting the game, several placeholders in the HTML page are replaced -with values depending on the export: +- ``$GODOT_BASENAME``: + The base name from the *Export Path*, as set up in the export options; suffixes are omitted + (e.g. ``game.html`` becomes ``game``). This variable can be used to generate a path + to the main JavaScript file ``$GODOT_BASENAME.js``, which provides the :js:class:`Engine` + class. A splash image shown during the booting process can be accessed using this variable + as well: ``$GODOT_BASENAME.png``. -+------------------------------+-----------------------------------------------+ -| Placeholder | Substituted by | -+==============================+===============================================+ -| ``$GODOT_BASENAME`` | Basename of exported files without suffixes, | -| | e.g. ``game`` when exporting ``game.html`` | -+------------------------------+-----------------------------------------------+ -| ``$GODOT_DEBUG_ENABLED`` | ``true`` if debugging, ``false`` otherwise | -+------------------------------+-----------------------------------------------+ -| ``$GODOT_HEAD_INCLUDE`` | Custom string to include just before the end | -| | of the HTML ```` element | -+------------------------------+-----------------------------------------------+ +- ``$GODOT_HEAD_INCLUDE``: + A custom string to include in the HTML document just before the end of the ```` tag. It + is customized in the export options under the *Html / Head Include* section. While you fully + control the HTML page you create, this variable can be useful for configuring parts of the + HTML ``head`` element from the Godot Editor, e.g. for different Web export presets. -The HTML file must evaluate the JavaScript file ``$GODOT_BASENAME.js``. This -file defines a global ``Engine`` object used to start the engine, :ref:`see -below ` for details. +- ``$GODOT_DEBUG_ENABLED``: + A flag that tells if this is a debug build, or not. This variable is substituted by strings + ``true`` and ``false``, and can be used to disable debug branches within your control code. -The boot splash image is exported as ``$GODOT_BASENAME.png`` and can be used -e.g. in ```` elements. +When the custom page is ready, it can be selected in the export options under the *Html / Custom Html Shell* +section. -``$GODOT_DEBUG_ENABLED`` can be useful to optionally display e.g. an output -console or other debug tools. +Starting the project +-------------------- +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, though some of them can be skipped and left for +a default behavior. -``$GODOT_HEAD_INCLUDE`` is replaced with the string specified by the export -option ``Html/Head Include``. - -.. _doc_javascript_engine_object: - -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: - -.. js:function:: Engine.load(basePath) - - Load the engine from the passed base path. - - :param string basePath: Base path of the engine to load. - :returns: Promise which resolves once the engine is loaded. - -.. js:function:: Engine.unload() - - Unload the engine to free memory. - - This is called automatically once the engine is started unless - explicitly disabled using :js:func:`engine.setUnloadAfterInit`. - -.. js:function:: Engine.isWebGLAvailable([majorVersion = 1]) - - Check whether WebGL is available. - - :param number majorVersion: - 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. - -.. js:function:: 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. - - .. code-block:: js - - 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. - - :param string extension: - Filename extension without preceding dot. - - .. 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 :mimetype:`application/wasm`. - -Starting an ``Engine`` instance -------------------------------- - -:js:class:`Engine` also acts a class: - -.. js:class:: Engine - - An instance of the engine that can be started, usually a game. - -Instantiate the class using the ``new`` operator: +First, the engine must be loaded, then it needs to be initialized, and after this the project +can finally be started. You can perform every of these steps manually and with great control. +However, in the simplest case all you need to do is to create an instance of the :js:class:`Engine` +class and then call the :js:meth:`engine.startGame` method. .. code-block:: js - var engine = new Engine(); + const execName = "path://to/executable" + const mainPack = "path://to/main_pack" -This yields an :js:class:`Engine` instance, referred to as ``engine`` with a -lower-case ``e`` from here. + const engine = new Engine(); + engine.startGame(execName, mainPack) -To start such an instance, the global ``Engine`` object must be loaded, -then the ``engine`` instance must be initialized and finally started. +This snippet of code automatically loads and initializes the engine before starting the game. +It uses the given path to the executable to deduce the path to load the engine. The :js:meth:`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. -.. js:function:: engine.init([basePath]) +In case your project needs to have special arguments passed to it by the start-up script, +:js:meth:`engine.startGame` can be replaced by :js:meth:`engine.start`. This method takes an +arbitrary list of string arguments. As it does not have a defined list of arguments, :js:meth:`engine.start` +cannot automatically load the engine. - Initialize the instance. The instance can then be started with one of the - ``start`` functions, usually :js:func:`engine.startGame`. +To load the engine manually the :js:meth:`Engine.load` static method must be called. As +this method is static, multiple engine instances can be spawned with the exact same ``basePath``. +If an instance requires a different ``basePath``, you can call the :js:meth:`engine.init` +method with that path before starting the game. - :param string basePath: - The base path to the engine, same as in :js:func:`Engine.load`. - Must be passed only if the engine hasn't been loaded yet. +.. note:: Multiple instances cannot be spawned by default, as the engine is immediately unloaded after it is initialized. + To prevent this from happening the :js:meth:`engine.setUnloadAfterInit` method can be called. It is still possible + to unload the engine manually afterwards by calling the :js:meth:`Engine.unload` static method. Unloading the engine + frees browser memory by unloading files that are no longer needed once the instance is initialized. - :returns: Promise that resolves once the engine is loaded and initialized. +To correctly load the engine on some hosting providers and network configurations you may +need to change the default filename extension by using :js:meth:`Engine.setWebAssemblyFilenameExtension`. +By default, the extension is assumed to be ``wasm``. If your hosting provider blocks this +extension, this static method can be used to change it to something that is supported. -.. js:function:: engine.preloadFile(file[, path]) +.. code-block:: js - Load a file so it is available in the file system once the instance runs. Must - be called **before** starting the instance. + Engine.setWebAssemblyFilenameExtension("dat"); + // Load mygame.dat as WebAssembly module. + Engine.load("mygame"); - :param file: - If type is string, the file will be loaded from that path. +.. warning:: If a different filename extension is used, some web servers may automatically + set the MIME-type of the file to something other than :mimetype:`application/wasm`. + In that case some start-up optimizations may be skipped. - If type is ``ArrayBuffer`` or a view on one, the buffer will used as - the content of the file. +Customizing the behavior +------------------------ +In the Web environment several methods can be used to guarantee that the game will work as intended. - :param string path: - Path by which the file will be available. Mandatory if ``file`` is not - a string. If not passed, the path is derived from the URL of the loaded - file. +If you target a specific version of WebGL, or just want to check if WebGL is available at all, +you can call the :js:meth:`Engine.isWebGLAvailable` method. It optionally takes an argument that +allows to test for a specific major version of WebGL. - :returns: Promise that resolves once the file is preloaded. +As the real executable file does not exist in the Web environment, the engine only stores a virtual +filename formed from the base name of loaded engine files. This value affects the output of the +:ref:`OS.get_executable_path() ` method and defines the name of +the automatically started main pack. The :js:meth:`engine.setExecutableName` method can be used +to override this value. -.. js:function:: 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 :js:func:`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. - - :param string variadic: Command line arguments. - - :returns: Promise that resolves once the engine started. - -.. js:function:: engine.startGame(execName, mainPack) - - Initializes the engine if not yet initialized, loads the executable, - 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 executable name - will be used to load the engine. - - :param string execName: - Executable's name (URL) to start. Also used as base path to load the - engine if not loaded already. Should not contain the file's extension. - - :param string mainPack: - Path (URL) to the main pack to start. - - :returns: Promise that resolves once the game started. - -Configuring start-up behaviour ------------------------------- - -Beside starting the engine, other methods of the engine instance allow -configuring the behavior: - -.. js:function:: 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. - - :param boolean enabled: - ``true`` if the engine shall be unloaded after initializing, - ``false`` otherwise. - -.. js:function:: engine.setCanvas(canvasElem) - - Specify a canvas to use. - - By default, the first canvas element on the page is used for rendering. - - :param HTMLCanvasElement canvasElem: The canvas to use. - -.. js:function:: 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. - - :param boolean enabled: - ``true`` if the canvas shall be resized on start, ``false`` otherwise. - -.. js:function:: 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: - - .. code-block:: php - - engine.setLocale(); - - :param string locale: - Locale. - - .. seealso:: List of :ref:`locales `. - -.. js:function:: 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 :ref:`OS.get_executable_path() ` - and the automatically started main pack, :file:`{ExecutableName}.pck`. - - :param string execName: Executable name. +If your project requires some files to be available the moment it is loaded, you can preload +them by calling the :js:meth:`engine.preloadFile` method with a path to a file or by providing it +with an ``ArrayBuffer`` object. In case of the ``ArrayBuffer``, or one of its views, a second argument +must be specified to define an internal path for the loaded resource. Customizing the presentation ---------------------------- +Several methods can be used to further customize the look and behavior of the game on your page. -The following methods are used to implement the presentation: +By default, the first canvas element on the page is used for rendering. To use a different canvas +element the :js:meth:`engine.setCanvas` method can be used. It requires a reference to the DOM +element itself. -.. js:function:: engine.setProgressFunc(callback) +.. code-block:: js - Set the callback for displaying download progress. + const canvasElement = document.querySelector("#my-canvas-element"); + engine.setCanvas(canvasElement); - :param function callback: - Callback called once per frame with two number arguments: - bytes loaded so far, and total bytes to load. +If the width and height of this canvas element differ from values set in the project settings, it +will be resized on the project start. This behavior can be disabled by calling the :js:meth:`engine.setCanvasResizedOnStart` +method. - .. code-block:: js +If your game takes some time to load, it may be useful to display a custom loading UI which tracks +the progress. This can be achieved with the :js:meth:`engine.setProgressFunc` method which allows +to set up a callback function to be called regularly as the engine loads new bytes. - function printProgress(current, total) { - console.log("Loaded " + current + " of " + total + " bytes"); - } - engine.setProgressFunc(printProgress); +.. code-block:: js - If the total is 0, it couldn't be calculated. Possible reasons - include: + function printProgress(current, total) { + console.log("Loaded " + current + " of " + total + " bytes"); + } + engine.setProgressFunc(printProgress); - - 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) +Be aware that in some cases ``total`` can be ``0``. This means that it cannot be calculated. - .. Note:: - For ease of use, the callback is only called once per frame, so that usage - of ``requestAnimationFrame()`` is not necessary. +If your game supports multiple languages, the :js:meth:`engine.setLocale` method can be used to set +a specific locale, provided you have a valid language code string. It may be good to use server-side +logic to determine which languages a user may prefer. This way the language code can be taken from the +``Accept-Language`` HTTP header, or determined by a GeoIP service. -.. js:function:: engine.setStdoutFunc(callback) +Debugging +--------- +To debug exported projects, it may be useful to read the standard output and error streams generated +by the engine. This is similar to the output shown in the editor console window. By default, standard +``console.log`` and ``console.warn`` are used for the output and error streams respectively. This +behavior can be customized by setting your own functions to handle messages. - Specify the standard output stream callback. +Use the :js:meth:`engine.setStdoutFunc` method to set a callback function for the output stream. Default +behavior is similar to this: - :param function callback: - Callback function called with one argument, the string to print. +.. code-block:: js - .. code-block:: js + function printStdout(text) { + console.log(text); + } + engine.setStdoutFunc(printStdout); - function printStdout(text) { - console.log(text); - } - engine.setStdoutFunc(printStdout); +Use the :js:meth:`engine.setStderrFunc` method to set a callback function for the error stream. Default +behavior is similar to this: - This method should usually only be used in debug pages. The - ``$GODOT_DEBUG_ENABLED`` placeholder can be used to check for this. +.. code-block:: js - By default, ``console.log()`` is used. + function printStderr(text) { + console.warn("Error: " + text); + } + engine.setStderrFunc(printStderr); -.. js:function:: engine.setStderrFunc(callback) +When handling the engine output keep in mind, that it may not be desirable to print it out in the +finished product. To control whether or not the current execution is actually a debug build you can +use ``$GODOT_DEBUG_ENABLED`` placeholder. - Specify the standard error stream callback. - - :param function callback: - Callback function called with one argument, the string to print. - - .. code-block:: js - - 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 +Further debugging options and a low level access to the execution environment are available in a form +of Emscripten's ``Module`` object. It can be accessed using the :js:attr:`engine.rtenv` property on the +engine instance. diff --git a/tutorials/platform/html5_shell_classref.rst b/tutorials/platform/html5_shell_classref.rst new file mode 100644 index 000000000..1e1a4e90a --- /dev/null +++ b/tutorials/platform/html5_shell_classref.rst @@ -0,0 +1,266 @@ +.. _doc_html5_shell_classref: + +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 :ref:`Custom HTML page for Web export `. + +Static Methods +^^^^^^^^^^^^^^ + ++---------+-------------------------------------------------------------------------------------------------------------------+ +| Promise | `Engine.load <#Engine.load>`__ **(** string basePath **)** | ++---------+-------------------------------------------------------------------------------------------------------------------+ +| void | `Engine.unload <#Engine.unload>`__ **(** **)** | ++---------+-------------------------------------------------------------------------------------------------------------------+ +| boolean | `Engine.isWebGLAvailable <#Engine.isWebGLAvailable>`__ **(** *[ number majorVersion=1 ]* **)** | ++---------+-------------------------------------------------------------------------------------------------------------------+ +| void | `Engine.setWebAssemblyFilenameExtension <#Engine.setWebAssemblyFilenameExtension>`__ **(** string extension **)** | ++---------+-------------------------------------------------------------------------------------------------------------------+ + +Instance Properties +^^^^^^^^^^^^^^^^^^^ + ++-----------------------+----------------------------------+ +| Emscripten ``Module`` | `engine.rtenv <#engine.rtenv>`__ | ++-----------------------+----------------------------------+ + +Instance Methods +^^^^^^^^^^^^^^^^ + ++---------+------------------------------------------------------------------------------------------------------+ +| Engine | `Engine <#Engine>`__ **(** **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| Promise | `engine.init <#engine.init>`__ **(** *[ string basePath ]* **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| Promise | `engine.preloadFile <#engine.preloadFile>`__ **(** string\|ArrayBuffer file *[, string path ]* **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| Promise | `engine.start <#engine.start>`__ **(** *[ string arg1, string arg2, … ]* **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| Promise | `engine.startGame <#engine.startGame>`__ **(** string execName, string mainPack **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| void | `engine.setUnloadAfterInit <#engine.setUnloadAfterInit>`__ **(** boolean enabled **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| void | `engine.setCanvas <#engine.setCanvas>`__ **(** HTMLCanvasElement canvasElem **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| void | `engine.setCanvasResizedOnStart <#engine.setCanvasResizedOnStart>`__ **(** boolean enabled **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| void | `engine.setLocale <#engine.setLocale>`__ **(** string locale **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| void | `engine.setExecutableName <#engine.setExecutableName>`__ **(** string execName **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| void | `engine.setProgressFunc <#engine.setProgressFunc>`__ **(** function callback **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| void | `engine.setStdoutFunc <#engine.setStdoutFunc>`__ **(** function callback **)** | ++---------+------------------------------------------------------------------------------------------------------+ +| void | `engine.setStderrFunc <#engine.setStderrFunc>`__ **(** function callback **)** | ++---------+------------------------------------------------------------------------------------------------------+ + + +Static Method Descriptions +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. js:method:: Engine.load(basePath) + + Load the engine from the specified base path. + + :param string basePath: + Base path of the engine to load. + :returns: + Promise which resolves once the engine is loaded. + +.. js:method:: Engine.unload() + + Unload the engine to free memory. + + This method is called automatically once the engine is started unless + explicitly disabled using :js:meth:`engine.setUnloadAfterInit`. + +.. js:method:: Engine.isWebGLAvailable([majorVersion = 1]) + + Check whether WebGL is available. Optionally, specify a particular version of WebGL to check for. + + :param number majorVersion: + 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. + +.. js:method:: Engine.setWebAssemblyFilenameExtension(extension) + + Set an alternative filename extension for the WebAssembly module. By default + it is assumed to be ``wasm``. + + :param string extension: + Filename extension without preceding dot. + + +Instance Property Descriptions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. js:attribute:: engine.rtenv + + The runtime environment provided by Emscripten's ``Module``. For more information + refer to the `official documentation `__ on Emscripten. + +Instance Method Descriptions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. js:class:: Engine + + Create a new instance of the ``Engine`` class. + +.. js:method:: 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 :js:meth:`Engine.load`. + + :param string basePath: + Base path of the engine to load. + + :returns: + Promise that resolves once the engine is loaded and initialized. + +.. js:method:: 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. + + :param string|ArrayBuffer file: + 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. + + :param string path: + 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. + +.. js:method:: engine.start([arg1, arg2, …]) + + Start the instance of the engine, using the passed strings as + command line arguments. :js:meth:`engine.startGame` can be used + in typical cases instead. + + This will initialize the instance if it is not initialized. For manual + initialization, see :js:meth:`engine.init`. The engine must be loaded beforehand. + + Fails if a canvas cannot be found on the page. + + :param string variadic: + Command line argument. + + :returns: + Promise that resolves once the engine started. + +.. js:method:: 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 :js:meth:`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. + + :param string execName: + Executable name in a form of URL, omitting filename extension. + + :param string mainPack: + URL of the main pack to start the game. + + :returns: + Promise that resolves once the game started. + +.. js:method:: engine.setUnloadAfterInit(enabled) + + Specify whether the engine will be unloaded automatically after the + instance is initialized. Enabled by default. + + :param boolean enabled: + ``true`` if the engine shall be unloaded after initializing, + ``false`` otherwise. + +.. js:method:: engine.setCanvas(canvasElem) + + Specify a canvas HTML element to use. By default, the first canvas element + on the page is used for rendering. + + :param HTMLCanvasElement canvasElem: + The canvas element to use. + +.. js:method:: 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. + + :param boolean enabled: + ``true`` if the canvas shall be resized on start, ``false`` otherwise. + +.. js:method:: engine.setLocale(locale) + + Specify a language code to select the proper localization for the game. + + .. seealso:: Complete list of :ref:`supported locales `. + + :param string locale: + Language code. + +.. js:method:: 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 :ref:`OS.get_executable_path() ` + and sets the automatically started main pack to :file:`{ExecutableName}.pck`. + + :param string execName: + Executable name. + +.. js:method:: 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) + + :param function callback: + The callback function must accept two numeric arguments: the amount of bytes + loaded so far, and the total number of bytes to load. + +.. js:method:: 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. + + :param function callback: + The callback function must accept one string argument: the message to print. + +.. js:method:: 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. + + :param function callback: + The callback function must accept one string argument: the message to print. diff --git a/tutorials/platform/img/html5_export_options.png b/tutorials/platform/img/html5_export_options.png new file mode 100644 index 000000000..27eeebe15 Binary files /dev/null and b/tutorials/platform/img/html5_export_options.png differ diff --git a/tutorials/platform/index.rst b/tutorials/platform/index.rst index cf661b5de..0683cabbf 100644 --- a/tutorials/platform/index.rst +++ b/tutorials/platform/index.rst @@ -7,5 +7,5 @@ Platform-specific android_in_app_purchases services_for_ios - customizing_html5_shell + platform_html5 consoles diff --git a/tutorials/platform/platform_html5.rst b/tutorials/platform/platform_html5.rst new file mode 100644 index 000000000..2bf6cdd67 --- /dev/null +++ b/tutorials/platform/platform_html5.rst @@ -0,0 +1,11 @@ +.. _doc_platform_html5: + +HTML5 +===== + +.. toctree:: + :maxdepth: 1 + :name: toc-learn-features-platform-html5 + + html5_shell_classref + customizing_html5_shell