Merge commit godotengine/godot-docs@703d0cd

contributing/development/compiling/compiling_for_android.rst

@@ -26,8 +26,8 @@ Requirements
 
 For compiling under Windows, Linux or macOS, the following is required:
 
-- `Python 3.6+ <https://www.python.org/downloads/>`_.
-- `SCons 3.1.2+ <https://scons.org/pages/download.html>`_ build system.
+- `Python 3.8+ <https://www.python.org/downloads/>`_.
+- `SCons 4.0+ <https://scons.org/pages/download.html>`_ build system.
 - `Android SDK <https://developer.android.com/studio/#command-tools>`_
   (command-line tools are sufficient).
 
@@ -228,7 +228,7 @@ root directory with the following arguments:
 
 - You can add the ``debug_symbols=yes`` parameter to include the debug symbols in the generated build.
 
-- You can skip certain architectures depending on your target device to speed up compilation. 
+- You can skip certain architectures depending on your target device to speed up compilation.
 
 Remember to add ``generate_apk=yes`` to the *last* architecture you're building, so that binaries are generated after the build.
 

contributing/development/compiling/compiling_for_ios.rst

@@ -13,8 +13,8 @@ Compiling for iOS
 Requirements
 ------------
 
-- `Python 3.6+ <https://www.python.org/downloads/macos/>`_.
-- `SCons 3.1.2+ <https://scons.org/pages/download.html>`_ build system.
+- `Python 3.8+ <https://www.python.org/downloads/macos/>`_.
+- `SCons 4.0+ <https://scons.org/pages/download.html>`_ build system.
 - `Xcode <https://apps.apple.com/us/app/xcode/id497799835>`_.
     - Launch Xcode once and install iOS support. If you have already launched
       Xcode and need to install iOS support, go to *Xcode -> Settings... -> Platforms*.

contributing/development/compiling/compiling_for_linuxbsd.rst

@@ -17,8 +17,8 @@ For compiling under Linux or other Unix variants, the following is
 required:
 
 - GCC 9+ or Clang 6+.
-- `Python 3.6+ <https://www.python.org/downloads/>`_.
-- `SCons 3.1.2+ <https://scons.org/pages/download.html>`_ build system.
+- `Python 3.8+ <https://www.python.org/downloads/>`_.
+- `SCons 4.0+ <https://scons.org/pages/download.html>`_ build system.
 - pkg-config (used to detect the development libraries listed below).
 - Development libraries:
 

contributing/development/compiling/compiling_for_macos.rst

@@ -15,8 +15,8 @@ Requirements
 
 For compiling under macOS, the following is required:
 
-- `Python 3.6+ <https://www.python.org/downloads/macos/>`_.
-- `SCons 3.1.2+ <https://scons.org/pages/download.html>`_ build system.
+- `Python 3.8+ <https://www.python.org/downloads/macos/>`_.
+- `SCons 4.0+ <https://scons.org/pages/download.html>`_ build system.
 - `Xcode <https://apps.apple.com/us/app/xcode/id497799835>`_
   (or the more lightweight Command Line Tools for Xcode).
 - `Vulkan SDK <https://sdk.lunarg.com/sdk/download/latest/mac/vulkan-sdk.dmg>`_

contributing/development/compiling/compiling_for_web.rst

@@ -16,8 +16,8 @@ Requirements
 To compile export templates for the Web, the following is required:
 
 - `Emscripten 3.1.62+ <https://emscripten.org>`__.
-- `Python 3.6+ <https://www.python.org/>`__.
-- `SCons 3.1.2+ <https://scons.org/pages/download.html>`__ build system.
+- `Python 3.8+ <https://www.python.org/>`__.
+- `SCons 4.0+ <https://scons.org/pages/download.html>`__ build system.
 
 .. seealso:: To get the Godot source code for compiling, see
              :ref:`doc_getting_source`.

contributing/development/compiling/compiling_for_windows.rst

@@ -30,10 +30,10 @@ For compiling under Windows, the following is required:
       Supports ``x86_64`` and ``x86_32`` only.
     - `MinGW-LLVM <https://github.com/mstorsjo/llvm-mingw/releases>`_ with clang can be used as
       an alternative to Visual Studio and MinGW-w64.
-      Supports ``x86_64``, ``x86_32``, and ``arm64``.      
-- `Python 3.6+ <https://www.python.org/downloads/windows/>`_. 
+      Supports ``x86_64``, ``x86_32``, and ``arm64``.
+- `Python 3.8+ <https://www.python.org/downloads/windows/>`_.
   **Make sure to enable the option to add Python to the** ``PATH`` **in the installer.**
-- `SCons 3.1.2+ <https://scons.org/pages/download.html>`_ build system. Using the
+- `SCons 4.0+ <https://scons.org/pages/download.html>`_ build system. Using the
   latest release is recommended, especially for proper support of recent Visual
   Studio releases.
 

contributing/development/compiling/introduction_to_the_buildsystem.rst

@@ -328,7 +328,7 @@ source to initialize any SCons build options passed via the command line:
     use_llvm = "yes"
     extra_suffix = "game_title"
 
-You can also disable some of the builtin modules before compiling, saving some
+You can also disable some of the built-in modules before compiling, saving some
 time it takes to build the engine. See :ref:`doc_optimizing_for_size` page for more details.
 
 .. seealso::

contributing/development/core_and_modules/custom_platform_ports.rst

@@ -170,7 +170,7 @@ or OpenGL ES 3.0, you have two options:
 Distributing a custom platform port
 -----------------------------------
 
-.. warning::
+.. danger::
 
     Before distributing a custom platform port, make sure you're allowed to
     distribute all the code that is being linked against. Console SDKs are

contributing/documentation/docs_image_guidelines.rst

@@ -63,7 +63,7 @@ make an image look clean. Below is an example of good cropping.
 .. image:: img/cropped_image.webp
 
 For cropping Krita is the recommended program. While some screenshot programs do
-have cropping built in it's not always easy to get something precise. And while
+have cropping built-in it's not always easy to get something precise. And while
 Krita is designed as a painting program the cropping tool gives you pixel precision
 by default. Of course, feel free to use a different program you are familiar with.
 

contributing/workflow/bisecting_regressions.rst

@@ -42,7 +42,7 @@ whether the issue is a regression in 4.0 or not.
 - If the issue is **not present** in 3.x, then you can try older 4.0 alphas and
   betas to determine when the regression started.
 
-.. warning::
+.. danger::
 
     Project files may be incompatible between Godot versions.
     **Make a backup of your project** before starting the bisection process.

requirements.txt

@@ -7,7 +7,7 @@ pygments==2.18.0
 
 # Sphinx base and RTD theme.
 sphinx==8.1.3
-sphinx_rtd_theme==3.0.1
+sphinx_rtd_theme==3.0.2
 
 # Sphinx extensions.
 

tutorials/2d/using_tilemaps.rst

@@ -25,7 +25,7 @@ Specifying the TileSet in the TileMapLayer
 ------------------------------------------
 
 If you've followed the previous page on :ref:`doc_using_tilesets`, you should
-have a TileSet resource that is built-in to the TileMapLayer node. This is good for
+have a TileSet resource that is built into the TileMapLayer node. This is good for
 prototyping, but in a real world project, you will generally have multiple
 levels reusing the same tileset.
 

tutorials/3d/3d_antialiasing.rst

@@ -291,6 +291,10 @@ same time.
 Antialiasing comparison
 ~~~~~~~~~~~~~~~~~~~~~~~
 
+.. Note that this table uses emojis, which are not monospaced in most editors.
+.. The table looks malformed but is not. When making changes, check the nearby
+.. lines for guidance.
+
 +--------------------------+--------------------------+--------------------------+--------------------------+--------------------------+--------------------------+--------------------------+
 | Feature                  | MSAA                     | TAA                      | FSR2                     | FXAA                     | SSAA                     | SSRL                     |
 +==========================+==========================+==========================+==========================+==========================+==========================+==========================+

tutorials/audio/audio_buses.rst

@@ -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.
 

tutorials/audio/audio_streams.rst

@@ -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.

tutorials/editor/managing_editor_features.rst

@@ -11,7 +11,7 @@ Introduction
 In certain situations, it may be desirable to limit what features can be used
 in the Godot editor. For example, a UI designer on a team who doesn't need to
 see 3D features, or an educator slowly introducing features to students. Godot
-has a built in system called "feature profiles" to do this.
+has a built-in system called "feature profiles" to do this.
 
 With feature profiles, major features and nodes can be hidden from the editor.
 This only hides parts of the interface and does not actually remove support for

tutorials/editor/using_the_web_editor.rst

@@ -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
 -------------------

tutorials/export/exporting_for_web.rst

@@ -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::
-
-    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.
+.. seealso::
 
-    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
 ---------------------