[stable] Merge commit godotengine/godot-docs@4b616e1

about/faq.rst

@@ -167,6 +167,38 @@ The main reasons for creating a custom scripting language for Godot were:
 
 GDScript was designed to curtail the issues above, and more.
 
+.. _doc_faq_which_programming_language_is_fastest:
+
+Which programming language is fastest?
+--------------------------------------
+
+In most games, the *scripting language* itself is not the cause of performance
+problems. Instead, performance is slowed by inefficient algorithms (which are
+slow in all languages), by GPU performance, or by the common C++ engine code
+like physics or navigation. All languages supported by Godot are fast enough for
+general-purpose scripting. You should choose a language based on other factors,
+like ease-of-use, familiarity, platform support, or language features.
+
+In general, the performance of C# and GDScript is within the same order of
+magnitude, and C++ is faster than both.
+
+Comparing GDScript performance to C# is tricky, since C# can be faster in some
+specific cases. The C# *language* itself tends to be faster than GDScript, which
+means that C# can be faster in situations with few calls to Godot engine code.
+However, C# can be slower than GDScript when making many Godot API calls, due
+to the cost of *marshalling*. C#'s performance can also be brought down by garbage
+collection which occurs at random and unpredictable moments. This can result in
+stuttering issues in complex projects, and is not exclusive to Godot.
+
+C++, using :ref:`GDExtension <doc_what_is_gdextension>`, will almost always be
+faster than either C# or GDScript. However, C++ is less easy to use than C# or
+GDScript, and is slower to develop with.
+
+You can also use multiple languages within a single project, with
+:ref:`cross-language scripting <doc_cross_language_scripting>`, or by using
+GDExtension and scripting languages together. Be aware that doing so comes with
+its own complications.
+
 What 3D model formats does Godot support?
 -----------------------------------------
 

community/tutorials.rst

@@ -3,7 +3,10 @@
 Tutorials and resources
 =======================
 
-This is a list of third-party tutorials and resources created by the Godot community. For resources, remember that there is the official `Godot Asset Library <https://godotengine.org/asset-library/asset>`_ full of official and community resources too! Also, have a look at this `huge list over at Reddit <https://www.reddit.com/r/godot/comments/an0iq5/godot_tutorials_list_of_video_and_written/>`_.
+This is a list of third-party tutorials and resources created by the Godot
+community. For resources, remember that there is the official
+`Godot Asset Library <https://godotengine.org/asset-library/asset>`_ full of
+official and community resources too!
 
 Think there is something missing here? Feel free to submit a `Pull Request <https://github.com/godotengine/godot-docs/blob/master/community/tutorials.rst>`_ as always.
 

contributing/development/compiling/compiling_for_ios.rst

@@ -20,9 +20,6 @@ Requirements
       Xcode and need to install iOS support, go to *Xcode -> Settings... -> Platforms*.
     - Go to *Xcode -> Settings... -> Locations -> Command Line Tools* and select
       an installed version. Even if one is already selected, re-select it.
-
-If you are building the ``master`` branch:
-
 -  Download and follow README instructions to build a static ``.xcframework``
    from the `MoltenVK SDK <https://github.com/KhronosGroup/MoltenVK#fetching-moltenvk-source-code>`__.
 
@@ -49,46 +46,40 @@ If you are building the ``master`` branch:
 Compiling
 ---------
 
-Open a Terminal, go to the root dir of the engine source code and type:
+Open a Terminal, go to the root folder of the engine source code and type
+the following to compile a debug build:
 
 ::
 
-    scons platform=ios target=template_debug
+    scons platform=ios target=template_debug generate_bundle=yes
 
-for a debug build, or:
+To compile a release build:
 
 ::
 
-    scons platform=ios target=template_release
-
-for a release build (check ``platform/ios/detect.py`` for the compiler
-flags used for each configuration).
+    scons platform=ios target=template_release generate_bundle=yes
 
-Alternatively, you can run
+Alternatively, you can run the following command for Xcode simulator libraries (optional):
 
 ::
 
-    scons platform=ios target=template_debug ios_simulator=yes arch=x86_64
     scons platform=ios target=template_debug ios_simulator=yes arch=arm64
+    scons platform=ios target=template_debug ios_simulator=yes arch=x86_64 generate_bundle=yes
 
-for a Simulator libraries.
+These simulator libraries cannot be used to run the exported project on the
+target device. Instead, they can be used to run the exported project directly on
+your Mac while still testing iOS platform-specific functionality.
 
 To create an Xcode project like in the official builds, you need to use the
 template located in ``misc/dist/ios_xcode``. The release and debug libraries
-should be placed in ``libgodot.ios.debug.xcframework`` and ``libgodot.ios.release.xcframework`` respectively.
-
-::
-
-    cp -r misc/dist/ios_xcode .
-
-    cp libgodot.ios.template_debug.arm64.a ios_xcode/libgodot.ios.debug.xcframework/ios-arm64/libgodot.a
-    lipo -create libgodot.ios.template_debug.arm64.simulator.a libgodot.ios.template_debug.x86_64.simulator.a -output ios_xcode/libgodot.ios.debug.xcframework/ios-arm64_x86_64-simulator/libgodot.a
-
-    cp libgodot.ios.template_release.arm64.a ios_xcode/libgodot.ios.release.xcframework/ios-arm64/libgodot.a
-    lipo -create libgodot.ios.template_release.arm64.simulator.a libgodot.ios.template_release.x86_64.simulator.a -output ios_xcode/libgodot.ios.release.xcframework/ios-arm64_x86_64-simulator/libgodot.a
-
-The MoltenVK static ``.xcframework`` folder must also be placed in the ``ios_xcode``
-folder once it has been created.
+should be placed in ``libgodot.ios.debug.xcframework`` and
+``libgodot.ios.release.xcframework`` respectively. This process can be automated
+by using the ``generate_bundle=yes`` option on the *last* SCons command used to
+build export templates (so that all binaries can be included).
+
+The MoltenVK static ``.xcframework`` folder must also be placed in the
+``ios_xcode`` folder once it has been created. MoltenVK is always statically
+linked on iOS; there is no dynamic linking option available, unlike macOS.
 
 Run
 ---

contributing/development/compiling/compiling_for_linuxbsd.rst

@@ -248,6 +248,12 @@ Start a terminal, go to the root dir of the engine source code and type:
     ``linuxbsd``. If you are looking to compile Godot 3.x, make sure to use the
     `3.x branch of this documentation <https://docs.godotengine.org/en/3.6/development/compiling/compiling_for_x11.html>`__.
 
+.. 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``.
+    See :ref:`doc_introduction_to_the_buildsystem_development_and_production_aliases`
+    for more info.
+
 If all goes well, the resulting binary executable will be placed in the
 "bin" subdirectory. This executable file contains the whole engine and
 runs without any dependencies. Executing it will bring up the Project
@@ -573,34 +579,3 @@ running ``scons -h``, then looking for options starting with ``builtin_``.
     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.
-
-Using Pyston for faster development
------------------------------------
-
-You can use `Pyston <https://www.pyston.org/>`__ to run SCons. Pyston is a JIT-enabled
-implementation of the Python language (which SCons is written in). It is currently
-only compatible with Linux. Pyston can speed up incremental builds significantly,
-often by a factor between 1.5× and 2×. Pyston can be combined with Clang and LLD
-to get even faster builds.
-
-- Download the `latest portable Pyston release <https://github.com/pyston/pyston/releases/latest>`__.
-- Extract the portable ``.tar.gz`` to a set location, such as ``$HOME/.local/opt/pyston/`` (create folders as needed).
-- Use ``cd`` to reach the extracted Pyston folder from a terminal,
-  then run ``./pyston -m pip install scons`` to install SCons within Pyston.
-- To make SCons via Pyston easier to run, create a symbolic link of its wrapper
-  script to a location in your ``PATH`` environment variable::
-
-    ln -s ~/.local/opt/pyston/bin/scons ~/.local/bin/pyston-scons
-
-- Instead of running ``scons <build arguments>``, run ``pyston-scons <build arguments>``
-  to compile Godot.
-
-If you can't run ``pyston-scons`` after creating the symbolic link,
-make sure ``$HOME/.local/bin/`` is part of your user's ``PATH`` environment variable.
-
-.. note::
-
-    Alternatively, you can run ``python -m pip install pyston_lite_autoload``
-    then run SCons as usual. This will automatically load a subset of Pyston's
-    optimizations in any Python program you run. However, this won't bring as
-    much of a performance improvement compared to installing "full" Pyston.

contributing/development/compiling/compiling_for_macos.rst

@@ -59,6 +59,12 @@ To support both architectures in a single "Universal 2" binary, run the above tw
 
     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``.
+    See :ref:`doc_introduction_to_the_buildsystem_development_and_production_aliases`
+    for more info.
+
 If all goes well, the resulting binary executable will be placed in the
 ``bin/`` subdirectory. This executable file contains the whole engine and
 runs without any dependencies. Executing it will bring up the Project
@@ -119,70 +125,46 @@ To build macOS export templates, you have to compile using the targets without
 the editor: ``target=template_release`` (release template) and
 ``target=template_debug``.
 
-Official templates are universal binaries which support both Intel x86_64 and
-ARM64 architectures. You can also create export templates that support only one
-of those two architectures by leaving out the ``lipo`` step below.
+Official templates are *Universal 2* binaries which support both ARM64 and Intel
+x86_64 architectures.
 
-- For Intel x86_64::
+- To support ARM64 (Apple Silicon) + Intel x86_64::
 
-    scons platform=macos target=template_release arch=x86_64
+    scons platform=macos target=template_debug arch=arm64
+    scons platform=macos target=template_release arch=arm64
     scons platform=macos target=template_debug arch=x86_64
+    scons platform=macos target=template_release arch=x86_64 generate_bundle=yes
 
-- For Arm64 (Apple M1)::
+- To support ARM64 (Apple Silicon) only (smaller file size, but less compatible with older hardware)::
 
-    scons platform=macos target=template_release arch=arm64
     scons platform=macos target=template_debug arch=arm64
-
-To support both architectures in a single "Universal 2" binary, run the above
-two commands blocks and then use ``lipo`` to bundle them together::
-
-    lipo -create bin/godot.macos.template_release.x86_64 bin/godot.macos.template_release.arm64 -output bin/godot.macos.template_release.universal
-    lipo -create bin/godot.macos.template_debug.x86_64 bin/godot.macos.template_debug.arm64 -output bin/godot.macos.template_debug.universal
+    scons platform=macos target=template_release arch=arm64 generate_bundle=yes
 
 To create an ``.app`` bundle like in the official builds, you need to use the
-template located in ``misc/dist/macos_template.app``. The release and debug
-builds should be placed in ``macos_template.app/Contents/MacOS`` with the names
-``godot_macos_release.universal`` and ``godot_macos_debug.universal`` respectively. You can do so
-with the following commands (assuming a universal build, otherwise replace the
-``.universal`` extension with the one of your arch-specific binaries)::
-
-    cp -r misc/dist/macos_template.app .
-    mkdir -p macos_template.app/Contents/MacOS
-    cp bin/godot.macos.template_release.universal macos_template.app/Contents/MacOS/godot_macos_release.universal
-    cp bin/godot.macos.template_debug.universal macos_template.app/Contents/MacOS/godot_macos_debug.universal
-    chmod +x macos_template.app/Contents/MacOS/godot_macos*
+template located in ``misc/dist/macos_template.app``. This process can be automated by using
+the ``generate_bundle=yes`` option on the *last* SCons command used to build export templates
+(so that all binaries can be included). This option also takes care of calling ``lipo`` to create
+an *Universal 2* binary from two separate ARM64 and x86_64 binaries (if both were compiled beforehand).
 
 .. note::
 
-    If you are building the ``master`` branch, you also need to include support
-    for the MoltenVK Vulkan portability library. By default, it will be linked
-    statically from your installation of the Vulkan SDK for macOS.
-    You can also choose to link it dynamically by passing ``use_volk=yes`` and
-    including the dynamic library in your ``.app`` bundle::
+    You also need to include support for the MoltenVK Vulkan portability
+    library. By default, it will be linked statically from your installation of
+    the Vulkan SDK for macOS. You can also choose to link it dynamically by
+    passing ``use_volk=yes`` and including the dynamic library in your ``.app``
+    bundle::
 
         mkdir -p macos_template.app/Contents/Frameworks
         cp <Vulkan SDK path>/macOS/libs/libMoltenVK.dylib macos_template.app/Contents/Frameworks/libMoltenVK.dylib
 
+    In most cases, static linking should be preferred as it makes distribution
+    easier. The main upside of dynamic linking is that it allows updating
+    MoltenVK without having to recompile export templates.
+
 You can then zip the ``macos_template.app`` folder to reproduce the ``macos.zip``
 template from the official Godot distribution::
 
-    zip -q -9 -r macos.zip macos_template.app
-
-Using Pyston for faster development
------------------------------------
-
-You can use `Pyston <https://www.pyston.org/>`__ to run SCons. Pyston is a
-JIT-enabled implementation of the Python language (which SCons is written in).
-Its "full" version is currently only compatible with Linux, but Pyston-lite is
-also compatible with macOS (both x86 and ARM). Pyston can speed up incremental
-builds significantly, often by a factor between 1.5× and 2×. Pyston can be
-combined with alternative linkers such as LLD or Mold to get even faster builds.
-
-To install Pyston-lite, run ``python -m pip install pyston_lite_autoload`` then
-run SCons as usual. This will automatically load a subset of Pyston's
-optimizations in any Python program you run. However, this won't bring as much
-of a performance improvement compared to installing "full" Pyston (which
-currently can't be done on macOS).
+    zip -r9 macos.zip macos_template.app
 
 Cross-compiling for macOS from Linux
 ------------------------------------

contributing/development/compiling/compiling_for_web.rst

@@ -125,7 +125,7 @@ server requirements.
         python platform/web/serve.py
 
     This will serve the contents of the ``bin/`` folder and open the default web
-    browser automatically. In the page that opens, access ``godot.tools.html``
+    browser automatically. In the page that opens, access ``godot.editor.html``
     and you should be able to test the web editor this way.
 
     Note that for production use cases, this Python-based web server should not

contributing/development/compiling/compiling_for_windows.rst

@@ -146,6 +146,12 @@ the engine source code (using ``cd``) and type:
 .. note:: When compiling with multiple CPU threads, SCons may warn about
           pywin32 being missing. You can safely ignore this warning.
 
+.. 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``. 
+    See :ref:`doc_introduction_to_the_buildsystem_development_and_production_aliases`
+    for more info.
+
 If all goes well, the resulting binary executable will be placed in
 ``C:\godot\bin\`` with the name ``godot.windows.editor.x86_32.exe`` or
 ``godot.windows.editor.x86_64.exe``. By default, SCons will build a binary matching

contributing/development/compiling/introduction_to_the_buildsystem.rst

@@ -139,6 +139,8 @@ run projects but does not include the editor or the Project Manager.
 
     scons platform=<platform> target=editor/template_debug/template_release
 
+.. _doc_introduction_to_the_buildsystem_development_and_production_aliases:
+
 Development and production aliases
 ----------------------------------
 

contributing/development/core_and_modules/custom_resource_format_loaders.rst

@@ -269,7 +269,7 @@ calls into ``std::istream``.
 
 .. code-block:: cpp
 
-    #include "core/os/file_access.h"
+    #include "core/io/file_access.h"
 
     #include <istream>
     #include <streambuf>
@@ -304,7 +304,7 @@ References
 
 - `istream <https://cplusplus.com/reference/istream/istream/>`_
 - `streambuf <https://cplusplus.com/reference/streambuf/streambuf/?kw=streambuf>`_
-- `core/io/file_access.h <https://github.com/godotengine/godot/blob/master/core/os/file_access.h>`_
+- `core/io/file_access.h <https://github.com/godotengine/godot/blob/master/core/io/file_access.h>`_
 
 Registering the new file format
 -------------------------------

contributing/development/core_and_modules/internal_rendering_architecture.rst

@@ -228,8 +228,8 @@ support Vulkan. OpenGL 3.3 Core Profile is used on desktop platforms to run this
 driver, as most graphics drivers on desktop don't support OpenGL ES.
 WebGL 2.0 is used for web exports.
 
-It is possible to use the use of OpenGL ES 3.0 directly on desktop platforms
-using the ``--rendering-driver opengl3_es`` command line argument, although this
+It is possible to use OpenGL ES 3.0 directly on desktop platforms
+by passing the ``--rendering-driver opengl3_es`` command line argument, although this
 will only work on graphics drivers that feature native OpenGL ES support (such
 as Mesa).
 

contributing/development/core_and_modules/object_class.rst

@@ -274,7 +274,7 @@ References:
 Resources
 ----------
 
-:ref:`Resource <class_resource>` inherits from Reference, so all resources
+:ref:`Resource <class_resource>` inherits from RefCounted, so all resources
 are reference counted. Resources can optionally contain a path, which
 reference a file on disk. This can be set with ``resource.set_path(path)``,
 though this is normally done by the resource loader. No two different

getting_started/first_2d_game/02.player_scene.rst

@@ -20,8 +20,16 @@ what the object *is*. Click the "Other Node" button and add an :ref:`Area2D
 
 .. image:: img/add_node.webp
 
-Godot will display a warning icon next to the node in the scene tree. You can
-ignore it for now. We will address it later.
+When you add the ``Area2D`` node, Godot will display the following **warning icon** 
+next to it in the scene tree:
+
+.. image:: img/no_shape_warning.webp
+
+This warning tells us that the ``Area2D`` node requires a shape to detect collisions or overlaps. 
+We can **ignore the warning temporarily** because we will first set up the player's visuals 
+(using an animated sprite). Once the visuals are ready, we will add a collision shape as a child 
+node. This will allow us to accurately size and position the shape based on the sprite’s appearance.
+
 
 With ``Area2D`` we can detect objects that overlap or run into the player.
 Change the node's name to ``Player`` by double-clicking on it. Now that we've
@@ -98,6 +106,9 @@ When you're finished, your ``Player`` scene should look like this:
 
 .. image:: img/player_scene_nodes.webp
 
+Once this is done, the warning on the ``Area2D`` node will disappear, as it now has 
+a shape assigned and can interact with other objects.
+
 Make sure to save the scene again after these changes.
 
 In the next part, we'll add a script to the player node to move and animate it.

tutorials/3d/introduction_to_3d.rst

@@ -19,10 +19,9 @@ which are almost identical to their 2D counterparts.
    `Github repository <https://github.com/godotengine/tps-demo>`__ or the 
    :ref:`Asset Library <doc_project_manager_downloading_demos>`.
 
-In 3D, math is a little more complex than in 2D, so also checking the
-:ref:`doc_vector_math` entry in the wiki (which was especially created for game
-developers, not mathematicians or engineers) will help pave the way for you
-to develop 3D games efficiently.
+In 3D, math is a little more complex than in 2D. For an introduction to the
+relevant math written for game developers, not mathemeticians or engineers,
+check out :ref:`doc_vector_math` and :ref:`doc_using_transforms`.
 
 3D workspace
 ~~~~~~~~~~~~