Update HTML5 platform docs

development/compiling/compiling_for_web.rst

@@ -10,7 +10,7 @@ Requirements
 
 To compile export templates for the Web, the following is required:
 
--  `Emscripten 1.37.9+ <http://kripken.github.io/emscripten-site>`__: If the version available
+-  `Emscripten 1.38.22+ <http://kripken.github.io/emscripten-site>`__: If the version available
    per package manager is not recent enough, the best alternative is to install
    using the `Emscripten SDK <http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html>`__
 -  `Python 2.7+ or Python 3.5+ <https://www.python.org/>`__
@@ -29,6 +29,11 @@ written by the Emscripten SDK, e.g. when invoking ``emsdk activate latest``,
 or by your package manager. It's also created when starting Emscripten's
 ``emcc`` program if the file doesn't exist.
 
+.. Attention::
+ On Windows, make sure to escape backslashes of paths within the Emscripten
+ configuration file as double backslashes ``\\`` or use Unix-style paths with a
+ single forward slash ``/``.
+
 Open a terminal and navigate to the root directory of the engine source code.
 Then instruct SCons to build the JavaScript platform. Specify ``target`` as
 either ``release`` for a release build or ``release_debug`` for a debug build::
@@ -66,18 +71,13 @@ asm.js, a highly optimizable subset of JavaScript, using Emscripten's
 tool called ``asm2wasm``. Emscripten automatically takes care of both
 processes, we simply run SCons.
 
-The other method uses LLVM's WebAssembly backend. This backend is not yet
-available in release versions of LLVM, only in development builds built with
-``LLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``.
-Compiling with this backend outputs files in LLVM's ``.s`` format, which is
-translated into actual WebAssembly using a tool called ``s2wasm``.
-Emscripten manages these processes as well, so we just invoke SCons.
+The other method uses LLVM's WebAssembly backend. This backend is available
+starting with LLVM 8 or in development builds.
+Emscripten manages this process as well, so we just invoke SCons.
 
 In order to choose one of the two methods, the ``LLVM_ROOT`` variable in the
 Emscripten configuration file is used. If it points to a directory containing
 binaries of Emscripten's *fastcomp* fork of clang, ``asm2wasm`` is used.
 This is the default in a normal Emscripten installation. Otherwise,
 LLVM binaries built with the WebAssembly backend will be expected and
-``s2wasm`` is used. On Windows, make sure to escape backslashes of paths within
-this file as double backslashes ``\\`` or use Unix-style paths with a single
-forward slash ``/``.
+the LLVM's WebAssembly backend is used.

getting_started/workflow/export/customizing_html5_shell.rst

@@ -1,238 +0,0 @@
-.. _doc_customizing_html5_shell:
-
-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/default.html <https://github.com/godotengine/godot/blob/master/misc/dist/html/default.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
- - 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
-
-Placeholder substitution
-------------------------
-
-When exporting the game, several placeholders in the HTML page are replaced
-with values depending on the export:
-
-+------------------------------+-----------------------------------------------+
-| 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 ``<head>`` element                |
-+------------------------------+-----------------------------------------------+
-
-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 <doc_javascript_engine_object>` 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``.
-
-.. _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 object itself has only two methods, ``load()`` and ``unload()``.
-
-``Engine.load(basePath)``
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Loads the engine from the passed base path.
-
-Returns a promise that resolves once the engine is loaded.
-
-``Engine.unload()``
-~~~~~~~~~~~~~~~~~~~
-
-Unloads the module to free memory. This is called automatically once the
-module is instantiated unless explicitly disabled.
-
-``Engine.isWebGLAvailable(majorVersion = 1)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Returns ``true`` if the given major version of WebGL is available,
-``false`` otherwise. Defaults to ``1`` for WebGL 1.0.
-
-Starting an ``Engine`` instance
--------------------------------
-
-The more interesting interface is accessed by instantiating ``Engine`` using
-the ``new`` operator:
-
-.. code-block:: js
-
-    var engine = new Engine();
-
-This ``Engine`` instance, referred to as ``engine`` with a lower-case ``e``
-from here, is a startable instance of the engine, usually a game. To start such
-an instance, the global ``Engine`` object must be loaded, then the ``engine``
-instance must be initialized and started.
-
-``engine.init(basePath)``
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Initializes the instance. If the engine wasn't loaded yet, a base path
-must be passed from which the engine will be loaded.
-
-Returns a promise that resolves once the engine is loaded and initialized.
-It can then be started with ``engine.startGame()``
-
-``engine.preloadFile(file, path)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This loads a file so it is available in the file system once the instance
-is started. This must be called **before** starting the instance.
-
-If ``file`` is a string, the file will be loaded from that URL. If ``file`` is
-an ``ArrayBuffer`` or a view on one, the buffer will used as the content of the
-file.
-
-If ``path`` is a string, it specifies the path by which the file will be
-available. This is mandatory if ``file`` is not a string.
-Otherwise, the path is derived from the URL of the loaded file.
-
-Returns a promise that resolves once the file is preloaded.
-
-``engine.start(arg1, arg2, …)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Starts the instance of the engine, handing the passed strings as arguments
-to the ``main()`` function. This allows great control over how the engine
-is used, but usually the other methods whose names start with ``engine.start``
-are simpler to use.
-
-Returns a promise that resolves once the engine started.
-
-``engine.startGame(mainPack)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Starts the game with the main pack loaded from the passed URL string and
-starts the engine with it.
-
-If the engine isn't loaded yet, the base path of the passed URL will be
-used to load the engine.
-
-Returns a 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:
-
-``engine.setUnloadAfterInit(enabled)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sets 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.
-
-Defaults to ``true``.
-
-``engine.setCanvas(canvasElem)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default, the first canvas element on the page is used for rendering.
-By calling this method, another canvas can be specified.
-
-``engine.setCanvasResizedOnStart(enabled)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sets whether the canvas will be resized to the width and height specified
-in the project settings on start. Defaults to ``true``.
-
-``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.
-
-``engine.setExecutableName(execName)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default, the base name of the loaded engine files is used for the
-executable name. This method allows specifying another name.
-
-Customizing the presentation
-----------------------------
-
-The following methods are used to implement the presentation:
-
-``engine.setProgressFunc(func)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This method is used to display download progress. The passed callback
-function is called with two number arguments, the first argument specifies
-bytes loaded so far, the second argument specifies the total number of bytes
-to load.
-
-.. code-block:: js
-
-    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)
-
-``engine.setStdoutFunc(func)``, ``engine.setStderrFunc(func)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-These methods allow implementing custom behavior for the ``stdout`` and
-``stderr`` streams. The functions passed in will be called with one string
-argument specifying the string to print.
-
-.. code-block:: js
-
-    function printStderr(text) {
-        console.warn("Error: " + text);
-    }
-    engine.setStderrFunc(printStderr);
-
-These methods should usually only be used in debug pages. The
-``$GODOT_DEBUG_ENABLED`` placeholder can be used to check for this.
-
-By default, ``console.log()`` and ``console.warn()`` are used respectively.
-
-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

getting_started/workflow/export/exporting_for_web.rst

@@ -4,12 +4,40 @@ Exporting for the Web
 =====================
 
 HTML5 export allows publishing games made in Godot Engine to the browser.
-This requires support for the recent technologies `WebAssembly
-<https://webassembly.org/>`__ and `WebGL 2.0 <https://www.khronos.org/webgl/>`__
-in the user's browser. **Firefox** and **Chromium** (Chrome, Opera) are
-the most popular supported browsers, **Safari** and **Edge** do not work yet.
-On **iOS**, all browsers must be based on WebKit (i.e. Safari), so they will also
-not work.
+This requires support for `WebAssembly
+<https://webassembly.org/>`__ and `WebGL <https://www.khronos.org/webgl/>`__
+in the user's browser.
+
+.. Important::
+ Use the browser-integrated developer console, usually opened with :kbd:`F12`,
+ to view **debug information** like JavaScript, engine, and WebGL errors.
+
+.. Attention::
+ Many browsers, Chromium-based browsers specifically, will not load exported
+ projects when **opened locally** per ``file://`` protocol. To get around this,
+ use a local server.
+
+ .. Tip::
+  Python offers an easy method to start a local server. Use
+  ``python -m SimpleHTTPServer`` with Python 2 or ``python -m http.server`` with
+  Python 3 to serve the current working directory at ``http://localhost:8000``.
+
+WebGL 2
+-------
+
+Until the *OpenGL ES 3* renderer is removed from Godot in favor of *Vulkan*,
+HTML5 export uses *WebGL 2* when the *GLES3* option selected.
+
+.. Warning::
+ Usage of WebGL 2 is not recommended due to its expected removal from Godot
+ without replacement.
+
+WebGL 2 is not supported in all browsers. **Firefox** and
+**Chromium** (Chrome, Opera) are the most popular supported browsers,
+**Safari** and **Edge** do not work. On **iOS**, all browsers are based on
+WebKit (i.e. Safari), so they will also not work.
+
+Godot's WebGL 2 renderer has issues with 3D and is no longer maintained.
 
 Limitations
 -----------
@@ -18,13 +46,6 @@ For security and privacy reasons, many features that work effortlessly on
 native platforms are more complicated on the web platform. Following is a list
 of limitations you should be aware of when porting a Godot game to the web.
 
-Exported ``.html`` file must not be reused
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-On export, several text placeholders are replaced in the **generated HTML
-file** specifically for the given export options. It must not be reused in
-further exports.
-
 Using cookies for data persistence
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -40,26 +61,51 @@ cases.
 Full screen and mouse capture
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Browsers do not allow arbitrarily **entering full screen** at any time. The same
-goes for **capturing the cursor**. Instead, these actions have to occur as a
-response to a JavaScript input event. In Godot, this is most easily done by
-entering full screen from within an input callback such as ``_input`` or
-``_unhandled_input``.
+Browsers do not allow arbitrarily **entering full screen**. The same goes for
+**capturing the cursor**. Instead, these actions have to occur as a response to
+a JavaScript input event. In Godot, this means entering full screen from within
+a pressed input event callback such as ``_input`` or ``_unhandled_input``.
+Querying the :ref:`class_Input` singleton is not sufficient, the relevant
+input event must currently be active.
+
+For the same reason, the full screen project setting doesn't work unless the
+engine is started from within a valid input event handler. This requires
+:ref:`customization of the HTML page <doc_customizing_html5_shell>`.
+
+Audio autoplay
+~~~~~~~~~~~~~~
 
-For the same reason, the full screen project setting is ignored.
+Chrome restricts how websites may play audio. It may be necessary for the
+player to click or tap or press a key to enable audio.
 
-HTTPClient
-~~~~~~~~~~
+.. seealso::
+ Google offers additional information about their `Web Audio autoplay policies <https://sites.google.com/a/chromium.org/dev/audio-video/autoplay>`__.
 
-The ``HTTPClient`` implementation for the HTML5 platform has several
-restrictions:
+:ref:`class_HTTPClient` and :ref:`class_HTTPRequest`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The HTTP classes have several restrictions on the HTML5 platform:
 
  -  Accessing or changing the ``StreamPeer`` is not possible
- -  Blocking mode is not available
+ -  Threaded/Blocking mode is not available
  -  Cannot progress more than once per frame, so polling in a loop will freeze
  -  No chunked responses
  -  Host verification cannot be disabled
- -  Subject to `same-origin policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`_
+ -  Subject to `same-origin policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`__
+
+Exported ``.html`` file must not be reused
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+On export, several text placeholders are replaced in the **generated HTML
+file** specifically for the given export options. It must not be reused in
+further exports.
+
+Boot splash is not displayed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The default HTML page does not display the boot splash while loading. However,
+the image is exported as a PNG file, so :ref:`custom HTML pages <doc_customizing_html5_shell>`
+can display it.
 
 Unimplemented functionality
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -68,23 +114,14 @@ The following functionality is currently unavailable on the HTML5 platform:
 
  -  Threads
  -  GDNative
+ -  C#
  -  Clipboard synchronisation between engine and operating system
- -  Networking other than ``HTTPClient``
-
-Check the `list of open HTML5 issues on Github <https://github.com/godotengine/godot/issues?q=is:open+is:issue+label:platform:html5>`_
-to see if functionality you're interested in has an issue yet. If not, open one
-to communicate your interest.
-
-Starting exported games from the local file system
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ -  Networking other than :ref:`class_HTTPClient` and :ref:`class_WebSocketClient`
 
-Many browsers, Chromium-based browsers specifically, will not load exported
-projects when **opened locally** per ``file://`` protocol. To get around this,
-use a local server.
-
-Python offers an easy method for this; using ``python -m SimpleHTTPServer``
-with Python 2 or ``python -m http.server`` with Python 3 will serve the current
-working directory on ``http://localhost:8000``.
+.. Tip::
+ Check the `list of open HTML5 issues on Github <https://github.com/godotengine/godot/issues?q=is:open+is:issue+label:platform:html5>`__
+ to see if functionality you're interested in has an issue yet. If not, open
+ one to communicate your interest.
 
 Serving the files
 -----------------
@@ -97,8 +134,7 @@ The generated ``.html`` file can be used as ``DirectoryIndex`` in Apache
 servers and can be renamed to e.g. ``index.html`` at any time, its name is
 never depended on by default.
 
-The HTML page is designed to fit the game perfectly without cutting off
-parts of the canvas when the browser window is scaled to the game's dimensions.
+The HTML page draws the game at maximum size within the browser window.
 This way it can be inserted into an ``<iframe>`` with the game's size, as is
 common on most web game hosting sites.
 
@@ -111,8 +147,12 @@ the default HTML page, but is included for
 :ref:`custom HTML pages <doc_customizing_html5_shell>`.
 
 The ``.pck`` file is binary, usually delivered with the MIME-type
-``application/octet-stream``. The ``.wasm`` file is delivered as
-``application/wasm``.
+:mimetype:`application/octet-stream`. The ``.wasm`` file is delivered as
+:mimetype:`application/wasm`.
+
+.. Caution::
+ Delivering the WebAssembly module (``.wasm``) with a MIME-type other than
+ :mimetype:`application/wasm` can prevent some start-up optimizations.
 
 Delivering the files with server-side compression is recommended especially for
 the ``.pck`` and ``.wasm`` files, which are usually large in size.
@@ -133,18 +173,12 @@ the default HTML page. See :ref:`doc_customizing_html5_shell`.
 HTML page. This allows to, for example, load webfonts and third-party
 JavaScript APIs, include CSS, or run JavaScript code.
 
-Turning on **Export with Debug** when exporting will, in addition to enabling
-various debug features of the engine, display a debug output below the canvas
-when using the default HTML page, displaying JavaScript and engine errors.
-You can also use the browser-integrated developer console, usually opened with
-the F12 key, which often shows more information, including WebGL errors.
-
 .. _doc_javascript_eval:
 
 Calling JavaScript from script
 ------------------------------
 
-In web builds, the ``JavaScript`` singleton is implemented. If offers a single
+In web builds, the ``JavaScript`` singleton is implemented. It offers a single
 method called ``eval`` that works similarly to the JavaScript function of the
 same name. It takes a string as an argument and executes it as JavaScript code.
 This allows interacting with the browser in ways not possible with script
@@ -179,10 +213,16 @@ also return ``null``.  The availability of the singleton can be checked with the
 
     func my_func3():
         if OS.has_feature('JavaScript'):
-            JavaScript.eval("console.log('The JavaScript singleton is available')")
+            JavaScript.eval("""
+                console.log('The JavaScript singleton is available')
+            """)
         else:
             print("The JavaScript singleton is NOT available")
 
+.. Tip::
+ GDScript's multi-line strings, surrounded by 3 quotes ``"""`` as in
+ ``my_func3()`` above, are useful to keep JavaScript code readable.
+
 The ``eval`` method also accepts a second, optional Boolean argument, which
 specifies whether to execute the code in the global execution context,
 defaulting to ``false`` to prevent polluting the global namespace::

getting_started/workflow/export/index.rst

@@ -14,6 +14,5 @@ Export
    exporting_for_uwp
    exporting_for_android
    exporting_for_web
-   customizing_html5_shell
    one-click_deploy
    changing_application_icon_for_windows

tutorials/platform/customizing_html5_shell.rst

@@ -0,0 +1,355 @@
+.. _doc_customizing_html5_shell:
+
+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 <https://github.com/godotengine/godot/blob/master/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 avilable at `/misc/dist/html/fixed-size.html <https://github.com/godotengine/godot/blob/master/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:
+
++------------------------------+-----------------------------------------------+
+| 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 ``<head>`` element                |
++------------------------------+-----------------------------------------------+
+
+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 <doc_javascript_engine_object>` 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``.
+
+.. _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 <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_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:
+
+.. code-block:: js
+
+    var engine = new Engine();
+
+This yields an :js:class:`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.
+
+.. js:function:: engine.init([basePath])
+
+    Initialize the instance. The instance can then be started with one of the
+    ``start`` functions, usually :js:func:`engine.startGame`.
+
+    :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.
+
+    :returns: Promise that resolves once the engine is loaded and initialized.
+
+.. js:function:: 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.
+
+    :param 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 available. Mandatory 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 preloaded.
+
+.. 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(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.
+
+    :param string mainPack:
+        Path to the main pack to start. Also used as base path to load the
+        engine if not loaded already.
+
+    :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(<?php echo Locale::acceptFromHttp($_SERVER['HTTP_ACCEPT_LANGUAGE']); ?>);
+
+    :param string locale:
+        Locale.
+
+    .. seealso:: List of :ref:`locales <doc_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() <class_OS_method_get_executable_path>`
+    and the automatically started main pack, :file:`{ExecutableName}.pck`.
+
+    :param string execName: Executable name.
+
+Customizing the presentation
+----------------------------
+
+The following methods are used to implement the presentation:
+
+.. js:function:: engine.setProgressFunc(callback)
+
+    Set the callback for displaying download progress.
+
+    :param function callback:
+        Callback called once per frame with two number arguments:
+        bytes loaded so far, and total bytes to load.
+
+    .. code-block:: js
+
+        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.
+
+.. js:function:: engine.setStdoutFunc(callback)
+
+    Specify the standard output stream callback.
+
+    :param function callback:
+        Callback function called with one argument, the string to print.
+
+    .. code-block:: js
+
+        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.
+
+.. js:function:: engine.setStderrFunc(callback)
+
+    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

tutorials/platform/index.rst

@@ -7,4 +7,5 @@ Platform-specific
 
    android_in_app_purchases
    services_for_ios
+   customizing_html5_shell
    consoles