From b6f33a8e250236d5ddfcff3b08a1d97f55955e2d Mon Sep 17 00:00:00 2001 From: Fabio Alessandrelli Date: Fri, 11 Dec 2020 19:06:24 +0100 Subject: [PATCH 1/3] 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. (cherry picked from commit 6d36e32eb5db260ac39b37fb594298bddea8b379) --- .../workflow/export/exporting_for_web.rst | 162 ++++++++++++------ 1 file changed, 108 insertions(+), 54 deletions(-) diff --git a/getting_started/workflow/export/exporting_for_web.rst b/getting_started/workflow/export/exporting_for_web.rst index c7c0aca21..518cd6caa 100644 --- a/getting_started/workflow/export/exporting_for_web.rst +++ b/getting_started/workflow/export/exporting_for_web.rst @@ -12,27 +12,11 @@ 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 `__. - -.. attention:: `There are significant bugs when running HTML5 projects on iOS `__ +.. attention:: `There are significant bugs when running HTML5 projects on iOS `__ (regardless of the browser). We recommend using :ref:`iOS' native export functionality ` instead, as it will also result in better performance. -.. note:: - - If you use Linux, due to - `poor Firefox WebGL performance `__, - it's recommended to play the exported project using a Chromium-based browser - instead of Firefox. - WebGL 2 ------- @@ -49,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 `__ +- *GDNative*: enables GDNative support but makes the binary bigger and slower to load. + +If you plan to use :ref:`VRAM compression ` 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 ```` 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 ----------- @@ -56,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 `_, + 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 + `__ + 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -68,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 ` 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 `. + Browsers are also starting to require that the web page is served with specific + `cross-origin isolation headers `__. + +GDNative +~~~~~~~~ + +As mentioned :ref:`above ` 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -82,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 `. -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. @@ -91,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 `__. -:ref:`class_HTTPClient` and :ref:`class_HTTPRequest` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. warning:: Access to microphone requires a + :ref:`secure context `. -The HTTP classes have several restrictions on the HTML5 platform: +Networking +~~~~~~~~~~ + +Low level networking is not implemented due to lacking support in browsers. + +Currently, only :ref:`HTTP client `, +:ref:`HTTP requests `, +:ref:`WebSocket (client) ` and :ref:`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 @@ -103,11 +167,26 @@ The HTTP classes have several restrictions on the HTML5 platform: - Host verification cannot be disabled - Subject to `same-origin policy `__ -Exported ``.html`` file must not be reused -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Clipboard +~~~~~~~~~ -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`. +Clipboard synchronization between engine and the operating system requires a +browser supporting the `Clipboard API `__, +additionally, due to the API asynchronous nature might not be reliable when +accessed from GDScript. + +.. warning:: Requires a :ref:`secure context `. + +Gamepads +~~~~~~~~ + +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 `__ +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 `. Boot splash is not displayed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -122,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 - `__ - to see if the functionality you're interested in has an issue yet. If - not, open one to communicate your interest. - Serving the files ----------------- @@ -174,19 +237,10 @@ the ``.pck`` and ``.wasm`` files, which are usually large in size. The WebAssembly module compresses particularly well, down to around a quarter of its original size with gzip compression. -Export options --------------- +**Hosts that provide on-the-fly compression:** GitHub Pages (gzip) -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 ```` element of the generated -HTML page. This allows to, for example, load webfonts and third-party -JavaScript APIs, include CSS, or run JavaScript code. +**Hosts that don't provide on-the-fly compression:** itch.io, GitLab Pages +(`supports manual gzip precompression `__) .. _doc_javascript_eval: From e4e9cfacf0310adab6c009a5bb276be54c377acd Mon Sep 17 00:00:00 2001 From: Fabio Alessandrelli Date: Sat, 12 Dec 2020 11:48:14 +0100 Subject: [PATCH 2/3] Update compiling for the Web. Bump emscripten requirements, mention threads, gdnative and editor build. (cherry picked from commit 2a209a065e2b7d1f2a334c75101d0466b7f93184) --- development/compiling/compiling_for_web.rst | 74 +++++++++++++-------- 1 file changed, 47 insertions(+), 27 deletions(-) diff --git a/development/compiling/compiling_for_web.rst b/development/compiling/compiling_for_web.rst index 2e54b6cbb..a0033c029 100644 --- a/development/compiling/compiling_for_web.rst +++ b/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+ `__. +- `Emscripten 1.39.9+ `__. - `Python 3.5+ `__. - `SCons 3.0+ `__ 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 ------------------------------------------------ +Threads and GDNative +-------------------- -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 default export templates do not include threads and GDNative support for +performance and compatibility reasons. See the +:ref:`export page ` for more info. -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. +You can build the export templates using the option ``threads_enabled=yes`` or +``gdnative_enabled=yes`` to enable threads or GDNative support:: -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. + 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 ` for the web +server requirements. From 8f2590e8a2dfef3b7b0e510324ae71abbc6cb029 Mon Sep 17 00:00:00 2001 From: Fabio Alessandrelli Date: Fri, 12 Mar 2021 17:59:17 +0100 Subject: [PATCH 3/3] Update the "Customizing the HTML5 Shell" page. Reflecting new changes in master, and upcoming in `3.2.4`. (cherry picked from commit 52d64f0bc36141e9faa25b6fb1e2ea0a7b20f6fd) --- .../platform/customizing_html5_shell.rst | 190 +++++++++--------- 1 file changed, 98 insertions(+), 92 deletions(-) diff --git a/tutorials/platform/customizing_html5_shell.rst b/tutorials/platform/customizing_html5_shell.rst index 248933ba9..3afbfdbe0 100644 --- a/tutorials/platform/customizing_html5_shell.rst +++ b/tutorials/platform/customizing_html5_shell.rst @@ -5,7 +5,7 @@ Custom HTML page for Web export While Web export templates provide a default HTML page fully capable of launching the project without any further customization, it may be beneficial to create a custom -HTML page. While the game itself cannot be directly controlled from the outside, +HTML page. While the game itself cannot easily be directly controlled from the outside yet, such page allows to customize the initialization process for the engine. Some use-cases where customizing the default page is useful include: @@ -20,32 +20,48 @@ Some use-cases where customizing the default page is useful include: The default HTML page is available in the Godot Engine repository at `/misc/dist/html/full-size.html `__ -and can be used as a reference implementation. Another sample HTML page is available at -`/misc/dist/html/fixed-size.html `__. -It differs from the default one by having a fixed size canvas area and an output widget below it. +but the following template can be used as a much simpler example: -.. note:: It is recommended to use developer tools provided by browser vendors to debug - exported projects. Output generated by the engine may be limited and does not - include WebGL errors. +.. code-block:: html + + + + + My Template + + + + + + + + Setup ----- -As evident by the default HTML page, it is mostly a regular HTML document. To work with -Godot projects it needs to be fully realized, to have a control code that calls -the :js:class:`Engine` class, and to provide places for several placeholders, which are -replaced with their actual values during export. +As shown by the example above, it is mostly a regular HTML document, with few placeholders +which needs to be replaced during export, an html ```` element, and some simple +JavaScript code that calls the :js:class:`Engine` class. -.. image:: img/html5_export_options.png +The only required placeholders are: -- ``$GODOT_BASENAME``: - The base name from the *Export Path*, as set up in the export options; suffixes are omitted - (e.g. ``game.html`` becomes ``game``). This variable can be used to generate a path - to the main JavaScript file ``$GODOT_BASENAME.js``, which provides the :js:class:`Engine` - class. A splash image shown during the booting process can be accessed using this variable - as well: ``$GODOT_BASENAME.png``. +- ``$GODOT_URL``: + The name of the main JavaScript file, which provides the :js:class:`Engine` class required + to start the engine and that must be included in the HTML as a ``