Merge pull request #1350 from eska014/html5-april18

Update HTML5 documentation

development/compiling/compiling_for_web.rst

@@ -13,39 +13,34 @@ To compile export templates for the Web, the following is required:
 -  `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
 
 Building export templates
 -------------------------
 
-Start a terminal and set the environment variable ``EMSCRIPTEN_ROOT`` to the
-installation directory of Emscripten:
+Before starting, confirm that the Emscripten configuration file exists and
+specifies all settings correctly. This file is available as ``~/.emscripten``
+on UNIX-like systems and ``%USERPROFILE%\.emscripten`` on Windows. It's usually
+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.
 
-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 package manager, the path can be retrieved with
-the ``em-config`` command::
-
-    export EMSCRIPTEN_ROOT=`em-config EMSCRIPTEN_ROOT`
-
-On Windows you can set the environment variable in the system settings or in
-the command prompt::
-
-    set EMSCRIPTEN_ROOT="C:\emsdk\emscripten\master"
-
-Now go to the root directory of the engine source code and instruct SCons to
-build the JavaScript platform. Specify ``target`` as either ``release`` for a
-release build or ``release_debug`` for a debug build::
+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::
 
     scons platform=javascript tools=no target=release
     scons platform=javascript tools=no target=release_debug
 
-The engine will now be compiled to WebAssembly by Emscripten. If all goes well,
+By default, the :ref:`JavaScript singleton <doc_javascript_eval>` will be built
+into the engine. Since ``eval()`` calls can be a security concern, the
+``javascript_eval`` option can be used to build without the singleton::
+
+    scons platform=javascript tools=no target=release javascript_eval=no
+    scons platform=javascript tools=no target=release_debug javascript_eval=no
+
+The engine will now be compiled to WebAssembly by Emscripten. Once finished,
 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.
@@ -76,10 +71,10 @@ 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
-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 ``/``.
+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 ``/``.

getting_started/workflow/export/customizing_html5_shell.rst

@@ -5,11 +5,19 @@ 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
+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
 `/mist/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
 ------------------------
@@ -65,6 +73,12 @@ Returns a promise that resolves once the engine is loaded.
 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
 -------------------------------
 
@@ -89,15 +103,19 @@ 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)``
+``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 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``.
+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 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.
 
@@ -209,7 +227,7 @@ argument specifying the string to print.
 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.
+By default, ``console.log()`` and ``console.warn()`` are used respectively.
 
 Accessing the Emscripten ``Module``
 -----------------------------------

getting_started/workflow/export/exporting_for_web.rst

@@ -8,6 +8,8 @@ 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.
+On **iOS**, all browsers must be based on WebKit (i.e. Safari), so they will also
+not work.
 
 Limitations
 -----------
@@ -54,6 +56,7 @@ restrictions:
 
  -  Accessing or changing the ``StreamPeer`` is not possible
  -  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>`_
@@ -75,8 +78,9 @@ to communicate your interest.
 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.
+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
@@ -135,6 +139,8 @@ 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
 ------------------------------
 
@@ -166,14 +172,22 @@ returned by ``eval()`` under certain circumstances:
 
 Any other JavaScript value is returned as ``null``.
 
-Calling ``JavaScript.eval`` on platforms other than HTML5 will also return
-``null``.
+HTML5 export templates may be built without support for the singleton. With such
+templates, and on platforms other than HTML5, calling ``JavaScript.eval`` will
+also return ``null``.  The availability of the singleton can be checked with the
+``JavaScript`` :ref:`feature tag <doc_feature_tags>`::
+
+    func my_func3():
+        if OS.has_feature('JavaScript'):
+            JavaScript.eval("console.log('The JavaScript singleton is available')")
+        else:
+            print("The JavaScript singleton is NOT available")
 
 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_func3():
+    func my_func4():
         # execute in global execution context,
         # thus adding a new JavaScript global variable `MyGlobal`
         JavaScript.eval("var SomeGlobal = {};", true)

getting_started/workflow/export/feature_tags.rst

@@ -33,7 +33,10 @@ Here is a list of most feature tags in Godot. Keep in mind they are *case sensit
 +=================+========================================================+
 | **Android**     | Running on Android                                     |
 +-----------------+--------------------------------------------------------+
-| **JavaScript**  | Running on JavaScript (HTML5)                          |
+| **HTML5**       | Running on HTML5                                       |
++-----------------+--------------------------------------------------------+
+| **JavaScript**  | :ref:`JavaScript singleton <doc_javascript_eval>` is   |
+|                 | available                                              |
 +-----------------+--------------------------------------------------------+
 | **OSX**         | Running on macOS                                       |
 +-----------------+--------------------------------------------------------+