Merge branch 'master' into 4.6

Author: mhilbrunner

engine_details/development/compiling/compiling_for_linuxbsd.rst

@@ -532,8 +532,8 @@ then use the following SCons command:
 After the build is completed, a new binary with a ``.llvm`` suffix will be
 created in the ``bin/`` folder.
 
-It's still recommended to use GCC for production builds as they can be compiled using
-link-time optimization, making the resulting binaries smaller and faster.
+It's still recommended to use GCC for production builds as it's the compiler used
+for official builds and is more rigorously tested.
 
 If this error occurs:
 

engine_details/editor/creating_icons.rst

@@ -21,32 +21,56 @@ Clone the ``godot`` repository containing all the editor icons:
     git clone https://github.com/godotengine/godot.git
 
 The icons must be created in a vector graphics editor in SVG format. There are
-two main requirements to follow:
+three main requirements to follow:
 
 - Icons must be 16×16. In Inkscape, you can configure the document size in
   **File > Document Properties**.
 - Lines should be snapped to pixels whenever possible to remain crisp at lower DPI.
   You can create a 16×16 grid in Inkscape to make this easier.
+- If the user has configured their editor to use a light theme, Godot will
+  convert the icon's colors based on a
+  `set of predefined color mappings <https://github.com/godotengine/godot/blob/master/editor/themes/editor_color_map.cpp>`__.
+  This is to ensure the icon always displays with a sufficient contrast rate.
+  Try to restrict your icon's color palette to colors found in the list above.
+  Otherwise, your icon may become difficult to read on a light background.
 
 Once you're satisfied with the icon's design, save the icon in the cloned
 repository's ``editor/icons`` folder. The icon name should match the intended
 name in a case-sensitive manner. For example, to create an icon for
 CPUParticles2D, name the file ``CPUParticles2D.svg``.
 
-Color conversion for light editor themes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. tip::
 
-If the user has configured their editor to use a light theme, Godot will
-convert the icon's colors based on a
-`set of predefined color mappings <https://github.com/godotengine/godot/blob/master/editor/themes/editor_color_map.cpp>`__.
-This is to ensure the icon always displays with a sufficient contrast rate.
-Try to restrict your icon's color palette to colors found in the list above.
-Otherwise, your icon may become difficult to read on a light background.
+    You can also browse all existing icons on the
+    `Godot editor icons <https://godotengine.github.io/editor-icons/>`__
+    website.
 
-.. note::
-	To enable color conversion for light editor themes:
-		1. :ui:`Import > Import As > Texture2D`
-		2. Set ``editor/convert_colors_with_editor_theme`` to ``true``
+Import options for custom icons
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For custom icons that are present in projects (as opposed to the engine source code),
+there are two import options you should enable:
+
+Scaling for hiDPI displays
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Icons need to be scaled properly on hiDPI displays to ensure they remain
+crisp and large enough to be readable.
+
+To ensure the icon is rendered at a correct scale on hiDPI displays, select the
+SVG file in the FileSystem dock, enable the **Editor > Scale with Editor Scale**
+option in the Import dock and click :button:`Reimport`. Note that this option is
+only available for icons in SVG format, as it requires the use of a vector
+format to work.
+
+Color conversion for light editor themes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To ensure the icon has its colors converted when the user is using a light
+theme, select the SVG file in the FileSystem dock, enable the **Editor > Convert
+Colors with Editor Theme** option in the Import dock and click
+:button:`Reimport`. Note that this option is only available for icons in SVG
+format, as it requires the use of a vector format to work.
 
 Icon optimization
 ~~~~~~~~~~~~~~~~~
@@ -76,19 +100,18 @@ make a separate pull request for your icons to be available within the editor
 as they can be self-contained.
 
 For specific instructions on how to create module icons, refer to
-:ref:`Creating custom module icons<doc_custom_module_icons>`.
+:ref:`Creating custom module icons <doc_custom_module_icons>`.
 
 Troubleshooting
 ~~~~~~~~~~~~~~~
 
 If icons don't appear in the editor, make sure that:
 
 1. Each icon's filename matches the naming requirement as described previously.
-
-2. ``modules/svg`` is enabled (it should be enabled by default). Without it,
-   icons won't appear in the editor at all.
+2. The ``svg`` module is enabled at compile-time (it is enabled by default).
+   Without this module, icons won't appear in the editor at all.
 
 References
 ~~~~~~~~~~
 
--  `editor/icons <https://github.com/godotengine/godot/tree/master/editor/icons>`__
+-  `editor/icons <https://github.com/godotengine/godot/tree/master/editor/icons>`__

engine_details/file_formats/tscn.rst

@@ -47,12 +47,10 @@ There are five main sections inside the TSCN file:
 3. Nodes
 4. Connections
 
-The file descriptor looks like ``[gd_scene load_steps=4 format=3 uid="uid://cecaux1sm7mo0"]``
-and should be the first entry in the file. The ``load_steps`` parameter is equal to the
-total amount of resources (internal and external) plus one (for the file itself).
-If the file has no resources, ``load_steps`` is omitted. The engine will
-still load the file correctly if ``load_steps`` is incorrect, but this will affect
-loading bars and any other piece of code relying on that value.
+The file descriptor looks like ``[gd_scene format=3 uid="uid://cecaux1sm7mo0"]``
+and should be the first entry in the file. Note that scenes saved before Godot 4.6
+will also have a ``load_steps=<int>`` attribute in the file descriptor. This
+attribute is now deprecated and should be ignored if present.
 
 ``uid`` is a unique string-based identifier representing the scene. This is
 used by the engine to track files that are moved around, even while the editor
@@ -92,15 +90,19 @@ so on. For example, a Node3D looks like:
 
 ::
 
-    [node name="Cube" type="Node3D"]
+    [node name="Cube" type="Node3D" unique_id=224283918]
     transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 1, 2, 3)
 
 The scene tree
 --------------
 
-The scene tree is made up of… nodes! The heading of each node consists of
-its name, parent and (most of the time) a type. For example:
-``[node name="PlayerCamera" type="Camera" parent="Player/Head"]``
+The scene tree is made up of… nodes! The heading of each node consists of its
+name, parent, a unique ID (used to track nodes even if they are moved or
+renamed), and most of the time, a type. For example: ``[node name="PlayerCamera"
+type="Camera" parent="Player/Head" unique_id=1697057368]``
+
+Note that ``unique_id`` is only present in scenes saved with Godot 4.6 or later.
+Therefore, it is not guaranteed to be present.
 
 Other valid keywords include:
 
@@ -120,10 +122,10 @@ the path should be ``"."``. Here is an example scene tree
 
 ::
 
-    [node name="Player" type="Node3D"]                    ; The scene root
-    [node name="Arm" type="Node3D" parent="."]            ; Parented to the scene root
-    [node name="Hand" type="Node3D" parent="Arm"]         ; Child of "Arm"
-    [node name="Finger" type="Node3D" parent="Arm/Hand"]  ; Child of "Hand"
+    [node name="Player" type="Node3D" unique_id=1155673912]                    ; The scene root
+    [node name="Arm" type="Node3D" parent="." unique_id=1010797352]            ; Parented to the scene root
+    [node name="Hand" type="Node3D" parent="Arm" unique_id=536436825]          ; Child of "Arm"
+    [node name="Finger" type="Node3D" parent="Arm/Hand" unique_id=1732647084]  ; Child of "Hand"
 
 .. tip::
 
@@ -138,7 +140,7 @@ collision, visuals (mesh + light) and a camera parented to the RigidBody3D:
 
 ::
 
-    [gd_scene load_steps=4 format=3 uid="uid://cecaux1sm7mo0"]
+    [gd_scene format=3 uid="uid://cecaux1sm7mo0"]
 
     [sub_resource type="SphereShape3D" id="SphereShape3D_tj6p1"]
 
@@ -147,20 +149,20 @@ collision, visuals (mesh + light) and a camera parented to the RigidBody3D:
     [sub_resource type="StandardMaterial3D" id="StandardMaterial3D_k54se"]
     albedo_color = Color(1, 0.639216, 0.309804, 1)
 
-    [node name="Ball" type="RigidBody3D"]
+    [node name="Ball" type="RigidBody3D" unique_id=1358867382]
 
-    [node name="CollisionShape3D" type="CollisionShape3D" parent="."]
+    [node name="CollisionShape3D" type="CollisionShape3D" parent="." unique_id=1279975976]
     shape = SubResource("SphereShape3D_tj6p1")
 
-    [node name="MeshInstance3D" type="MeshInstance3D" parent="."]
+    [node name="MeshInstance3D" type="MeshInstance3D" parent="." unique_id=558852834]
     mesh = SubResource("SphereMesh_4w3ye")
     surface_material_override/0 = SubResource("StandardMaterial3D_k54se")
 
-    [node name="OmniLight3D" type="OmniLight3D" parent="."]
+    [node name="OmniLight3D" type="OmniLight3D" parent="." unique_id=1581292810]
     light_color = Color(1, 0.698039, 0.321569, 1)
     omni_range = 10.0
 
-    [node name="Camera3D" type="Camera3D" parent="."]
+    [node name="Camera3D" type="Camera3D" parent="." unique_id=795715540]
     transform = Transform3D(1, 0, 0, 0, 0.939693, 0.34202, 0, -0.34202, 0.939693, 0, 1, 3)
 
 NodePath
@@ -187,7 +189,7 @@ For example, the ``skeleton`` property in the MeshInstance3D node called
 
 ::
 
-    [node name="mesh" type="MeshInstance3D" parent="Armature01"]
+    [node name="mesh" type="MeshInstance3D" parent="Armature01" unique_id=1638249225]
     skeleton = NodePath("..")
 
 Skeleton3D
@@ -208,7 +210,7 @@ Here's an example of a skeleton node with two bones:
 
 ::
 
-    [node name="Skeleton3D" type="Skeleton3D" parent="PlayerModel/Robot_Skeleton" index="0"]
+    [node name="Skeleton3D" type="Skeleton3D" parent="PlayerModel/Robot_Skeleton" index="0" unique_id=542985694]
     bones/1/position = Vector3(0.114471, 2.19771, -0.197845)
     bones/1/rotation = Quaternion(0.191422, -0.0471201, -0.00831942, 0.980341)
     bones/2/position = Vector3(-2.59096e-05, 0.236002, 0.000347473)
@@ -227,12 +229,12 @@ An example of a :ref:`class_Marker3D` node parented to a bone in Skeleton:
 
 ::
 
-    [node name="GunBone" type="BoneAttachment3D" parent="PlayerModel/Robot_Skeleton/Skeleton3D" index="5"]
+    [node name="GunBone" type="BoneAttachment3D" parent="PlayerModel/Robot_Skeleton/Skeleton3D" index="5" unique_id=63481392]
     transform = Transform3D(0.333531, 0.128981, -0.933896, 0.567174, 0.763886, 0.308015, 0.753209, -0.632331, 0.181604, -0.323915, 1.07098, 0.0497144)
     bone_name = "hand.R"
     bone_idx = 55
 
-    [node name="ShootFrom" type="Marker3D" parent="PlayerModel/Robot_Skeleton/Skeleton3D/GunBone"]
+    [node name="ShootFrom" type="Marker3D" parent="PlayerModel/Robot_Skeleton/Skeleton3D/GunBone" unique_id=679926736]
     transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0.4, 0)
 
 AnimationPlayer
@@ -353,7 +355,7 @@ Here's an example of an ArrayMesh saved to its own ``.tres`` file. Some fields w
 
 ::
 
-    [gd_resource type="ArrayMesh" load_steps=2 format=3 uid="uid://dww8o7hsqrhx5"]
+    [gd_resource type="ArrayMesh" format=3 uid="uid://dww8o7hsqrhx5"]
 
     [ext_resource type="Material" path="res://player/model/playerobot.tres" id="1_r3bjq"]
 
@@ -423,7 +425,7 @@ AnimationPlayer for brevity:
 
 ::
 
-    [gd_scene load_steps=4 format=3 uid="uid://cdyt3nktp6y6"]
+    [gd_scene format=3 uid="uid://cdyt3nktp6y6"]
 
     [sub_resource type="Animation" id="Animation_r2qdp"]
     resource_name = "scale_down"
@@ -450,15 +452,15 @@ AnimationPlayer for brevity:
 
     [sub_resource type="BoxMesh" id="BoxMesh_u688r"]
 
-    [node name="Node3D" type="Node3D"]
+    [node name="Node3D" type="Node3D" unique_id=2076735200]
 
-    [node name="AnimationPlayer" type="AnimationPlayer" parent="."]
+    [node name="AnimationPlayer" type="AnimationPlayer" parent="." unique_id=2139773137]
     autoplay = "scale_down"
     libraries = {
     "": SubResource("AnimationLibrary_4qx36")
     }
 
-    [node name="Box" type="MeshInstance3D" parent="."]
+    [node name="Box" type="MeshInstance3D" parent="." unique_id=711004519]
     mesh = SubResource("BoxMesh_u688r")
 
 For generic property ``value`` tracks, ``keys`` is a dictionary containing 3

getting_started/first_2d_game/02.player_scene.rst

@@ -18,6 +18,14 @@ rule, a scene's root node should reflect the object's desired functionality -
 what the object *is*. In the upper-left corner, in the "Scene" tab, click the
 "Other Node" button and add an :ref:`Area2D <class_Area2D>` node to the scene.
 
+.. note::
+
+    Godot also provides the :ref:`CharacterBody2D <class_CharacterBody2D>` node, 
+    specifically designed for 2D characters, which includes built-in support for some 
+    of the processes explained in this tutorial. In many real world projects, CharacterBody2D 
+    would be a better choice for players and enemies. However, this tutorial focuses on 
+    core concepts that apply to a wider range of nodes and use cases.
+
 .. image:: img/add_node.webp
 
 When you add the ``Area2D`` node, Godot will display the following **warning icon**

index.rst

@@ -48,14 +48,14 @@ To begin reading the relevant documentation, select the tile that matches your p
         }
 
         .grid-item {
-            color: hsla(0, 0%, 100%, 0.9);
             padding: 1rem;
             border-radius: 0.375rem;
             text-align: center;
         }
 
+        .grid-item,
         .grid-item:visited {
-            color: unset;
+            color: hsla(0, 0%, 100%, 0.9);
         }
 
         .grid-item:hover,
@@ -109,7 +109,7 @@ To begin reading the relevant documentation, select the tile that matches your p
     <br>
 
 You can also use the table of contents in the sidebar to easily access
-any section of the documentation for your topic of interest. You can 
+any section of the documentation for your topic of interest. You can
 also use the search function in the top-left corner.
 
 Get involved

tutorials/2d/introduction_to_2d.rst

@@ -300,10 +300,10 @@ Node2D and Control node
 for 2D game objects, and :ref:`Control <class_Control>` is the base node 
 for everything GUI. For 3D, Godot uses the :ref:`Node3D <class_Node3D>` node.
 
-3D in 2D
---------
+Displaying 3D nodes in 2D
+-------------------------
 
-It is possible to display 3D scenes in 2D screen, You can see this in the demo `3D in 2D Viewport <https://godotengine.org/asset-library/asset/2804>`__.
+It is possible to display 3D nodes in a 2D scene by using a :ref:`SubViewport<class_SubViewport>`. You can see this in the demo `3D in 2D Viewport <https://godotengine.org/asset-library/asset/2804>`__.
 
 .. image:: img/3d_in_2d_demo_editor.webp
 

tutorials/export/exporting_for_android.rst

@@ -79,7 +79,7 @@ In that screen, 2 paths need to be set:
 
 - ``Java SDK Path`` should be the location where OpenJDK 17 was installed.
 
-- ``Android Sdk Path`` should be the location where the Android SDK was installed.
+- ``Android SDK Path`` should be the location where the Android SDK was installed. This directory should contain ``platform-tools/adb``.
   - For example ``%LOCALAPPDATA%\Android\Sdk\`` on Windows or ``/Users/$USER/Library/Android/sdk/`` on macOS.
 
 Once that is configured, everything is ready to export to Android!

tutorials/export/exporting_for_linux.rst

@@ -18,6 +18,53 @@ system. When exporting for Linux, the exporter takes all the project files and
 creates a ``data.pck`` file. This file is bundled with a specially optimized
 binary that is smaller, faster and does not contain the editor and debugger.
 
+Architecture
+------------
+
+There are 7 different processor architectures that exported Godot projects can run
+on in Linux:
+
+- x86_64
+- x86_32
+- arm64
+- arm32
+- rv64
+- ppc64
+- loongarch64
+
+The default is x86_64, this is the most common architecture of PC processors
+today. All modern Intel and AMD processors as of writing this are x86_64.
+
+x86_32 will give you a 32bit executable that can run on 32bit only distributions
+of Linux as well as some modern distributions that are 64bit. It is NOT recommended
+to use this option unless you are trying to get your project to run on an old 32bit
+distribution and processor. It should also be noted that several prominent
+distributions, such as Fedora, have been discussing removing their 32bit libraries
+which would prevent executables made this way from running on future versions of
+that distribution.
+
+arm64 executables can run on 64bit ARM processors. If you're familiar with the
+Raspberry Pi, those have utilized 64bit ARM processors since the Pi 3 (older
+versions used 32bit ARM processors). If you're uploading to a platform that
+supports multiple executables, such as itch.io, and you're confident your game
+could run on a common ARM computer, such as the Pi 5, then we'd recommend exporting
+this version and providing it as an option.
+
+arm32 executables are for older 32bit arm processors, such as what the Raspberry Pi 1
+and 2 used. Given that they're not common at all these days we do not recommend
+exporting for this unless you have a computer with one of these processors you know
+you can, and want to have your game running on.
+
+rv64 is for RISC-V processors, ppc64 is for 64bit PowerPC processors, and
+loongarch64 is for 64bit LoongArch processors. All of these architectures are
+substantially more niche when it comes to running videogames on them. And we only
+recommend exporting for them if you have a reason to, such as if you're an
+enthusiast who owns hardware. Official export templates are not provided by Godot,
+you will have to create them on your own. Instructions for compiling the engine for
+RISC-V and creating export templates can be found on the :ref:`doc_compiling_for_linuxbsd`
+page.
+
+
 Environment variables
 ---------------------