Add to and update web docs

 - Update build instructions
 - Document security restrictions
 - Document locale lookup
 - Document JavaScript.eval return type inference
 - Various hints and fixes

reference/compiling_for_web.rst

@@ -16,8 +16,8 @@ To compile export templates for the Web, the following is required:
    untested as of now)
 -  `SCons <http://www.scons.org>`__ build system
 
-Compiling
----------
+Building export templates
+-------------------------
 
 Start a terminal and set the environment variable ``EMSCRIPTEN_ROOT`` to the
 installation directory of Emscripten::
@@ -40,68 +40,18 @@ build or ``release_debug`` for a debug build::
 
 The engine will now be compiled to JavaScript by Emscripten. If all goes well,
 the resulting file will be placed in the ``bin`` subdirectory. Its name is
-``godot.javascript.opt.asm.js`` for release or
-``godot.javascript.opt.debug.asm.js`` for debug. Additionally, three files of
-the same name but with the extensions ``.html``, ``.html.mem`` and ``.js`` will
-be generated.
-
-Building export templates
--------------------------
-
-After compiling, further steps are required to build the template.
-The actual web export template has the form of a zip file containing at least
-these 5 files:
-
-1. ``godot.asm.js`` — This is the file that was just compiled, but under a
-   different name.
-
-   For the release template::
-
-       cp bin/godot.javascript.opt.asm.js godot.asm.js
-
-   For the debug template::
-
-       cp bin/godot.javascript.opt.debug.asm.js godot.asm.js
-
-2. ``godot.js``
-3. ``godot.mem``
-4. ``godot.html`` — other files created during compilation, initially with the
-   same name as the ``.asm.js`` file, except ``.asm.js`` is replaced by
-   ``.js`` for ``godot.js``, ``.html`` for ``godot.html`` and ``.html.mem`` for
-   ``godot.mem``.
-
-   For the release template::
+``godot.javascript.opt.zip`` for release or ``godot.javascript.opt.debug.zip``
+for debug.
 
-       cp bin/godot.javascript.opt.js       godot.js
-       cp bin/godot.javascript.opt.html     godot.html
-       cp bin/godot.javascript.opt.html.mem godot.mem
-
-   For the debug template::
-
-       cp bin/godot.javascript.opt.debug.js       godot.js
-       cp bin/godot.javascript.opt.debug.html     godot.html
-       cp bin/godot.javascript.opt.debug.html.mem godot.mem
-
-5. ``godotfs.js`` — This file is located within the Godot Engine repository,
-   under ``/tools/dist/html_fs/``::
-
-    cp tools/dist/html_fs/godotfs.js .
-
-Once these 5 files are assembled, zip them up and your export template is ready
-to go. The correct name for the template file is ``javascript_release.zip`` for
+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::
 
-    zip javascript_release.zip godot.asm.js godot.js godot.mem godotfs.js godot.html
+    cp bin/godot.javascript.opt.zip ~/.godot/templates/javascript_release.zip
 
 And ``javascript_debug.zip`` for the debug template::
 
-    zip javascript_debug.zip godot.asm.js godot.js godot.mem godotfs.js godot.html
-
-The resulting files must be placed in the ``templates`` directory in your Godot
-user directory::
-
-    mv javascript_release.zip ~/.godot/templates
-    mv javascript_debug.zip ~/.godot/templates
+    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
@@ -144,7 +94,9 @@ Emscripten configuration file ``~/.emscripten`` is set. 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.
+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::
@@ -152,28 +104,14 @@ 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 binaries in either release or debug mode.
-The generated files' names contain ``.webassembly`` as an additional file
-suffix before the extension.
-
-In order to build the actual WebAssembly export templates, the WebAssembly
-binary file with the ``.wasm`` extension is added to the archive as
-``godot.wasm`` in place of ``godot.asm.js`` alongside the usual files.
-
-For the release template::
-
-   cp bin/godot.javascript.opt.webassembly.wasm godot.wasm
-
-For the debug template::
-
-   cp bin/godot.javascript.opt.debug.webassembly.wasm godot.wasm
-
-WebAssembly builds do not use a memory initializer file, so do not add a
-``godot.mem`` file to the archive — there is none.
+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``::
 
-The WebAssembly export 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
 
 Customizing the HTML page
 -------------------------
@@ -184,8 +122,8 @@ 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 so substitute the ``{{{ SCRIPT }}}``
-placeholder by a ``<script>>`` element containing the loader code. This makes
+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.
 

tutorials/asset_pipeline/exporting_for_web.rst

@@ -31,14 +31,17 @@ size. The WebAssembly binary (``.wasm``) file compresses particularly well.
 Export options
 --------------
 
-Turning on **Debugging Enabled** when exporting will display a debug output
-below the canvas, displaying JavaScript and engine errors. If controls are
+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.
 
 **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 the minimum value can be used since memory growth is
-enabled.
+For WebAssembly builds, memory growth is enabled, so this only sets the
+initially allocated amount, which will grow as needed.
 
 **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
@@ -63,29 +66,74 @@ 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.
 
+Security restrictions
+---------------------
+
+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.
+
+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``.
+
+Locale
+------
+
+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.
+
 Calling JavaScript from script
 ------------------------------
 
 In web builds, the ``JavaScript`` singleton is available. If offers a single
-method called ``eval`` that works similar to the JavaScript function of the
+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 the code compatible with other platforms, check if the
+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
-        Globals.get_singleton("JavaScript")
+        JavaScript = Globals.get_singleton("JavaScript")
 
     func my_func():
         # call JavaScript.eval only if available
         if JavaScript:
             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:
+
+ * JavaScript ``number`` is returned as GDScript :ref:`class_int` if it is an
+   integer or as :ref:`class_float` otherwise
+ * 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:
+
+    * 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)
+
+Any other JavaScript value is returned as ``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::