Update and clarify HTML5 doc

development/compiling/compiling_for_web.rst

@@ -43,22 +43,14 @@ 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.
 
-To install the templates, place them into the ``templates`` directory in your
-Godot user directory. Rename the zip archive to ``javascript_release.zip`` for
-the release template::
+Finally, rename the zip archive to ``javascript_release.zip`` for the
+release template::
 
-    cp bin/godot.javascript.opt.zip ~/.godot/templates/javascript_release.zip
+    mv bin/godot.javascript.opt.zip bin/javascript_release.zip
 
 And ``javascript_debug.zip`` for the debug template::
 
-    cp bin/godot.javascript.opt.debug.zip ~/.godot/templates/javascript_debug.zip
-
-If you are writing custom modules or using custom C++ code, you may want to
-configure your zip files as custom export templates. This can be done in the
-export GUI, using the "Custom Package" option.
-There's no need to copy the templates in this case — you can simply reference
-the resulting files in your Godot source folder, so the next time you build,
-the custom templates will already be referenced.
+    mv bin/godot.javascript.opt.debug.zip bin/javascript_debug.zip
 
 Compiling to WebAssembly
 -------------------------
@@ -66,28 +58,24 @@ Compiling to WebAssembly
 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 experimental *WebAssembly* format, which
-should eventually offer better performance and loading times. Its specification
-is still in flux and compile tools may sporadically fail to build Godot.
-Running a game per WebAssembly requires nightly browser builds with special
-flags set. As such, WebAssembly builds are currently not suitable for
-publishing.
+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 `incoming branch of Emscripten <http://kripken.github.io/emscripten-site/docs/building_from_source/building_emscripten_from_source_using_the_sdk.html#building-emscripten-from-the-main-repositories>`_.
+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.
 
-The other method uses LLVM's WebAssembly backend, which should eventually
-produce more performant binaries. To build LLVM with this backend, set the
-CMake variable ``LLVM_EXPERIMENTAL_TARGETS_TO_BUILD`` to ``WebAssembly`` when
-building LLVM.
-
+The other method uses LLVM's WebAssembly backend. This backend is not yet
+available in release versions of LLVM, only in development builds.
 Compiling with this backend outputs files in LLVM's ``.s`` format, which is
-translated to actual WebAssembly using a tool called ``s2wasm``. Emscripten
-manages these processes as well, so we just invoke SCons.
+translated into actual WebAssembly using a tool called ``s2wasm``.
+Emscripten manages these processes 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 ``~/.emscripten`` is set. If it points to a
@@ -107,11 +95,12 @@ adding ``wasm=yes`` to the SCons arguments::
 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.
-The templates simply replace the previous asm.js-based web export templates
-with the names ``javascript_release.zip`` and ``javascript_debug.zip``::
 
-   cp bin/godot.javascript.opt.webassembly.zip       ~/.godot/templates/javascript_release.zip
-   cp bin/godot.javascript.opt.debug.webassembly.zip ~/.godot/templates/javascript_debug.zip
+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
 -------------------------
@@ -149,32 +138,13 @@ substituted by values dependent on the export:
 | Placeholder                  | substituted by                                |
 +==============================+===============================================+
 | ``$GODOT_BASE``              | Basename of files referenced within the page, |
-|                              | without file extension or other suffixes      |
-+------------------------------+-----------------------------------------------+
-| ``$GODOT_CANVAS_WIDTH``      | Integer specifying the initial display width  |
-|                              | of the game                                   |
-+------------------------------+-----------------------------------------------+
-| ``$GODOT_CANVAS_HEIGHT``     | Integer specifying the initial display height |
-|                              | of the game                                   |
+|                              | without suffixes                              |
 +------------------------------+-----------------------------------------------+
-| ``$GODOT_DEBUG_ENABLED``     | String ``true`` if debugging, ``false``       |
-|                              | otherwise                                     |
-+------------------------------+-----------------------------------------------+
-| ``$GODOT_CONTROLS_ENABLED``  | String ``true`` if ``html/controls_enabled``  |
-|                              | is enabled, ``false`` otherwise               |
-+------------------------------+-----------------------------------------------+
-| ``$GODOT_HEAD_TITLE``        | Title of the page, normally used as content   |
-|                              | of the HTML ``<title>`` element               |
+| ``$GODOT_DEBUG_ENABLED``     | ``true`` if debugging, ``false`` otherwise    |
 +------------------------------+-----------------------------------------------+
 | ``$GODOT_HEAD_INCLUDE``      | Custom string to include just before the end  |
 |                              | of the HTML ``<head>`` element                |
 +------------------------------+-----------------------------------------------+
-| ``$GODOT_STYLE_FONT_FAMILY`` | CSS format ``font-family`` to use, without    |
-|                              | terminating semicolon                         |
-+------------------------------+-----------------------------------------------+
-| ``$GODOT_STYLE_INCLUDE``     | Custom string to include just before the end  |
-|                              | of the page's CSS                             |
-+------------------------------+-----------------------------------------------+
 | ``{{{ SCRIPT }}}``           | ``<script>`` that loads the engine,           |
 |                              | substituted only when building, not on export |
 +------------------------------+-----------------------------------------------+
@@ -182,5 +152,4 @@ substituted by values dependent on the 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 only substituted during build time, not during export time.
-The other placeholders are optional.
+and is substituted during build time rather than export.

learning/workflow/export/exporting_for_web.rst

@@ -21,68 +21,76 @@ 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.
 
-The ``.mem``, ``.pck`` (and ``.wasm`` when using WebAssembly) files are
-binary, usually delivered with MIME-type ``application/octet-stream``.
+The other exported files are served as they are next to the ``.html`` file,
+names unchanged.
+
+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``.
 
 Delivering the files with gzip compression is recommended especially for the
 ``.pck``, ``.asm.js``, ``.mem`` and ``.wasm`` files, which are usually large in
-size. The WebAssembly binary (``.wasm``) file compresses particularly well.
+size.
 
 Export options
 --------------
 
-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. If controls are
-enabled as well, display of this output can be toggled.
-You can also use the browser-integrated developer console, usually opened with
-the F12 key, which often shows more information, including WebGL errors.
+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.
 
-**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 builds, memory growth is enabled, so this only sets the
-initially allocated amount, which will grow as needed.
+**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.
 
-**Enable Run** will add a button between the *Stop scene* and *Play edited Scene*
-buttons in the editor to quickly open the game in the default browser for
-testing.
+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.
 
-The remaining options customize the generated HTML page:
+**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.
 
-**Title** is the content of the ``<title>`` element of the page, usually used by
-browsers as the tab and window name. The title set here is only displayed until
-the game is started, afterwards the title is set to the application name set in
-the project settings.
+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.
 
-**Head Include** and **Style Include** are appended into the ``<head>`` and
-CSS ``<style>`` elements respectively. This allows, for example, linking
-web fonts for use in the page.
+Web export limitations
+----------------------
 
-**Font Family** is the CSS ``font-family`` used on the page, without terminating
-semicolon.
+Exported files must not be reused
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Controls Enabled** toggles display of controls, offering e.g. a toggle for
-output display in debug mode and a fullscreen button.
-In the default page, the controls are displayed in the top-right corner on top
-of the canvas, which can get in the way in games that use the cursor.
+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.
 
-Security restrictions
----------------------
+Some functions must be called from input callbacks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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.
+entering full screen from within an input callback such ``_input`` or
+``_unhandled_input``.
+
+Starting exported games from the local file system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many browsers will not load exported projects when **opened locally**
+per ``file://`` protocol. To get around this, use a local server.
 
-Chromium-derived browsers will not load exported projects when
-**opened locally** per ``file://`` protocol. To get around this, you can start
-the browser with the ``--allow-file-access-from-files`` flag, or use a local
-server. Python offers an easy way 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``.
+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
-------
+Locale lookup
+~~~~~~~~~~~~~
 
 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
@@ -130,7 +138,8 @@ value and returned by ``eval()`` under certain circumstances:
     * 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)
+      as 8-bit values (0-255) for the color components and
+      floating point values (0.0-1.0) for the alpha channel
 
 Any other JavaScript value is returned as ``null``.