mirror of
https://github.com/stan220/godot-docs.git
synced 2026-09-08 20:29:03 +00:00
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.
This commit is contained in:
Fabio Alessandrelli
@@ -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
|
||||
-----------------------------------------------
|
||||
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 <doc_javascript_export_options>` 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 <doc_javascript_export_options>` for the web
|
||||
server requirements.
|
||||
|
||||
@@ -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>`.
|
||||
|
||||
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 <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
|
||||
~~~~~~~~~
|
||||
|
||||
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 <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
|
||||
~~~~~~~~
|
||||
|
||||
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:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user