[pull] master from godotengine:master

.github/workflows/static_checks.yml

@@ -56,7 +56,7 @@ jobs:
 
       - name: Class reference schema checks
         run: |
-          xmllint --noout --schema doc/class.xsd doc/classes/*.xml modules/*/doc_classes/*.xml platform/*/doc_classes/*.xml
+          xmllint --quiet --noout --schema doc/class.xsd doc/classes/*.xml modules/*/doc_classes/*.xml platform/*/doc_classes/*.xml
 
       - name: Run C compiler on `gdextension_interface.h`
         run: |

core/config/project_settings.cpp

@@ -1563,6 +1563,7 @@ ProjectSettings::ProjectSettings() {
 	GLOBAL_DEF(PropertyInfo(Variant::INT, "rendering/rendering_device/staging_buffer/block_size_kb", PROPERTY_HINT_RANGE, "4,2048,1,or_greater"), 256);
 	GLOBAL_DEF(PropertyInfo(Variant::INT, "rendering/rendering_device/staging_buffer/max_size_mb", PROPERTY_HINT_RANGE, "1,1024,1,or_greater"), 128);
 	GLOBAL_DEF(PropertyInfo(Variant::INT, "rendering/rendering_device/staging_buffer/texture_upload_region_size_px", PROPERTY_HINT_RANGE, "1,256,1,or_greater"), 64);
+	GLOBAL_DEF(PropertyInfo(Variant::INT, "rendering/rendering_device/staging_buffer/texture_download_region_size_px", PROPERTY_HINT_RANGE, "1,256,1,or_greater"), 64);
 	GLOBAL_DEF_RST(PropertyInfo(Variant::BOOL, "rendering/rendering_device/pipeline_cache/enable"), true);
 	GLOBAL_DEF(PropertyInfo(Variant::FLOAT, "rendering/rendering_device/pipeline_cache/save_chunk_size_mb", PROPERTY_HINT_RANGE, "0.000001,64.0,0.001,or_greater"), 3.0);
 	GLOBAL_DEF(PropertyInfo(Variant::INT, "rendering/rendering_device/vulkan/max_descriptors_per_pool", PROPERTY_HINT_RANGE, "1,256,1,or_greater"), 64);

doc/classes/AABB.xml

@@ -46,8 +46,8 @@
 				[gdscript]
 				var box = AABB(Vector3(5, 0, 5), Vector3(-20, -10, -5))
 				var absolute = box.abs()
-				print(absolute.position) # Prints (-15, -10, 0)
-				print(absolute.size)     # Prints (20, 10, 5)
+				print(absolute.position) # Prints (-15.0, -10.0, 0.0)
+				print(absolute.size)     # Prints (20.0, 10.0, 5.0)
 				[/gdscript]
 				[csharp]
 				var box = new Aabb(new Vector3(5, 0, 5), new Vector3(-20, -10, -5));
@@ -96,12 +96,12 @@
 				var box = AABB(Vector3(0, 0, 0), Vector3(5, 2, 5))
 
 				box = box.expand(Vector3(10, 0, 0))
-				print(box.position) # Prints (0, 0, 0)
-				print(box.size)     # Prints (10, 2, 5)
+				print(box.position) # Prints (0.0, 0.0, 0.0)
+				print(box.size)     # Prints (10.0, 2.0, 5.0)
 
 				box = box.expand(Vector3(-5, 0, 5))
-				print(box.position) # Prints (-5, 0, 0)
-				print(box.size)     # Prints (15, 2, 5)
+				print(box.position) # Prints (-5.0, 0.0, 0.0)
+				print(box.size)     # Prints (15.0, 2.0, 5.0)
 				[/gdscript]
 				[csharp]
 				var box = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 5));
@@ -138,15 +138,15 @@
 				[gdscript]
 				var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))
 
-				print(box.get_longest_axis())       # Prints (0, 0, 1)
+				print(box.get_longest_axis())       # Prints (0.0, 0.0, 1.0)
 				print(box.get_longest_axis_index()) # Prints 2
-				print(box.get_longest_axis_size())  # Prints 8
+				print(box.get_longest_axis_size())  # Prints 8.0
 				[/gdscript]
 				[csharp]
 				var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8));
 
 				GD.Print(box.GetLongestAxis());      // Prints (0, 0, 1)
-				GD.Print(box.GetLongestAxisIndex()); // Prints 2
+				GD.Print(box.GetLongestAxisIndex()); // Prints Z
 				GD.Print(box.GetLongestAxisSize());  // Prints 8
 				[/csharp]
 				[/codeblocks]
@@ -175,15 +175,15 @@
 				[gdscript]
 				var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))
 
-				print(box.get_shortest_axis())       # Prints (1, 0, 0)
+				print(box.get_shortest_axis())       # Prints (1.0, 0.0, 0.0)
 				print(box.get_shortest_axis_index()) # Prints 0
-				print(box.get_shortest_axis_size())  # Prints 2
+				print(box.get_shortest_axis_size())  # Prints 2.0
 				[/gdscript]
 				[csharp]
 				var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8));
 
 				GD.Print(box.GetShortestAxis());      // Prints (1, 0, 0)
-				GD.Print(box.GetShortestAxisIndex()); // Prints 0
+				GD.Print(box.GetShortestAxisIndex()); // Prints X
 				GD.Print(box.GetShortestAxisSize());  // Prints 2
 				[/csharp]
 				[/codeblocks]
@@ -225,12 +225,12 @@
 				[codeblocks]
 				[gdscript]
 				var a = AABB(Vector3(4, 4, 4), Vector3(8, 8, 8)).grow(4)
-				print(a.position) # Prints (0, 0, 0)
-				print(a.size)     # Prints (16, 16, 16)
+				print(a.position) # Prints (0.0, 0.0, 0.0)
+				print(a.size)     # Prints (16.0, 16.0, 16.0)
 
 				var b = AABB(Vector3(0, 0, 0), Vector3(8, 4, 2)).grow(2)
-				print(b.position) # Prints (-2, -2, -2)
-				print(b.size)     # Prints (12, 8, 6)
+				print(b.position) # Prints (-2.0, -2.0, -2.0)
+				print(b.size)     # Prints (12.0, 8.0, 6.0)
 				[/gdscript]
 				[csharp]
 				var a = new Aabb(new Vector3(4, 4, 4), new Vector3(8, 8, 8)).Grow(4);
@@ -275,8 +275,8 @@
 				var box2 = AABB(Vector3(2, 0, 2), Vector3(8, 4, 4))
 
 				var intersection = box1.intersection(box2)
-				print(intersection.position) # Prints (2, 0, 2)
-				print(intersection.size)     # Prints (3, 2, 4)
+				print(intersection.position) # Prints (2.0, 0.0, 2.0)
+				print(intersection.size)     # Prints (3.0, 2.0, 4.0)
 				[/gdscript]
 				[csharp]
 				var box1 = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 8));

doc/classes/AStarGrid2D.xml

@@ -12,8 +12,8 @@
 		astar_grid.region = Rect2i(0, 0, 32, 32)
 		astar_grid.cell_size = Vector2(16, 16)
 		astar_grid.update()
-		print(astar_grid.get_id_path(Vector2i(0, 0), Vector2i(3, 4))) # prints (0, 0), (1, 1), (2, 2), (3, 3), (3, 4)
-		print(astar_grid.get_point_path(Vector2i(0, 0), Vector2i(3, 4))) # prints (0, 0), (16, 16), (32, 32), (48, 48), (48, 64)
+		print(astar_grid.get_id_path(Vector2i(0, 0), Vector2i(3, 4))) # Prints [(0, 0), (1, 1), (2, 2), (3, 3), (3, 4)]
+		print(astar_grid.get_point_path(Vector2i(0, 0), Vector2i(3, 4))) # Prints [(0, 0), (16, 16), (32, 32), (48, 48), (48, 64)]
 		[/gdscript]
 		[csharp]
 		AStarGrid2D astarGrid = new AStarGrid2D();

doc/classes/Array.xml

@@ -183,17 +183,17 @@
 
 				public override void _Ready()
 				{
-				    // Prints true (3/3 elements evaluate to true).
+				    // Prints True (3/3 elements evaluate to true).
 				    GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(GreaterThan5));
-				    // Prints false (1/3 elements evaluate to true).
+				    // Prints False (1/3 elements evaluate to true).
 				    GD.Print(new Godot.Collections.Array>int< { 4, 10, 4 }.All(GreaterThan5));
-				    // Prints false (0/3 elements evaluate to true).
+				    // Prints False (0/3 elements evaluate to true).
 				    GD.Print(new Godot.Collections.Array>int< { 4, 4, 4 }.All(GreaterThan5));
-				    // Prints true (0/0 elements evaluate to true).
+				    // Prints True (0/0 elements evaluate to true).
 				    GD.Print(new Godot.Collections.Array>int< { }.All(GreaterThan5));
 
 				    // Same as the first line above, but using a lambda function.
-				    GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(element => element > 5)); // Prints true
+				    GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(element => element > 5)); // Prints True
 				}
 				[/csharp]
 				[/codeblocks]
@@ -462,10 +462,10 @@
 				[csharp]
 				var arr = new Godot.Collections.Array { "inside", 7 };
 				// By C# convention, this method is renamed to `Contains`.
-				GD.Print(arr.Contains("inside"));  // Prints true
-				GD.Print(arr.Contains("outside")); // Prints false
-				GD.Print(arr.Contains(7));         // Prints true
-				GD.Print(arr.Contains("7"));       // Prints false
+				GD.Print(arr.Contains("inside"));  // Prints True
+				GD.Print(arr.Contains("outside")); // Prints False
+				GD.Print(arr.Contains(7));         // Prints True
+				GD.Print(arr.Contains("7"));       // Prints False
 				[/csharp]
 				[/codeblocks]
 				In GDScript, this is equivalent to the [code]in[/code] operator:

doc/classes/AudioStream.xml

@@ -13,6 +13,12 @@
 		<link title="Audio Spectrum Visualizer Demo">https://godotengine.org/asset-library/asset/2762</link>
 	</tutorials>
 	<methods>
+		<method name="_get_bar_beats" qualifiers="virtual const">
+			<return type="int" />
+			<description>
+				Override this method to return the bar beats of this stream.
+			</description>
+		</method>
 		<method name="_get_beat_count" qualifiers="virtual const">
 			<return type="int" />
 			<description>
@@ -45,6 +51,12 @@
 				Override this method to customize the name assigned to this audio stream. Unused by the engine.
 			</description>
 		</method>
+		<method name="_has_loop" qualifiers="virtual const">
+			<return type="bool" />
+			<description>
+				Override this method to return [code]true[/code] if this stream has a loop.
+			</description>
+		</method>
 		<method name="_instantiate_playback" qualifiers="virtual const">
 			<return type="AudioStreamPlayback" />
 			<description>

doc/classes/Basis.xml

@@ -91,7 +91,7 @@
 				# Creates a Basis whose z axis points down.
 				var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0))
 
-				print(my_basis.z) # Prints (0, -1, 0)
+				print(my_basis.z) # Prints (0.0, -1.0, 0.0)
 				[/gdscript]
 				[csharp]
 				// Creates a Basis whose z axis points down.
@@ -112,9 +112,9 @@
 				[gdscript]
 				var my_basis = Basis.from_scale(Vector3(2, 4, 8))
 
-				print(my_basis.x) # Prints (2, 0, 0)
-				print(my_basis.y) # Prints (0, 4, 0)
-				print(my_basis.z) # Prints (0, 0, 8)
+				print(my_basis.x) # Prints (2.0, 0.0, 0.0)
+				print(my_basis.y) # Prints (0.0, 4.0, 0.0)
+				print(my_basis.z) # Prints (0.0, 0.0, 8.0)
 				[/gdscript]
 				[csharp]
 				var myBasis = Basis.FromScale(new Vector3(2.0f, 4.0f, 8.0f));
@@ -163,7 +163,7 @@
 				my_basis = my_basis.rotated(Vector3.UP, TAU / 2)
 				my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4)
 
-				print(my_basis.get_scale()) # Prints (2, 4, 8)
+				print(my_basis.get_scale()) # Prints (2.0, 4.0, 8.0)
 				[/gdscript]
 				[csharp]
 				var myBasis = new Basis(
@@ -285,9 +285,9 @@
 				)
 				my_basis = my_basis.scaled(Vector3(0, 2, -2))
 
-				print(my_basis.x) # Prints (0, 2, -2)
-				print(my_basis.y) # Prints (0, 4, -4)
-				print(my_basis.z) # Prints (0, 6, -6)
+				print(my_basis.x) # Prints (0.0, 2.0, -2.0)
+				print(my_basis.y) # Prints (0.0, 4.0, -4.0)
+				print(my_basis.z) # Prints (0.0, 6.0, -6.0)
 				[/gdscript]
 				[csharp]
 				var myBasis = new Basis(
@@ -360,9 +360,9 @@
 				)
 				my_basis = my_basis.transposed()
 
-				print(my_basis.x) # Prints (1, 4, 7)
-				print(my_basis.y) # Prints (2, 5, 8)
-				print(my_basis.z) # Prints (3, 6, 9)
+				print(my_basis.x) # Prints (1.0, 4.0, 7.0)
+				print(my_basis.y) # Prints (2.0, 5.0, 8.0)
+				print(my_basis.z) # Prints (3.0, 6.0, 9.0)
 				[/gdscript]
 				[csharp]
 				var myBasis = new Basis(
@@ -454,7 +454,7 @@
 				[gdscript]
 				# Basis that swaps the X/Z axes and doubles the scale.
 				var my_basis = Basis(Vector3(0, 2, 0), Vector3(2, 0, 0), Vector3(0, 0, 2))
-				print(my_basis * Vector3(1, 2, 3)) # Prints (4, 2, 6)
+				print(my_basis * Vector3(1, 2, 3)) # Prints (4.0, 2.0, 6.0)
 				[/gdscript]
 				[csharp]
 				// Basis that swaps the X/Z axes and doubles the scale.

doc/classes/Button.xml

@@ -47,7 +47,7 @@
 			If set to something other than [constant TextServer.AUTOWRAP_OFF], the text gets wrapped inside the node's bounding rectangle.
 		</member>
 		<member name="clip_text" type="bool" setter="set_clip_text" getter="get_clip_text" default="false">
-			When this property is enabled, text that is too large to fit the button is clipped, when disabled the Button will always be wide enough to hold the text.
+			If [code]true[/code], text that is too large to fit the button is clipped horizontally. If [code]false[/code], the button will always be wide enough to hold the text. The text is not vertically clipped, and the button's height is not affected by this property.
 		</member>
 		<member name="expand_icon" type="bool" setter="set_expand_icon" getter="is_expand_icon" default="false">
 			When enabled, the button's icon will expand/shrink to fit the button's size while keeping its aspect. See also [theme_item icon_max_width].

doc/classes/Callable.xml

@@ -13,7 +13,7 @@
 		func test():
 		    var callable = Callable(self, "print_args")
 		    callable.call("hello", "world")  # Prints "hello world ".
-		    callable.call(Vector2.UP, 42, callable)  # Prints "(0, -1) 42 Node(node.gd)::print_args".
+		    callable.call(Vector2.UP, 42, callable)  # Prints "(0.0, -1.0) 42 Node(node.gd)::print_args".
 		    callable.call("invalid")  # Invalid call, should have at least 2 arguments.
 		[/gdscript]
 		[csharp]

doc/classes/Dictionary.xml

@@ -281,9 +281,9 @@
 				    { 210, default },
 				};
 
-				GD.Print(myDict.ContainsKey("Godot")); // Prints true
-				GD.Print(myDict.ContainsKey(210));     // Prints true
-				GD.Print(myDict.ContainsKey(4));       // Prints false
+				GD.Print(myDict.ContainsKey("Godot")); // Prints True
+				GD.Print(myDict.ContainsKey(210));     // Prints True
+				GD.Print(myDict.ContainsKey(4));       // Prints False
 				[/csharp]
 				[/codeblocks]
 				In GDScript, this is equivalent to the [code]in[/code] operator:
@@ -321,7 +321,7 @@
 				var dict2 = new Godot.Collections.Dictionary{{"A", 10}, {"B", 2}};
 
 				// Godot.Collections.Dictionary has no Hash() method. Use GD.Hash() instead.
-				GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Prints true
+				GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Prints True
 				[/csharp]
 				[/codeblocks]
 				[b]Note:[/b] Dictionaries with the same entries but in a different order will not have the same hash.

doc/classes/Engine.xml

@@ -209,10 +209,10 @@
 				print(Engine.has_singleton("Unknown"))     # Prints false
 				[/gdscript]
 				[csharp]
-				GD.Print(Engine.HasSingleton("OS"));          // Prints true
-				GD.Print(Engine.HasSingleton("Engine"));      // Prints true
-				GD.Print(Engine.HasSingleton("AudioServer")); // Prints true
-				GD.Print(Engine.HasSingleton("Unknown"));     // Prints false
+				GD.Print(Engine.HasSingleton("OS"));          // Prints True
+				GD.Print(Engine.HasSingleton("Engine"));      // Prints True
+				GD.Print(Engine.HasSingleton("AudioServer")); // Prints True
+				GD.Print(Engine.HasSingleton("Unknown"));     // Prints False
 				[/csharp]
 				[/codeblocks]
 				[b]Note:[/b] Global singletons are not the same as autoloaded nodes, which are configurable in the project settings.

doc/classes/Geometry2D.xml

@@ -201,13 +201,13 @@
 				var polygon = PackedVector2Array([Vector2(0, 0), Vector2(100, 0), Vector2(100, 100), Vector2(0, 100)])
 				var offset = Vector2(50, 50)
 				polygon = Transform2D(0, offset) * polygon
-				print(polygon) # prints [(50, 50), (150, 50), (150, 150), (50, 150)]
+				print(polygon) # Prints [(50.0, 50.0), (150.0, 50.0), (150.0, 150.0), (50.0, 150.0)]
 				[/gdscript]
 				[csharp]
 				var polygon = new Vector2[] { new Vector2(0, 0), new Vector2(100, 0), new Vector2(100, 100), new Vector2(0, 100) };
 				var offset = new Vector2(50, 50);
 				polygon = new Transform2D(0, offset) * polygon;
-				GD.Print((Variant)polygon); // prints [(50, 50), (150, 50), (150, 150), (50, 150)]
+				GD.Print((Variant)polygon); // Prints [(50, 50), (150, 50), (150, 150), (50, 150)]
 				[/csharp]
 				[/codeblocks]
 			</description>

doc/classes/MainLoop.xml

@@ -78,6 +78,7 @@
 			<description>
 				Called each physics frame with the time since the last physics frame as argument ([param delta], in seconds). Equivalent to [method Node._physics_process].
 				If implemented, the method must return a boolean value. [code]true[/code] ends the main loop, while [code]false[/code] lets it proceed to the next frame.
+				[b]Note:[/b] [param delta] will be larger than expected if running at a framerate lower than [member Engine.physics_ticks_per_second] / [member Engine.max_physics_steps_per_frame] FPS. This is done to avoid "spiral of death" scenarios where performance would plummet due to an ever-increasing number of physics steps per frame. This behavior affects both [method _process] and [method _physics_process]. As a result, avoid using [param delta] for time measurements in real-world seconds. Use the [Time] singleton's methods for this purpose instead, such as [method Time.get_ticks_usec].
 			</description>
 		</method>
 		<method name="_process" qualifiers="virtual">
@@ -86,6 +87,7 @@
 			<description>
 				Called each process (idle) frame with the time since the last process frame as argument (in seconds). Equivalent to [method Node._process].
 				If implemented, the method must return a boolean value. [code]true[/code] ends the main loop, while [code]false[/code] lets it proceed to the next frame.
+				[b]Note:[/b] [param delta] will be larger than expected if running at a framerate lower than [member Engine.physics_ticks_per_second] / [member Engine.max_physics_steps_per_frame] FPS. This is done to avoid "spiral of death" scenarios where performance would plummet due to an ever-increasing number of physics steps per frame. This behavior affects both [method _process] and [method _physics_process]. As a result, avoid using [param delta] for time measurements in real-world seconds. Use the [Time] singleton's methods for this purpose instead, such as [method Time.get_ticks_usec].
 			</description>
 		</method>
 	</methods>

doc/classes/NavigationPathQueryParameters2D.xml

@@ -49,6 +49,9 @@
 		<constant name="PATH_POSTPROCESSING_EDGECENTERED" value="1" enum="PathPostProcessing">
 			Centers every path position in the middle of the traveled navigation mesh polygon edge. This creates better paths for tile- or gridbased layouts that restrict the movement to the cells center.
 		</constant>
+		<constant name="PATH_POSTPROCESSING_NONE" value="2" enum="PathPostProcessing">
+			Applies no postprocessing and returns the raw path corridor as found by the pathfinding algorithm.
+		</constant>
 		<constant name="PATH_METADATA_INCLUDE_NONE" value="0" enum="PathMetadataFlags" is_bitfield="true">
 			Don't include any additional metadata about the returned path.
 		</constant>

doc/classes/NavigationPathQueryParameters3D.xml

@@ -49,6 +49,9 @@
 		<constant name="PATH_POSTPROCESSING_EDGECENTERED" value="1" enum="PathPostProcessing">
 			Centers every path position in the middle of the traveled navigation mesh polygon edge. This creates better paths for tile- or gridbased layouts that restrict the movement to the cells center.
 		</constant>
+		<constant name="PATH_POSTPROCESSING_NONE" value="2" enum="PathPostProcessing">
+			Applies no postprocessing and returns the raw path corridor as found by the pathfinding algorithm.
+		</constant>
 		<constant name="PATH_METADATA_INCLUDE_NONE" value="0" enum="PathMetadataFlags" is_bitfield="true">
 			Don't include any additional metadata about the returned path.
 		</constant>

doc/classes/NavigationServer2D.xml

@@ -533,7 +533,7 @@
 				Returns all navigation obstacle [RID]s that are currently assigned to the requested navigation [param map].
 			</description>
 		</method>
-		<method name="map_get_path" qualifiers="const">
+		<method name="map_get_path">
 			<return type="PackedVector2Array" />
 			<param index="0" name="map" type="RID" />
 			<param index="1" name="origin" type="Vector2" />
@@ -754,12 +754,13 @@
 				[b]Performance:[/b] While convenient, reading data arrays from [Mesh] resources can affect the frame rate negatively. The data needs to be received from the GPU, stalling the [RenderingServer] in the process. For performance prefer the use of e.g. collision shapes or creating the data arrays entirely in code.
 			</description>
 		</method>
-		<method name="query_path" qualifiers="const">
+		<method name="query_path">
 			<return type="void" />
 			<param index="0" name="parameters" type="NavigationPathQueryParameters2D" />
 			<param index="1" name="result" type="NavigationPathQueryResult2D" />
+			<param index="2" name="callback" type="Callable" default="Callable()" />
 			<description>
-				Queries a path in a given navigation map. Start and target position and other parameters are defined through [NavigationPathQueryParameters2D]. Updates the provided [NavigationPathQueryResult2D] result object with the path among other results requested by the query.
+				Queries a path in a given navigation map. Start and target position and other parameters are defined through [NavigationPathQueryParameters2D]. Updates the provided [NavigationPathQueryResult2D] result object with the path among other results requested by the query. After the process is finished the optional [param callback] will be called.
 			</description>
 		</method>
 		<method name="region_create">