Update documentation about HTML5 exporting and compiling (#4454)

* Improve the Exporting for the Web section.

Add "Export Type" options (threads, gdnative, regular).
Add warnings about "secure contexts" limitations.
Mentions threads and GDNative requirements.
Mention WebRTC as a networking API.
General refactor.

* Update compiling for the Web.

Bump emscripten requirements, mention threads, gdnative and editor
build.

development/compiling/compiling_for_web.rst

@@ -10,7 +10,7 @@ Requirements
 
 To compile export templates for the Web, the following is required:
 
--  `Emscripten 1.39.0+ <https://emscripten.org>`__.
+-  `Emscripten 1.39.9+ <https://emscripten.org>`__.
 -  `Python 3.5+ <https://www.python.org/>`__.
 -  `SCons 3.0+ <https://www.scons.org>`__ build system.
 
@@ -20,16 +20,9 @@ To compile export templates for the Web, the following is required:
 Building export templates
 -------------------------
 
-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.
-
-.. 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 ``/``.
+Before starting, confirm that ``emcc`` is available in your PATH. This is
+usually configured by the Emscripten SDK, e.g. when invoking ``emsdk activate``
+and ``source ./emsdk_env.sh``/``emsdk_env.bat``.
 
 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
@@ -60,22 +53,49 @@ And ``webassembly_debug.zip`` for the debug template::
 
     mv bin/godot.javascript.opt.debug.zip bin/webassembly_debug.zip
 
-Building per asm.js translation or LLVM backend
------------------------------------------------
-
-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 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
-the LLVM's WebAssembly backend is used.
+Threads and GDNative
+--------------------
+
+The default export templates do not include threads and GDNative support for
+performance and compatibility reasons. See the
+:ref:`export page <doc_javascript_export_options>` for more info.
+
+You can build the export templates using the option ``threads_enabled=yes`` or
+``gdnative_enabled=yes`` to enable threads or GDNative support::
+
+    scons platform=javascript tools=no threads_enabled=yes target=release
+    scons platform=javascript tools=no threads_enabled=yes target=release_debug
+
+    scons platform=javascript tools=no gdnative_enabled=yes target=release
+    scons platform=javascript tools=no gdnative_enabled=yes target=release_debug
+
+Once finished, the resulting file will be placed in the ``bin`` subdirectory.
+Its name will have either the ``.threads`` or ``.gdnative`` suffix.
+
+Finally, rename the zip archives to ``webassembly_release_threads.zip`` and
+``webassembly_release_gdnative.zip`` for the release template::
+
+    mv bin/godot.javascript.opt.threads.zip bin/webassembly_threads_release.zip
+    mv bin/godot.javascript.opt.gdnative.zip bin/webassembly_gdnative_release.zip
+
+And ``webassembly_debug_threads.zip`` and ``webassembly_debug_gdnative.zip`` for
+the debug template::
+
+    mv bin/godot.javascript.opt.debug.threads.zip bin/webassembly_threads_debug.zip
+    mv bin/godot.javascript.opt.debug.gdnative.zip bin/webassembly_gdnative_debugzip
+
+Building the editor
+-------------------
+
+It is also possible to build a version of the Godot editor that can run in the
+browser. The editor version requires threads support and is not recommended
+over the native build. You can build the editor with::
+
+    scons platform=javascript tools=yes threads_enabled=yes target=release_debug
+
+Once finished, the resulting file will be placed in the ``bin`` subdirectory.
+Its name will be ``godot.javascript.opt.tools.threads.zip``. You can upload the
+zip content to your web server and visit it with your browser to use the editor.
+
+Refer to the :ref:`export page <doc_javascript_export_options>` for the web
+server requirements.

tutorials/export/exporting_for_web.rst

@@ -12,16 +12,7 @@ in the user's browser.
                with :kbd:`F12`, to view **debug information** like JavaScript,
                engine, and WebGL errors.
 
-.. attention:: Many browsers, including Firefox and Chromium-based browsers,
-               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 http.server 8000 --bind 127.0.0.1`` with Python 3 to serve the
-                        current working directory at ``http://localhost:8000``.
-                        `Refer to MDN for additional information <https://developer.mozilla.org/en-US/docs/Learn/Common_questions/set_up_a_local_testing_server>`__.
-
-.. attention:: `There are significant bugs when running HTML5 projects on iOS <https://github.com/godotengine/godot/issues/26554>`__
+.. attention:: `There are significant bugs when running HTML5 projects on iOS <https://github.com/godotengine/godot/issues?q=is:issue+is:open+label:platform:html5+ios>`__
                (regardless of the browser). We recommend using
                :ref:`iOS' native export functionality <doc_exporting_for_ios>`
                instead, as it will also result in better performance.
@@ -42,6 +33,43 @@ WebKit (i.e. Safari), so they will also not work.
 
 Godot's WebGL 2 renderer has issues with 3D and is no longer maintained.
 
+.. _doc_javascript_export_options:
+
+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.
+
+You can choose the **Export Type** to select which features will be available:
+
+- *Regular*: is the most compatible across browsers, will not support threads, nor GDNative.
+- *Threads*: will require the browser to support `SharedArrayBuffer <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer>`__
+- *GDNative*: enables GDNative support but makes the binary bigger and slower to load.
+
+If you plan to use :ref:`VRAM compression <doc_import_images>` make sure that
+**Vram Texture Compression** is enabled for the targeted platforms (enabling
+both **For Desktop** and **For Mobile** will result in a bigger, but more
+compatible export).
+
+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.
+
+.. important:: Each project must generate their own HTML file. On export,
+               several text placeholders are replaced in the generated HTML
+               file specifically for the given export options. Any direct
+               modifications to that HTML file will be lost in future exports.
+               To customize the generated file, use the **Custom HTML shell**
+               option.
+
+.. warning:: **Export types** other then *Regular* are not yet supported by the
+             C# version.
+
 Limitations
 -----------
 
@@ -49,6 +77,19 @@ 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.
 
+.. _doc_javascript_secure_contexts:
+
+.. important:: Browser vendors are making more and more functionalities only
+               available in `secure contexts <https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts>`_,
+               this means that such features are only be available if the web
+               page is served via a secure HTTPS connection (localhost is
+               usually exempt from such requirement).
+
+.. 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 the functionality you're interested in has an issue yet. If
+         not, open one to communicate your interest.
+
 Using cookies for data persistence
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -61,6 +102,26 @@ 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.
 
+Threads
+~~~~~~~
+
+As mentioned :ref:`above <doc_javascript_export_options>` multi-threading is
+only available if the appropriate **Export Type** is set and support for it
+across browsers is still limited.
+
+.. warning:: Requires a :ref:`secure context <doc_javascript_secure_contexts>`.
+             Browsers are also starting to require that the web page is served with specific
+             `cross-origin isolation headers <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy>`__.
+
+GDNative
+~~~~~~~~
+
+As mentioned :ref:`above <doc_javascript_export_options>` GDNative is only
+available if the appropriate **Export Type** is set.
+
+The export will also copy the required GDNative ``.wasm`` files to the output
+folder (and must be uploaded to your server along with your game).
+
 Full screen and mouse capture
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -75,8 +136,8 @@ 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
-~~~~~~~~~~~~~~
+Audio
+~~~~~
 
 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.
@@ -84,10 +145,20 @@ player to click or tap or press a key to enable audio.
 .. seealso:: Google offers additional information about their `Web Audio autoplay
              policies <https://sites.google.com/a/chromium.org/dev/audio-video/autoplay>`__.
 
-:ref:`class_HTTPClient` and :ref:`class_HTTPRequest`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. warning:: Access to microphone requires a
+             :ref:`secure context <doc_javascript_secure_contexts>`.
+
+Networking
+~~~~~~~~~~
+
+Low level networking is not implemented due to lacking support in browsers.
 
-The HTTP classes have several restrictions on the HTML5 platform:
+Currently, only :ref:`HTTP client <doc_http_client_class>`,
+:ref:`HTTP requests <doc_http_request_class>`,
+:ref:`WebSocket (client) <doc_websocket>` and :ref:`WebRTC <doc_webrtc>` are
+supported.
+
+The HTTP classes also have several restrictions on the HTML5 platform:
 
  -  Accessing or changing the ``StreamPeer`` is not possible
  -  Threaded/Blocking mode is not available
@@ -96,11 +167,26 @@ The HTTP classes have several restrictions on the HTML5 platform:
  -  Host verification cannot be disabled
  -  Subject to `same-origin policy <https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy>`__
 
-Exported ``.html`` file must not be reused
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Clipboard
+~~~~~~~~~
+
+Clipboard synchronization between engine and the operating system requires a
+browser supporting the `Clipboard API <https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API>`__,
+additionally, due to the API asynchronous nature might not be reliable when
+accessed from GDScript.
+
+.. warning:: Requires a :ref:`secure context <doc_javascript_secure_contexts>`.
+
+Gamepads
+~~~~~~~~
 
-Each project must generate their own HTML file. On export, several text placeholders are replaced in the **generated HTML
-file** specifically for the given export options. Any direct modifications to the **generated HTML file** will be lost in future exports. To customize the generated file, see :ref:`doc_customizing_html5_shell`.
+Gamepads will not be detected until one of their button is pressed. Gamepads
+might have the wrong mapping depending on the browser/OS/gamepad combination,
+sadly the `Gamepad API <https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API>`__
+does not provide a reliable way to detect the gamepad information necessary
+to remap them based on model/vendor/OS due to privacy considerations.
+
+.. warning:: Requires a :ref:`secure context <doc_javascript_secure_contexts>`.
 
 Boot splash is not displayed
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -115,22 +201,6 @@ Shader language limitations
 When exporting a GLES2 project to HTML5, WebGL 1.0 will be used. WebGL 1.0
 doesn't support dynamic loops, so shaders using those won't work there.
 
-Unimplemented functionality
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following functionality is currently unavailable on the HTML5 platform:
-
- -  Threads
- -  GDNative
- -  C#
- -  Clipboard synchronization between engine and operating system
- -  Networking other than :ref:`class_HTTPClient` and :ref:`class_WebSocketClient`
-
-.. 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 the functionality you're interested in has an issue yet. If
-         not, open one to communicate your interest.
-
 Serving the files
 -----------------
 
@@ -170,21 +240,7 @@ of its original size with gzip compression.
 **Hosts that provide on-the-fly compression:** GitHub Pages (gzip)
 
 **Hosts that don't provide on-the-fly compression:** itch.io, GitLab Pages
-(`supports manual gzip precompression <https://webd97.de/post/gitlab-pages-compression/>`__
-
-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.
+(`supports manual gzip precompression <https://webd97.de/post/gitlab-pages-compression/>`__)
 
 .. _doc_javascript_eval: