Merge commit godotengine/godot-docs@1d9c4a4

.github/workflows/build_offline_docs.yml

@@ -14,6 +14,8 @@ jobs:
     runs-on: ubuntu-24.04
     timeout-minutes: 180
     strategy:
+      max-parallel: 1
+      fail-fast: false
       matrix:
         branch:
           - master
@@ -44,7 +46,7 @@ jobs:
           echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
           echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
           sudo apt update
-          sudo apt install parallel libwebp7
+          sudo apt install parallel libwebp7 imagemagick
 
       - name: Migrate to Redot
         run: |

.gitignore

@@ -2,15 +2,30 @@
 !redirects.csv
 .env
 
-env/
-__pycache__
-*.pyc
+_build/
 *~
 .directory
 .vs/
 .vscode/
 *.mo
 
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Common environment files
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# User created Python virtual environment as described in the docs
+godot-docs-venv/
+
 # Vim temp files
 *.swo
 *.swp
@@ -44,9 +59,6 @@ logo.h
 tmp-unused-images
 tmp-unused-images-history
 
-# User created Python virtual environement as described in the docs
-godot-docs-venv/
-
 # Jetbrains IDE files
 /.idea/
 

conf.py

@@ -220,6 +220,8 @@
 
 html_js_files = [
     "js/custom.js",
+    ('https://plausible.godot.foundation/js/script.file-downloads.outbound-links.js',
+     {'defer': 'defer', 'data-domain': 'godotengine.org'}),
 ]
 
 # Output file base name for HTML help builder

contributing/development/compiling/compiling_for_ios.rst

@@ -86,3 +86,29 @@ Run
 
 To run on a device or simulator, follow these instructions:
 :ref:`doc_exporting_for_ios`.
+
+Troubleshooting
+---------------
+
+Fatal error: 'cstdint' file not found
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you get a compilation error of this form early on, it's likely because
+the Xcode command line tools installation needs to be repaired after
+a macOS or Xcode update:
+
+::
+
+    ./core/typedefs.h:45:10: fatal error: 'cstdint' file not found
+    45 | #include <cstdint>
+       |          ^~~~~~~~~
+
+Run these two commands to reinstall Xcode command line tools
+(enter your administrator password as needed):
+
+::
+
+    sudo rm -rf /Library/Developer/CommandLineTools
+    sudo xcode-select --install
+
+If it still does not work, try updating Xcode from the Mac App Store and try again.

contributing/development/compiling/compiling_for_linuxbsd.rst

@@ -608,7 +608,7 @@ running ``scons -h``, then looking for options starting with ``builtin_``.
 
 .. warning::
 
-    When using system libraries, the resulting library is **not** portable
+    When using system libraries, the resulting binary is **not** portable
     across Linux distributions anymore. Do not use this approach for creating
     binaries you intend to distribute to others, unless you're creating a
     package for a Linux distribution.

contributing/development/compiling/compiling_for_macos.rst

@@ -57,10 +57,6 @@ To compile for Apple Silicon (ARM64) powered Macs, use::
 
     scons platform=macos arch=arm64
 
-To support both architectures in a single "Universal 2" binary, run the above two commands and then use ``lipo`` to bundle them together::
-
-    lipo -create bin/godot.macos.editor.x86_64 bin/godot.macos.editor.arm64 -output bin/godot.macos.editor.universal
-
 .. tip::
     If you are compiling Godot to make changes or contribute to the engine,
     you may want to use the SCons options ``dev_build=yes`` or ``dev_mode=yes``.
@@ -72,20 +68,39 @@ If all goes well, the resulting binary executable will be placed in the
 runs without any dependencies. Executing it will bring up the Project
 Manager.
 
+.. note:: Using a standalone editor executable is not recommended, it should be always packaged into an
+          ``.app`` bundle to avoid UI activation issues.
+
 .. note:: If you want to use separate editor settings for your own Godot builds
           and official releases, you can enable
           :ref:`doc_data_paths_self_contained_mode` by creating a file called
           ``._sc_`` or ``_sc_`` in the ``bin/`` folder.
 
-To create an ``.app`` bundle like in the official builds, you need to use the
-template located in ``misc/dist/macos_tools.app``. Typically, for an optimized
+Automatic ``.app`` bundle creation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To automatically create an ``.app`` bundle like in the official builds, use the ``generate_bundle=yes`` option on the *last*
+SCons command used to build editor::
+
+    scons platform=macos arch=x86_64
+    scons platform=macos arch=arm64 generate_bundle=yes
+
+Manual ``.app`` bundle creation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To support both architectures in a single "Universal 2" binary,
+run the above two commands and then use ``lipo`` to bundle them together::
+
+    lipo -create bin/godot.macos.editor.x86_64 bin/godot.macos.editor.arm64 -output bin/godot.macos.editor.universal
+
+To create an ``.app`` bundle, you need to use the template located in ``misc/dist/macos_tools.app``. Typically, for an optimized
 editor binary built with ``dev_build=yes``::
 
-    cp -r misc/dist/macos_tools.app ./Godot.app
-    mkdir -p Godot.app/Contents/MacOS
-    cp bin/godot.macos.editor.universal Godot.app/Contents/MacOS/Godot
-    chmod +x Godot.app/Contents/MacOS/Godot
-    codesign --force --timestamp --options=runtime --entitlements misc/dist/macos/editor.entitlements -s - Godot.app
+    cp -r misc/dist/macos_tools.app ./bin/Godot.app
+    mkdir -p bin/Godot.app/Contents/MacOS
+    cp bin/godot.macos.editor.universal bin/Godot.app/Contents/MacOS/Godot
+    chmod +x bin/Godot.app/Contents/MacOS/Godot
+    codesign --force --timestamp --options=runtime --entitlements misc/dist/macos/editor.entitlements -s - bin/Godot.app
 
 .. note::
 
@@ -95,8 +110,8 @@ editor binary built with ``dev_build=yes``::
     You can also choose to link it dynamically by passing ``use_volk=yes`` and
     including the dynamic library in your ``.app`` bundle::
 
-        mkdir -p Godot.app/Contents/Frameworks
-        cp <Vulkan SDK path>/macOS/lib/libMoltenVK.dylib Godot.app/Contents/Frameworks/libMoltenVK.dylib
+        mkdir -p <Godot bundle name>.app/Contents/Frameworks
+        cp <Vulkan SDK path>/macOS/lib/libMoltenVK.dylib <Godot bundle name>.app/Contents/Frameworks/libMoltenVK.dylib
 
 Running a headless/server build
 -------------------------------
@@ -200,3 +215,29 @@ Now you can compile with SCons like you normally would::
 If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument::
 
     scons platform=macos osxcross_sdk=darwin15
+
+Troubleshooting
+---------------
+
+Fatal error: 'cstdint' file not found
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you get a compilation error of this form early on, it's likely because
+the Xcode command line tools installation needs to be repaired after
+a macOS or Xcode update:
+
+::
+
+    ./core/typedefs.h:45:10: fatal error: 'cstdint' file not found
+    45 | #include <cstdint>
+       |          ^~~~~~~~~
+
+Run these two commands to reinstall Xcode command line tools
+(enter your administrator password as needed):
+
+::
+
+    sudo rm -rf /Library/Developer/CommandLineTools
+    sudo xcode-select --install
+
+If it still does not work, try updating Xcode from the Mac App Store and try again.

contributing/development/compiling/introduction_to_the_buildsystem.rst

@@ -69,9 +69,10 @@ To list the available target platforms, use ``scons platform=list``::
     The following platforms are available:
 
         android
-        javascript
+        ios
         linuxbsd
-        server
+        macos
+        web
         windows
 
     Please run SCons again and select a valid platform: platform=<string>
@@ -124,20 +125,24 @@ build targets, and which will be explained below.
 Target
 ------
 
-Target controls if the editor is contained and debug flags are used.
-All builds are optimized. Each mode means:
+The ``target`` option controls if the editor is compiled and debug flags are used.
+Optimization levels (``optimize``) and whether each build contains debug symbols
+(``debug_symbols``) is controlled separately from the target. Each mode means:
 
--  ``target=editor``: Build with editor, optimized, with debugging code (defines: ``TOOLS_ENABLED``, ``DEBUG_ENABLED``, ``-O2``/``/O2``)
--  ``target=template_debug``: Build with C++ debugging symbols (defines: ``DEBUG_ENABLED``, ``-O2``/``/O2``)
--  ``target=template_release``: Build without symbols (defines: ``-O3``/``/O2``)
+-  ``target=editor``: Build an editor binary (defines ``TOOLS_ENABLED`` and ``DEBUG_ENABLED``)
+-  ``target=template_debug``: Build a debug export template (defines ``DEBUG_ENABLED``)
+-  ``target=template_release``: Build a release export template
 
 The editor is enabled by default in all PC targets (Linux, Windows, macOS),
 disabled for everything else. Disabling the editor produces a binary that can
 run projects but does not include the editor or the Project Manager.
 
+The list of :ref:`command line arguments <doc_command_line_tutorial>`
+available varies depending on the build type.
+
 ::
 
-    scons platform=<platform> target=editor/template_debug/template_release
+    scons platform=<platform> target=editor|template_debug|template_release
 
 .. _doc_introduction_to_the_buildsystem_development_and_production_aliases:
 

contributing/development/configuring_an_ide/clion.rst

@@ -81,3 +81,21 @@ You can now build, run, debug, profile, and Valgrind check the Godot editor via
    :align: center
 
 When playing a scene, the Godot editor will spawn a separate process. You can debug this process in CLion by going to **Run > Attach to process...**, typing ``godot``, and selecting the Godot process with the highest **pid** (process ID), which will usually be the running project.
+
+Ignoring object and library files
+-----------------------------------
+
+After building Godot in CLion, you may see the object and library files showing up in the **Project** view.
+
+.. figure:: img/clion-object-library-files-in-project-view.webp
+   :align: center
+
+You can configure CLion to ignore those files:
+
+- Open CLion and navigate to **Preferences > Editor > File Types > Ignored Files and Folders**
+- Click the **+** button to add ``*.o`` and ``*.a`` to the list. In Windows, you would add ``*.obj`` and ``*.dll``.
+
+.. figure:: img/clion-ignore-object-library-files.webp
+   :align: center
+
+Now, the files should be ignored in the Project view.

contributing/development/core_and_modules/common_engine_methods_and_macros.rst

@@ -182,6 +182,8 @@ repetition:
 It's recommended to use ``GLOBAL_DEF``/``EDITOR_DEF`` only once per setting and
 use ``GLOBAL_GET``/``EDITOR_GET`` in all other places where it's referenced.
 
+.. _doc_common_engine_methods_and_macros_error_macros:
+
 Error macros
 ------------
 

contributing/development/core_and_modules/core_types.rst

@@ -103,7 +103,30 @@ which are equivalent to new, delete, new[] and delete[].
 memnew/memdelete also use a little C++ magic and notify Objects right
 after they are created, and right before they are deleted.
 
-For dynamic memory, use Vector<>.
+For dynamic memory, use one of Godot's sequence types such as ``Vector<>``
+or ``LocalVector<>``. ``Vector<>`` behaves much like an STL ``std::vector<>``,
+but is simpler and uses Copy-On-Write (CoW) semantics. CoW copies of
+``Vector<>`` can safely access the same data from different threads, but
+several threads cannot access the same ``Vector<>`` instance safely.
+It can be safely passed via public API if it has a ``Packed`` alias.
+
+The ``Packed*Array`` :ref:`types <doc_gdscript_packed_arrays>` are aliases
+for specific ``Vector<*>`` types (e.g., ``PackedByteArray``,
+``PackedInt32Array``) that are accessible via GDScript. Outside of core,
+prefer using the ``Packed*Array`` aliases for functions exposed to scripts,
+and ``Vector<>`` for other occasions.
+
+``LocalVector<>`` is much more like ``std::vector`` than ``Vector<>``.
+It is non-CoW, with less overhead. It is intended for internal use where
+the benefits of CoW are not needed. Note that neither ``LocalVector<>``
+nor ``Vector<>`` are drop-in replacements for each other. They are two
+unrelated types with similar interfaces, both using a buffer as their
+storage strategy.
+
+``List<>`` is another Godot sequence type, using a doubly-linked list as
+its storage strategy. Prefer ``Vector<>`` (or ``LocalVector<>``) over
+``List<>`` unless you're sure you need it, as cache locality and memory
+fragmentation tend to be more important with small collections.
 
 References:
 ~~~~~~~~~~~

contributing/development/cpp_usage_guidelines.rst

@@ -100,6 +100,15 @@ pull request.
 To follow the existing style, please use standard ``#ifdef``-based include
 guards instead of ``#pragma once`` in new files.
 
+``try``-``catch`` blocks
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+C++ style exception handling using ``try`` and ``catch`` blocks is forbidden.
+This restriction is in place for several reasons, including performance, binary
+size and code complexity.
+Use :ref:`doc_common_engine_methods_and_macros_error_macros` instead.
+
+
 .. seealso::
 
     See :ref:`doc_code_style_guidelines_header_includes` for guidelines on sorting

contributing/documentation/building_the_manual.rst

@@ -162,8 +162,33 @@ RAM for Sphinx alone.
 Specifying a list of files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. warning::
+
+    This section will not work on Windows, since the repository is using
+    a simplified ``make.bat`` script instead of the real GNU Make program.
+    If you would like to get a Linux terminal on your system, consider using
+    `Windows Subsystem for Linux (WSL) <https://learn.microsoft.com/en-us/windows/wsl/>`__.
+
 You can specify a list of files to build, which can greatly speed up compilation:
 
 .. code:: sh
 
     make html FILELIST='classes/class_node.rst classes/class_resource.rst'
+
+The list of files can also be provided by the ``git`` command.
+This way you can automatically get the names of all files that have changed since
+the last commit (``sed`` is used to put them on the same line).
+
+.. code:: sh
+
+    make html FILELIST="$(git diff HEAD --name-only | sed -z 's/\n/ /g')"
+
+You can replace ``HEAD`` with ``master`` to return all files changed from the
+``master`` branch:
+
+.. code:: sh
+
+    make html FILELIST="$(git diff master --name-only | sed -z 's/\n/ /g')"
+
+If any images were modified, the output will contain some warnings about them,
+but the build will proceed correctly.

contributing/documentation/docs_image_guidelines.rst

@@ -242,10 +242,12 @@ videos should be included with the following code snippet::
        :autoplay:
        :loop:
        :muted:
+       :align: default
 
 Where ``documentation_video.webp`` would be changed to the name of the video you
 created. Name your videos in a way that makes their meaning clear, possibly with
 a prefix that makes their relationship to a documentation page explicit.
 
 The ``:autoplay:``, ``:loop:`` and ``:muted:`` flags should always be specified
 unless the video needs to play audio. In this case, do not specify *any* of these flags.
+The ``:align: default`` flag should always be specified.

getting_started/first_2d_game/03.coding_the_player.rst

@@ -399,7 +399,7 @@ Next, add this code to the function:
 .. tabs::
  .. code-tab:: gdscript GDScript
 
-    func _on_body_entered(body):
+    func _on_body_entered(_body):
         hide() # Player disappears after being hit.
         hit.emit()
         # Must be deferred as we can't change physics properties on a physics callback.