godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-03 05:48:42 +03:00
Code Issues Packages Projects Releases Wiki Activity

Document exporting as progressive web app in Exporting for the web

Browse Source 
- Document no-threads web export and its limitations.
- Document sample-based audio playback and its limitations.
- Mention that threading issues can be worked around by exporting
  as a progressive web app.
This commit is contained in:
Hugo Locurcio
2024-11-08 19:52:51 +01:00
committed by Max Hilbrunner
parent 39bb9f4b54
commit 73e706cab7
4 changed files with 128 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
tutorials/audio/audio_buses.rst
View File

@@ -88,6 +88,16 @@ Finally, toggle the **Playing** property to **On** and sound will flow.
Adding effects
--------------
.. warning::
This feature is not supported on the web platform if the AudioStreamPlayer's
playback mode is set to **Sample**, which is the default. It will only work if the
playback mode is set to **Stream**, at the cost of increased latency if threads
are not enabled.
See :ref:`Audio playback in the Exporting for the Web documentation <doc_exporting_for_web_audio_playback>`
for details.
Audio buses can contain all sorts of effects. These effects modify the sound in
one way or another and are applied in order.

20
tutorials/audio/audio_streams.rst
View File

@@ -80,6 +80,16 @@ Unlike for 2D, the 3D version of AudioStreamPlayer has a few more advanced optio
Reverb buses
~~~~~~~~~~~~
.. warning::
This feature is not supported on the web platform if the AudioStreamPlayer's
playback mode is set to **Sample**, which is the default. It will only work if the
playback mode is set to **Stream**, at the cost of increased latency if threads
are not enabled.
See :ref:`Audio playback in the Exporting for the Web documentation <doc_exporting_for_web_audio_playback>`
for details.
Godot allows for 3D audio streams that enter a specific Area3D node to send dry
and wet audio to separate buses. This is useful when you have several reverb
configurations for different types of rooms. This is done by enabling this type
@@ -102,6 +112,16 @@ that effect.
Doppler
~~~~~~~
.. warning::
This feature is not supported on the web platform if the AudioStreamPlayer's
playback mode is set to **Sample**, which is the default. It will only work if the
playback mode is set to **Stream**, at the cost of increased latency if threads
are not enabled.
See :ref:`Audio playback in the Exporting for the Web documentation <doc_exporting_for_web_audio_playback>`
for details.
When the relative velocity between an emitter and listener changes, this is
perceived as an increase or decrease in the pitch of the emitted sound.
Godot can track velocity changes in the AudioStreamPlayer3D and Camera nodes.

3
tutorials/editor/using_the_web_editor.rst
View File

@@ -69,7 +69,8 @@ of the Web platform:
.. seealso::
See the
`list of open issues on GitHub related to the web editor <https://github.com/godotengine/godot/issues?q=is%3Aopen+is%3Aissue+label%3Aplatform%3Ahtml5+label%3Atopic%3Aeditor>`__ for a list of known bugs.
`list of open issues on GitHub related to the web editor <https://github.com/godotengine/godot/issues?q=is%3Aopen+is%3Aissue+label%3Aplatform%3Aweb+label%3Atopic%3Aeditor>`__
for a list of known bugs.
Importing a project
-------------------

117
tutorials/export/exporting_for_web.rst
View File

@@ -11,8 +11,7 @@ Exporting for the Web
HTML5 export allows publishing games made in Godot Engine to the browser.
This requires support for `WebAssembly
<https://webassembly.org/>`__, `WebGL <https://www.khronos.org/webgl/>`__ and
`SharedArrayBuffer <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer>`_
<https://webassembly.org/>`__ and `WebGL 2.0 <https://www.khronos.org/webgl/>`__
in the user's browser.
.. attention::
@@ -26,21 +25,16 @@ in the user's browser.
with :kbd:`F12` (:kbd:`Cmd + Option + I` on macOS), to view
**debug information** like JavaScript, engine, and WebGL errors.
.. attention::
.. seealso::
Godot 4's HTML5 exports currently cannot run on macOS and iOS due to upstream bugs
with SharedArrayBuffer and WebGL 2.0. We recommend using
:ref:`macOS <doc_exporting_for_macos>` and :ref:`iOS <doc_exporting_for_ios>`
native export functionality instead, as it will also result in better performance.
Godot 3's HTML5 exports are more compatible with various browsers in
general, especially when using the GLES2 rendering backend (which only
requires WebGL 1.0).
See the
`list of open issues on GitHub related to the web export <https://github.com/godotengine/godot/issues?q=is%3Aopen+is%3Aissue+label%3Aplatform%3Aweb>`__
for a list of known bugs.
Export file name
----------------
We do suggest users to export their Web projects with ``index.html`` as the file name.
We suggest users to export their Web projects with ``index.html`` as the file name.
``index.html`` is usually the default file loaded by web servers when accessing the
parent directory, usually hiding the name of that file.
@@ -54,13 +48,38 @@ WebGL version
-------------
Godot 4.0 and later can only target WebGL 2.0 (using the Compatibility rendering
method). There is no stable way to run Vulkan applications on the web yet.
method). Forward+/Mobile are not supported on the web platform, as these
rendering methods are designed around modern low-level graphics APIs. Godot
currently does not support WebGPU, which is a prerequisite for allowing
Forward+/Mobile to run on the web platform.
See `Can I use WebGL 2.0 <https://caniuse.com/webgl2>`__ for a list of browser
versions supporting WebGL 2.0. Note that Safari has several issues with WebGL
2.0 support that other browsers don't have, so we recommend using a
Chromium-based browser or Firefox if possible.
.. _doc_exporting_for_web_audio_playback:
Audio playback
--------------
Since Godot 4.3, audio playback is done using the Web Audio API on the web
platform. This **Sample** playback mode allows for low latency even when the
project is exported without thread support, but it has several limitations:
- AudioEffects are not supported.
- :ref:`Reverberation and doppler <doc_audio_streams_reverb_buses>` effects are not supported.
- Procedural audio generation is not supported.
- Positional audio may not always work correctly depending on the node's properties.
To use Godot's own audio playback system on the web platform, you can change the
default playback mode using the **Audio > General > Default Playback Type.web**
project setting, or change the **Playback Type** property to **Stream** on an
:ref:`class_AudioStreamPlayer`, :ref:`class_AudioStreamPlayer2D` or
:ref:`class_AudioStreamPlayer3D` node. This leads to increased latency
(especially when thread support is disabled), but it allows the full suite
of Godot's audio features to work.
.. _doc_javascript_export_options:
Export options
@@ -73,7 +92,7 @@ game in the default browser for testing.
If your project uses GDExtension **Extension Support** needs to be enabled.
If you plan to use :ref:`VRAM compression <doc_importing_images>` make sure that
**Vram Texture Compression** is enabled for the targeted platforms (enabling
**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).
@@ -91,6 +110,59 @@ JavaScript APIs, include CSS, or run JavaScript code.
To customize the generated file, use the **Custom HTML shell**
option.
.. _doc_exporting_for_web_thread_extension_support:
Thread and extension support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If **Thread Support** is enabled, the exported project will be able to
:ref:`make use of multithreading <doc_using_multiple_threads>` to improve
performance. This also allows for low-latency audio playback
when the playback type is set to **Stream** (instead of the default **Sample**
that is used in web exports). Enabling this feature requires the use of
cross-origin isolation headers, which are described in the
:ref:`doc_exporting_for_web_serving_the_files` section below.
If **Extensions Support** is enabled, :ref:`GDExtensions <doc_what_is_gdextension>`
will be able to be loaded. Note that GDExtensions still need to be specifically
compiled for the web platform to work. Like thread support, enabling this feature
requires the use of cross-origin isolation headers.
Exporting as a Progressive Web App (PWA)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If **Progressive Web App > Enable** is enabled, it will have several effects:
- Configure high-resolution icons, a display mode and screen orientation. These
are configured at the end of the Progressive Web App section in the export
options. These options are used if the user adds the project to their device's
homescreen, which is common on mobile platforms. This is also supported on
desktop platforms, albeit in a more limited capacity.
- Allow the project to be loaded without an Internet connection if it has been
loaded at least once beforehand. This works thanks to the *service worker*
that is installed when the project is first loaded in the user's browser. This
service worker provides a local fallback when no Internet connection is
available.
- Note that web browsers can choose to evict the cached data if the user runs
low on disk space, or if the user hasn't opened the project for a while.
To ensure data is cached for a longer duration, the user can bookmark the page,
or ideally add it to their device's home screen.
- If the offline data is not available because it was evicted from the cache,
you can configure an **Offline Page** that will be displayed in this case.
The page must be in HTML format and will be saved on the client's machine
the first time the project is loaded.
- Ensure cross-origin isolation headers are always present, even if the web
server hasn't been configured to send them. This allows exports with threads
enabled to work when hosted on any website, even if there is no way for you to
control the headers it sends.
- This behavior can be disabled by unchecking **Enable Cross Origin Isolation Headers**
in the Progressive Web App section.
Limitations
-----------
@@ -218,8 +290,8 @@ used, see :ref:`doc_customizing_html5_shell`.
.. warning::
To ensure low audio latency and the ability to use :ref:`class_Thread` in web exports,
Godot 4 web exports always use
If either :ref:`thread support or extension support <doc_exporting_for_web_thread_extension_support>`
are enabled, the exported project will require
`SharedArrayBuffer <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer>`__.
This requires a :ref:`secure context <doc_javascript_secure_contexts>`,
while also requiring the following CORS headers to be set when serving the files:
@@ -230,11 +302,13 @@ used, see :ref:`doc_customizing_html5_shell`.
Cross-Origin-Embedder-Policy: require-corp
If you don't control the web server or are unable to add response headers,
use `coi-serviceworker <https://github.com/gzuidhof/coi-serviceworker>`__
as a workaround.
check **Progressive Web App > Enable** in the export options. This applies
a service worker-based workaround that allows the project to run by
simulating the presence of these response headers. A secure context
is still required in this case.
If the client doesn't receive the required response headers,
**the project will not run**.
If the client doesn't receive the required response headers or the service
worker-based workaround is not applied, **the project will not run**.
The generated ``.html`` file can be used as ``DirectoryIndex`` in Apache
servers and can be renamed to e.g. ``index.html`` at any time. Its name is
@@ -302,7 +376,8 @@ supported on your web server for further file size savings.
Interacting with the browser and JavaScript
-------------------------------------------
See the :ref:`dedicated page <doc_web_javascript_bridge>` on how to interact with JavaScript and access some unique Web browser features.
See the :ref:`dedicated page <doc_web_javascript_bridge>` on how to interact
with JavaScript and access some unique Web browser features.
Environment variables
---------------------