Update HTML5 platform documentation

 - Remove asm.js documentation
 - Document engine.js interface
 - Elaborate on limitations
 - Elaborate on generated files
 - Update build toolchain documentation
 - Update JavaScript singleton documentation

development/compiling/compiling_for_web.rst

@@ -10,7 +10,10 @@ Requirements
 
 To compile export templates for the Web, the following is required:
 
--  `Emscripten <http://emscripten.org/>`__: The easiest way to install it, if it's not up to date in your Linux package manager, is to use the `Emscripten SDK <http://emscripten.org/>`__ (Install in a path without spaces, i.e. not in "Program Files")
+-  `Emscripten 1.37.9+ <http://emscripten.org/>`__: 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/gettng_started/downloads.html>`__
+   (Install in a path without spaces, i.e. not in ``Program Files``)
 -  `Python 2.7+ or Python 3.5+ <https://www.python.org/>`__
 -  `SCons <http://www.scons.org>`__ build system
 
@@ -20,71 +23,54 @@ Building export templates
 Start a terminal and set the environment variable ``EMSCRIPTEN_ROOT`` to the
 installation directory of Emscripten:
 
--  If you installed Emscripten via the Emscripten SDK, you will declare the variable with a path to your downloaded folder::
+If you installed Emscripten via the Emscripten SDK, declare the variable with a
+path to the downloaded folder::
 
     export EMSCRIPTEN_ROOT=~/emsdk/emscripten/master
 
--  If you installed Emscripten via your package manager, you can know the path with the ``em-config`` command::
+If you installed Emscripten via package manager, the path can be retrieved with
+the ``em-config`` command::
 
-    em-config EMSCRIPTEN_ROOT
+    export EMSCRIPTEN_ROOT=`em-config EMSCRIPTEN_ROOT`
 
-   So you will declare the variable as for example::
+On Windows you can set the environment variable in the system settings or in
+the command prompt::
 
-    export EMSCRIPTEN_ROOT=/usr/lib/emscripten
-
-The Emscripten variables are defined in the ``~/.emscripten`` file, so this is an alternative way to check. Erase this file if you want to reinstall Emscripten with a fresh new method.
-
-If you are on Windows and used Emscripten SDK, start a regular prompt or the Emscripten Command Prompt.
-Do **not** use the Developer Command Prompt nor any of the ones that come with
-Visual Studio. You can set the environment variable in the system settings or
-in the prompt itself::
-
-    set EMSCRIPTEN_ROOT=C:\emsdk\emscripten\master
+    set EMSCRIPTEN_ROOT="C:\emsdk\emscripten\master"
 
 Now go to the root directory of the engine source code and instruct SCons to
-compile for JavaScript. Specify ``target`` as either ``release`` for a release
-build or ``release_debug`` for a debug build::
+build the JavaScript platform. Specify ``target`` as either ``release`` for a
+release build or ``release_debug`` for a debug build::
 
     scons platform=javascript tools=no target=release
     scons platform=javascript tools=no target=release_debug
 
-The engine will now be compiled to JavaScript by Emscripten. If all goes well,
+The engine will now be compiled to WebAssembly by Emscripten. If all goes well,
 the resulting file will be placed in the ``bin`` subdirectory. Its name is
 ``godot.javascript.opt.zip`` for release or ``godot.javascript.opt.debug.zip``
 for debug.
 
-If it's not, check if you have properly installed everything, and if EMSCRIPTEN_ROOT path is correctly defined, including in the ``~/.emscripten`` file.
-
-Finally, rename the zip archive to ``javascript_release.zip`` for the
+Finally, rename the zip archive to ``webassembly_release.zip`` for the
 release template::
 
-    mv bin/godot.javascript.opt.zip bin/javascript_release.zip
+    mv bin/godot.javascript.opt.zip bin/webassembly_release.zip
 
-And ``javascript_debug.zip`` for the debug template::
+And ``webassembly_debug.zip`` for the debug template::
 
-    mv bin/godot.javascript.opt.debug.zip bin/javascript_debug.zip
+    mv bin/godot.javascript.opt.debug.zip bin/webassembly_debug.zip
 
-Compiling to WebAssembly
--------------------------
+Building per asm.js translation or LLVM backend
+-----------------------------------------------
 
-The current default for exporting to the web is to compile to *asm.js*, a
-highly optimizable subset of JavaScript.
-
-It is also possible to compile to the *WebAssembly* format, which offers better
-performance and loading times. Running a game in this format requires a browser
-with WebAssembly support.
-
-Compiling to WebAssembly requires using the latest version of Emscripten.
-If your OS does not offer up-to-date packages for Emscripten, the easiest way
-is usually to install using Emscripten's `emsdk <http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html>`_.
-
-WebAssembly can be compiled in two ways: The default way is to first
-compile to asm.js similarly to the default method, then translate to
-WebAssembly using a tool called ``asm2wasm``. Emscripten automatically takes
-care of both processes, we simply run SCons.
+WebAssembly can be compiled in two ways: The default is to first compile to
+asm.js, a highly optimizable subset of JavaScript, using Emscripten's
+*fastcomp* fork of LLVM. This code is then translated to WebAssembly using a
+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.
+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.
@@ -97,73 +83,3 @@ 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 ``/``.
-
-With ``LLVM_ROOT`` set up correctly, compiling to WebAssembly is as easy as
-adding ``wasm=yes`` to the SCons arguments::
-
-    scons platform=javascript target=release wasm=yes
-    scons platform=javascript target=release_debug wasm=yes
-
-These commands will build WebAssembly export templates in either release or
-debug mode. The generated files' names contain ``.webassembly`` as an
-additional file suffix before the extension.
-
-If it's not compiling, check if you have properly installed everything, and if ``LLVM_ROOT`` and ``BINARYEN_ROOT`` variables are defined in the ``~/.emscripten`` file. You can define the ``BINARYEN_ROOT`` path manually in this file if you already installed Binaryen an other way and want to avoid SCons to compile it from ports during template compilation. Emscripten SDK comes with its own fork of LLVM called fastcomp, which has the JSBackend needed for asm.js and asm2wasm, so the ``LLVM_ROOT`` path must lead to an ``/emscripten-fastcomp`` directory.
-
-Finally, the WebAssembly templates are renamed to ``webassembly_release.zip``
-and ``webassembly_debug.zip``::
-
-    mv bin/godot.javascript.opt.webassembly.zip       bin/webassembly_release.zip
-    mv bin/godot.javascript.opt.debug.webassembly.zip bin/webassembly_debug.zip
-
-Customizing the HTML page
--------------------------
-
-Rather than the default HTML file generated when compiling, it is
-also possible to use a custom HTML page. This allows drastic customization of
-the final web presentation.
-
-This can be done in two ways. The first is to replace the
-``platform/javascript/godot_shell.html`` file. In this case, the HTML file is
-used at build time, allowing Emscripten to substitute the ``{{{ SCRIPT }}}``
-placeholder by a ``<script>`` element containing the loader code. This makes
-the HTML file usable for both asm.js and WebAssembly templates, since they use
-different loading code.
-
-The other method is to simply replace the ``godot.html`` file within the
-complete export templates. This method does not require building the engine.
-However, in this case, no ``{{{ SCRIPT }}}`` placeholder should be used in the
-HTML file, since it would never be replaced — the loader code for either asm.js
-or WebAssembly must already be included in the file.
-
-In the HTML page, the JavaScript object ``Module`` is the page's interface to
-Emscripten. Check the official documentation for information on how to use it:
-https://kripken.github.io/emscripten-site/docs/api_reference/module.html
-
-The default HTML page offers an example to start off with, separating the
-Emscripten interface logic in the JavaScript ``Module`` object from the page
-logic in the ``Presentation`` object. Emscripten's default ``shell.html`` file
-is another example, but does not use Godot's placeholders, listed below.
-
-When exporting a game, several placeholders in the ``godot.html`` file are
-substituted by values dependent on the export:
-
-+------------------------------+-----------------------------------------------+
-| Placeholder                  | substituted by                                |
-+==============================+===============================================+
-| ``$GODOT_BASE``              | Basename of files referenced within the page, |
-|                              | without suffixes                              |
-+------------------------------+-----------------------------------------------+
-| ``$GODOT_DEBUG_ENABLED``     | ``true`` if debugging, ``false`` otherwise    |
-+------------------------------+-----------------------------------------------+
-| ``$GODOT_HEAD_INCLUDE``      | Custom string to include just before the end  |
-|                              | of the HTML ``<head>`` element                |
-+------------------------------+-----------------------------------------------+
-| ``{{{ SCRIPT }}}``           | ``<script>`` that loads the engine,           |
-|                              | substituted only when building, not on export |
-+------------------------------+-----------------------------------------------+
-
-The first three of the placeholders listed should always be implemented in the
-HTML page, since they are important for the correct presentation of the game.
-The last placeholder is important when rewriting the ``godot_shell.html`` file
-and is substituted during build time rather than export.

learning/workflow/export/customizing_html5_shell.rst

@@ -0,0 +1,220 @@
+.. _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 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
+`/mist/dist/html/default.html <https://github.com/godotengine/godot/blob/master/misc/dist/html/default.html>`_.
+
+Placeholder substitution
+------------------------
+
+When exporting the game, several placeholders in the HTML page are substituted
+by values dependening 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 substituted 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.
+
+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, fileName)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 and the file
+name will be retained. If ``file`` is an ``ArrayBuffer`` or a view on one,
+the buffer will available as a file under the name given by ``fileName``.
+
+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 specifed.
+
+``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 specifices 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 respecively.
+
+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

learning/workflow/export/exporting_for_web.rst

@@ -3,81 +3,74 @@
 Exporting for the Web
 =====================
 
-Exporting for the web generates several files to be served from a web server,
-including a default HTML page for presentation. A custom HTML file can be
-used, see :ref:`doc_compiling_for_web`.
+HTML5 export allows publishing games made in Godot Engine to the browser.
+This requires support for the recent technologies `WebAssembly
+<http://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.
 
-The default HTML file 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.
-This way it can be inserted into an ``<iframe>`` with the game's size, as is
-common on most web game hosting sites.
+Limitations
+-----------
 
-Serving the files
------------------
+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.
 
-The generated ``.html`` file can be used as ``DirectoryIndex`` and can be
-renamed to e.g. ``index.html`` at any time, its name is never depended on.
-It can also be inserted into another HTML file as an ``<iframe>`` element.
-Users must allow **third-party** cookies when playing a game presented in an
-iframe.
+Exported ``.html`` file must not be reused
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The other exported files are served as they are next to the ``.html`` file,
-names unchanged.
+On export, several text placeholders are replaced in the **generated HTML
+file** specifically for the given export options. It must not be reused in
+futher exports.
 
-The ``.mem`` and ``.pck`` files are binary, usually delivered with the
-MIME-type ``application/octet-stream``. The ``.wasm`` file is the WebAssembly
-module, delivered as ``application/wasm``.
+Using cookies for data persistence
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Delivering the files with gzip compression is recommended especially for the
-``.pck``, ``.asm.js``, ``.mem`` and ``.wasm`` files, which are usually large in
-size.
+Users must **allow cookies** (specifically IndexedDB) if persistence of the
+``user://`` file system is desired. When playing a game presented in an
+``iframe``, **third-party** cookies must also be enabled. Incognito/private
+mode also prevents persistence.
 
-Export options
---------------
+The method ``OS.is_userfs_persistent()`` can be used to check if the
+``user://`` file system is persistent, but can give false positives in some
+cases.
 
-If a runnable web export template is available, a button appears between the
-*Stop scene* and *Play edited Scene* buttons in the editor to quickly open the
-game in the default browser for testing.
+Full screen and mouse capture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Target** sets the format of the engine. *WebAssembly* is a newer and more
-performant technology that is only supported by recent browser versions.
-*asm.js* is a highly optimizable subset of JavaScript and supported by some
-older browser versions. A 64-bit browser is required to run games in asm.js
-format. Most notably, this is a problem with Firefox, which on Windows is
-shipped as a 32-bit application by default.
+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``.
 
-For asm.js **Memory Size** is fixed and must thus be set during export. Try
-using no more than necessary to strain users' browsers as little as possible.
-For WebAssembly, memory growth is enabled, so this option is not needed nor
-displayed.
+For the same reason, the full screen project setting is ignored.
 
-**Head Include** is appended into the ``<head>`` element of the generated
-HTML page. This allows, for example, linking web fonts for use in the page.
+HTTPClient
+~~~~~~~~~~
 
-Turning on **Debugging Enabled** when exporting will, in addition to enabling
-various debug features of the engine, display a debug output below the canvas,
-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.
+The ``HTTPClient`` implementation for the HTML5 platform has several
+restrictions:
 
-Web export limitations
-----------------------
+ -  Accessing or changing the ``StreamPeer`` is not possible
+ -  Blocking mode is not available
+ -  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>`_
 
-Exported files must not be reused
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Unimplemented functionality
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The exported files ending with ``.html`` and ``fs.js`` are adjusted on export
-specifically for that game's version and the given export options. They must
-not be reused in futher exports.
+The following functionality is currently unavailable on the HTML5 platform:
 
-Some functions must be called from input callbacks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ -  Threads
+ -  GDNative
+ -  Clipboard synchronisation between engine and operating system
+ -  Networking other than ``HTTPClient``
 
-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 ``_input`` or
-``_unhandled_input``.
+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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -89,66 +82,98 @@ 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``.
 
-Locale lookup
-~~~~~~~~~~~~~
+Serving the files
+-----------------
 
-Godot tries to detect the user's locale using information provided by the
-browser, but this is rather unreliable. A better way is to use CGI to read the
-HTTP ``Accept-Language`` header. If you assign its value to the JavaScript
-property ``Module.locale`` after the ``Module`` objects is created, but before
-the engine starts, Godot will use that value to initialize the locale.
-In any case, users should always be offered the option to configure the locale
-manually.
+Exporting for the web generates several files to be served from a web server,
+including a default HTML page for presentation. A custom HTML file can be
+used, see :ref:`doc_customizing_html5_shell`.
+
+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.
+This way it can be inserted into an ``<iframe>`` with the game's size, as is
+common on most web game hosting sites.
+
+The other exported files are served as they are, next to the ``.html`` file,
+names unchanged. The ``.wasm`` file is a binary WebAssembly module implementing
+the engine. The ``.pck`` file is the Godot main pack containing your game. The
+``.js`` file contains start-up code and is used by the ``.html`` file to access
+the engine. The ``.png`` file contains the boot splash image. It is not used in
+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``.
+
+Delivering the files with server-side compression is recommended especially for
+the ``.pck`` and ``.wasm`` files, which are usually large in size.
+The WebAssembly module compresses particularily well, down to around a quarter
+of its original size with GZip.
+
+Export options
+--------------
+
+If a runnable web export template is available, a button appears between the
+*Stop scene* and *Play edited Scene* buttons in the editor to quickly open the
+game in the default browser for testing.
+
+If a path to a **Custom HTML shell** file is given, it will be used instead of
+the default HTML page. See :ref:`doc_customizing_html5_shell`.
+
+**Head Include** is appended into the ``<head>`` element of the generated
+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.
 
 Calling JavaScript from script
 ------------------------------
 
-In web builds, the ``JavaScript`` singleton is available. If offers a single
+In web builds, the ``JavaScript`` singleton is implemented. If 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
 languages integrated into Godot.
 
-In order to keep your code compatible with other platforms, check if the
-JavaScript singleton is available before using it::
-
-    var JavaScript
-
-    func _ready():
-        # retrieve the singleton here, will return `null` on platforms other than web
-        JavaScript = Globals.get_singleton("JavaScript")
+::
 
     func my_func():
-        # call JavaScript.eval only if available
-        if JavaScript:
-            JavaScript.eval("alert('Calling JavaScript per GDScript!');")
+        JavaScript.eval("alert('Calling JavaScript per GDScript!');")
 
-The return value of the last JavaScript statement is converted to a GDScript
-value and returned by ``eval()`` under certain circumstances:
+The value of the last JavaScript statement is converted to a GDScript value and
+returned by ``eval()`` under certain circumstances:
 
- * JavaScript ``number`` is returned as GDScript :ref:`class_int` if it is an
-   integer or as :ref:`class_float` otherwise
+ * JavaScript ``number`` is returned as GDScript :ref:`class_float`
  * JavaScript ``boolean`` is returned as GDScript :ref:`class_bool`
  * JavaScript ``string`` is returned as GDScript :ref:`class_String`
- * JavaScript ``object`` is only converted and returned if it has certain
-   ``Number``-type properties, listed in order of priority:
+ * JavaScript ``ArrayBuffer``, ``TypedArray`` and ``DataView`` are returned as
+   GDScript :ref:`class_PoolByteArray`
+
+::
 
-    * Objects with ``x``, ``y`` and ``z`` properties are returned as a :ref:`class_Vector3`
-    * Objects with ``x``, ``y``, ``width`` and ``height`` properties are returned as a :ref:`class_Rect2`
-    * Objects with ``x`` and ``y`` properties are returned as a :ref:`class_Vector2`
-    * Objects with an ``r``, ``g``, ``b`` and an optional ``a``  property are
-      returned as a :ref:`class_Color`, the JavaScript values are interpreted
-      as 8-bit values (0-255) for the color components and
-      floating point values (0.0-1.0) for the alpha channel
+    func my_func2():
+        var js_return = JavaScript.eval("var myNumber = 1; myNumber + 2;")
+        print(js_return) # prints '3.0'
 
 Any other JavaScript value is returned as ``null``.
 
+Calling ``JavaScript.eval`` on platforms other than HTML5 will also return
+``null``.
+
 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::
 
-    func my_func2():
-        if JavaScript:
-            # execute in global execution context,
-            # thus adding a new JavaScript global variable `MyGlobal`
-            JavaScript.eval("var MyGlobal = {};", true)
+    func my_func3():
+        # execute in global execution context,
+        # thus adding a new JavaScript global variable `MyGlobal`
+        JavaScript.eval("var SomeGlobal = {};", true)

learning/workflow/export/index.rst

@@ -13,4 +13,5 @@ Export
    exporting_for_uwp
    exporting_for_android
    exporting_for_web
+   customizing_html5_shell
    one-click_deploy