Merge pull request #76476 from YuriSizov/4.0-cherrypicks

Cherry-picks for the 4.0 branch (future 4.0.3) - 3rd batch

12 files changed, 28 insertions, 14 deletions

diff --git a/doc/classes/AnimatableBody2D.xml b/doc/classes/AnimatableBody2D.xml
index fbc2fb8509..7b0d356b5a 100644
--- a/doc/classes/AnimatableBody2D.xml
+++ b/doc/classes/AnimatableBody2D.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AnimatableBody2D" inherits="StaticBody2D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Physics body for 2D physics which moves only by script or animation. Useful for moving platforms and doors.
+		Physics body for 2D physics which moves only by script or animation (while affecting other bodies on its path). Useful for moving platforms and doors.
 	</brief_description>
 	<description>
 		Animatable body for 2D physics.
diff --git a/doc/classes/AnimatableBody3D.xml b/doc/classes/AnimatableBody3D.xml
index 0733780bf7..617a4cc88f 100644
--- a/doc/classes/AnimatableBody3D.xml
+++ b/doc/classes/AnimatableBody3D.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AnimatableBody3D" inherits="StaticBody3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Physics body for 3D physics which moves only by script or animation. Useful for moving platforms and doors.
+		Physics body for 3D physics which moves only by script or animation (while affecting other bodies on its path). Useful for moving platforms and doors.
 	</brief_description>
 	<description>
 		Animatable body for 3D physics.
diff --git a/doc/classes/Engine.xml b/doc/classes/Engine.xml
index 461ffcb2e0..c41a853bb7 100644
--- a/doc/classes/Engine.xml
+++ b/doc/classes/Engine.xml
@@ -306,7 +306,7 @@
 			[b]Note:[/b] This property does not impact the editor's Errors tab when running a project from the editor.
 		</member>
 		<member name="time_scale" type="float" setter="set_time_scale" getter="get_time_scale" default="1.0">
-			Controls how fast or slow the in-game clock ticks versus the real life one. It defaults to 1.0. A value of 2.0 means the game moves twice as fast as real life, whilst a value of 0.5 means the game moves at half the regular speed.
+			Controls how fast or slow the in-game clock ticks versus the real life one. It defaults to 1.0. A value of 2.0 means the game moves twice as fast as real life, whilst a value of 0.5 means the game moves at half the regular speed. This also affects [Timer] and [SceneTreeTimer] (see [method SceneTree.create_timer] for how to control this).
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/Expression.xml b/doc/classes/Expression.xml
index 2451ab1a0d..2c0e6b49b2 100644
--- a/doc/classes/Expression.xml
+++ b/doc/classes/Expression.xml
@@ -49,6 +49,7 @@
 		[/codeblocks]
 	</description>
 	<tutorials>
+		<link title="Evaluating Expressions">$DOCS_URL/tutorials/scripting/evaluating_expressions.html</link>
 	</tutorials>
 	<methods>
 		<method name="execute">
diff --git a/doc/classes/Gradient.xml b/doc/classes/Gradient.xml
index 33f0a7979a..969169d8f5 100644
--- a/doc/classes/Gradient.xml
+++ b/doc/classes/Gradient.xml
@@ -49,13 +49,14 @@
 			<return type="void" />
 			<description>
 				Reverses/mirrors the gradient.
+				[b]Note:[/b] This method mirrors all points around the middle of the gradient, which may produce unexpected results when [member interpolation_mode] is set to [constant GRADIENT_INTERPOLATE_CONSTANT].
 			</description>
 		</method>
 		<method name="sample">
 			<return type="Color" />
 			<param index="0" name="offset" type="float" />
 			<description>
-				Returns the interpolated color specified by [code]offset[/code].
+				Returns the interpolated color specified by [param offset].
 			</description>
 		</method>
 		<method name="set_color">
diff --git a/doc/classes/ImmediateMesh.xml b/doc/classes/ImmediateMesh.xml
index a6d2e3e249..81fd62f85f 100644
--- a/doc/classes/ImmediateMesh.xml
+++ b/doc/classes/ImmediateMesh.xml
@@ -4,9 +4,20 @@
 		Mesh optimized for creating geometry manually.
 	</brief_description>
 	<description>
-		Mesh optimized for creating geometry manually, similar to OpenGL1.x immediate mode.
+		A mesh type optimized for creating geometry manually, similar to OpenGL 1.x immediate mode.
+		Here's a sample on how to generate a triangular face:
+		[codeblocks]
+		var mesh = ImmediateMesh.new()
+		mesh.surface_begin(Mesh.PRIMITIVE_TRIANGLES)
+		mesh.surface_add_vertex(Vector3.LEFT)
+		mesh.surface_add_vertex(Vector3.FORWARD)
+		mesh.surface_add_vertex(Vector3.ZERO)
+		mesh.surface_end()
+		[/codeblocks]
+		[b]Note:[/b] Generating complex geometries with [ImmediateMesh] is highly inefficient. Instead, it is designed to generate simple geometry that changes often.
 	</description>
 	<tutorials>
+		<link title="Using ImmediateMesh">$DOCS_URL/tutorials/3d/procedural_geometry/immediatemesh.html</link>
 	</tutorials>
 	<methods>
 		<method name="clear_surfaces">
diff --git a/doc/classes/Input.xml b/doc/classes/Input.xml
index 70e629974d..ab9ed47b85 100644
--- a/doc/classes/Input.xml
+++ b/doc/classes/Input.xml
@@ -300,7 +300,7 @@
 			<param index="2" name="hotspot" type="Vector2" default="Vector2(0, 0)" />
 			<description>
 				Sets a custom mouse cursor image, which is only visible inside the game window. The hotspot can also be specified. Passing [code]null[/code] to the image parameter resets to the system cursor. See [enum CursorShape] for the list of shapes.
-				[param image]'s size must be lower than 256×256.
+				[param image]'s size must be lower than or equal to 256×256. To avoid rendering issues, sizes lower than or equal to 128×128 are recommended.
 				[param hotspot] must be within [param image]'s size.
 				[b]Note:[/b] [AnimatedTexture]s aren't supported as custom mouse cursors. If using an [AnimatedTexture], only the first frame will be displayed.
 				[b]Note:[/b] Only images imported with the [b]Lossless[/b], [b]Lossy[/b] or [b]Uncompressed[/b] compression modes are supported. The [b]Video RAM[/b] compression mode can't be used for custom cursors.
diff --git a/doc/classes/RigidBody2D.xml b/doc/classes/RigidBody2D.xml
index 937d0910ec..17b5ce6c68 100644
--- a/doc/classes/RigidBody2D.xml
+++ b/doc/classes/RigidBody2D.xml
@@ -283,7 +283,7 @@
 			Kinematic body freeze mode. Similar to [constant FREEZE_MODE_STATIC], but collides with other bodies along its path when moved. Useful for a frozen body that needs to be animated.
 		</constant>
 		<constant name="CENTER_OF_MASS_MODE_AUTO" value="0" enum="CenterOfMassMode">
-			In this mode, the body's center of mass is calculated automatically based on its shapes.
+			In this mode, the body's center of mass is calculated automatically based on its shapes. This assumes that the shapes' origins are also their center of mass.
 		</constant>
 		<constant name="CENTER_OF_MASS_MODE_CUSTOM" value="1" enum="CenterOfMassMode">
 			In this mode, the body's center of mass is set through [member center_of_mass]. Defaults to the body's origin position.
diff --git a/doc/classes/RigidBody3D.xml b/doc/classes/RigidBody3D.xml
index a066254b4f..917ffe0b99 100644
--- a/doc/classes/RigidBody3D.xml
+++ b/doc/classes/RigidBody3D.xml
@@ -290,7 +290,7 @@
 			Kinematic body freeze mode. Similar to [constant FREEZE_MODE_STATIC], but collides with other bodies along its path when moved. Useful for a frozen body that needs to be animated.
 		</constant>
 		<constant name="CENTER_OF_MASS_MODE_AUTO" value="0" enum="CenterOfMassMode">
-			In this mode, the body's center of mass is calculated automatically based on its shapes.
+			In this mode, the body's center of mass is calculated automatically based on its shapes. This assumes that the shapes' origins are also their center of mass.
 		</constant>
 		<constant name="CENTER_OF_MASS_MODE_CUSTOM" value="1" enum="CenterOfMassMode">
 			In this mode, the body's center of mass is set through [member center_of_mass]. Defaults to the body's origin position.
diff --git a/doc/classes/StaticBody2D.xml b/doc/classes/StaticBody2D.xml
index 2393790e12..acb291b7e1 100644
--- a/doc/classes/StaticBody2D.xml
+++ b/doc/classes/StaticBody2D.xml
@@ -1,13 +1,13 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="StaticBody2D" inherits="PhysicsBody2D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Physics body for 2D physics which is static or moves only by script. Useful for floor and walls.
+		Physics body for 2D physics which is static or moves only by script (without affecting other bodies on its path). Useful for floors and walls.
 	</brief_description>
 	<description>
 		Static body for 2D physics.
 		A static body is a simple body that doesn't move under physics simulation, i.e. it can't be moved by external forces or contacts but its transformation can still be updated manually by the user. It is ideal for implementing objects in the environment, such as walls or platforms. In contrast to [RigidBody2D], it doesn't consume any CPU resources as long as they don't move.
 		They have extra functionalities to move and affect other bodies:
-		[b]Static transform change:[/b] Static bodies can be moved by animation or script. In this case, they are just teleported and don't affect other bodies on their path.
+		[b]Static transform change:[/b] Static bodies [i]can[/i] be moved by animation or script. In this case, they are just teleported and don't affect other bodies on their path. Use [AnimatableBody2D] instead of [StaticBody2D] if you need a moving static body that affects other bodies on its path.
 		[b]Constant velocity:[/b] When [member constant_linear_velocity] or [member constant_angular_velocity] is set, static bodies don't move themselves but affect touching bodies as if they were moving. This is useful for simulating conveyor belts or conveyor wheels.
 	</description>
 	<tutorials>
diff --git a/doc/classes/StaticBody3D.xml b/doc/classes/StaticBody3D.xml
index 7bebd46004..a0e3c3fae5 100644
--- a/doc/classes/StaticBody3D.xml
+++ b/doc/classes/StaticBody3D.xml
@@ -1,14 +1,14 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="StaticBody3D" inherits="PhysicsBody3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Physics body for 3D physics which is static or moves only by script. Useful for floor and walls.
+		Physics body for 3D physics which is static or moves only by script (without affecting other bodies on its path). Useful for floors and walls.
 	</brief_description>
 	<description>
 		Static body for 3D physics.
 		A static body is a simple body that doesn't move under physics simulation, i.e. it can't be moved by external forces or contacts but its transformation can still be updated manually by the user. It is ideal for implementing objects in the environment, such as walls or platforms. In contrast to [RigidBody3D], it doesn't consume any CPU resources as long as they don't move.
 		They have extra functionalities to move and affect other bodies:
-		[i]Static transform change:[/i] Static bodies can be moved by animation or script. In this case, they are just teleported and don't affect other bodies on their path.
-		[i]Constant velocity:[/i] When [member constant_linear_velocity] or [member constant_angular_velocity] is set, static bodies don't move themselves but affect touching bodies as if they were moving. This is useful for simulating conveyor belts or conveyor wheels.
+		[b]Static transform change:[/b] Static bodies [i]can[/i] be moved by animation or script. In this case, they are just teleported and don't affect other bodies on their path. Use [AnimatableBody3D] instead of [StaticBody3D] if you need a moving static body that affects other bodies on its path.
+		[b]Constant velocity:[/b] When [member constant_linear_velocity] or [member constant_angular_velocity] is set, static bodies don't move themselves but affect touching bodies as if they were moving. This is useful for simulating conveyor belts or conveyor wheels.
 		[b]Warning:[/b] With a non-uniform scale this node will probably not function as expected. Please make sure to keep its scale uniform (i.e. the same on all axes), and change the size(s) of its collision shape(s) instead.
 	</description>
 	<tutorials>
diff --git a/doc/classes/Timer.xml b/doc/classes/Timer.xml
index 1b6c05284e..f4f4efd42e 100644
--- a/doc/classes/Timer.xml
+++ b/doc/classes/Timer.xml
@@ -5,6 +5,7 @@
 	</brief_description>
 	<description>
 		Counts down a specified interval and emits a signal on reaching 0. Can be set to repeat or "one-shot" mode.
+		[b]Note:[/b] Timers are affected by [member Engine.time_scale], a higher scale means quicker timeouts, and vice versa.
 		[b]Note:[/b] To create a one-shot timer without instantiating a node, use [method SceneTree.create_timer].
 	</description>
 	<tutorials>
@@ -52,7 +53,7 @@
 		</member>
 		<member name="wait_time" type="float" setter="set_wait_time" getter="get_wait_time" default="1.0">
 			The wait time in seconds.
-			[b]Note:[/b] Timers can only emit once per rendered frame at most (or once per physics frame if [member process_callback] is [constant TIMER_PROCESS_PHYSICS]). This means very low wait times (lower than 0.05 seconds) will behave in significantly different ways depending on the rendered framerate. For very low wait times, it is recommended to use a process loop in a script instead of using a Timer node.
+			[b]Note:[/b] Timers can only emit once per rendered frame at most (or once per physics frame if [member process_callback] is [constant TIMER_PROCESS_PHYSICS]). This means very low wait times (lower than 0.05 seconds) will behave in significantly different ways depending on the rendered framerate. For very low wait times, it is recommended to use a process loop in a script instead of using a Timer node. Timers are affected by [member Engine.time_scale], a higher scale means quicker timeouts, and vice versa.
 		</member>
 	</members>
 	<signals>