Merge pull request #65931 from fabriceci/add-recovery-as-collision-in-low-level-methods

Add recovery_as_collision in move_and_collide/test_move

4 files changed, 14 insertions, 6 deletions

diff --git a/doc/classes/PhysicsBody2D.xml b/doc/classes/PhysicsBody2D.xml
index e8d7ac9920..59660b4de5 100644
--- a/doc/classes/PhysicsBody2D.xml
+++ b/doc/classes/PhysicsBody2D.xml
@@ -28,11 +28,13 @@
 			<param index="0" name="distance" type="Vector2" />
 			<param index="1" name="test_only" type="bool" default="false" />
 			<param index="2" name="safe_margin" type="float" default="0.08" />
+			<param index="3" name="recovery_as_collision" type="bool" default="false" />
 			<description>
 				Moves the body along the vector [param distance]. In order to be frame rate independent in [method Node._physics_process] or [method Node._process], [param distance] should be computed using [code]delta[/code].
 				Returns a [KinematicCollision2D], which contains information about the collision when stopped, or when touching another body along the motion.
 				If [param test_only] is [code]true[/code], the body does not move but the would-be collision information is given.
 				[param safe_margin] is the extra margin used for collision recovery (see [member CharacterBody2D.safe_margin] for more details).
+				If [param recovery_as_collision] is [code]true[/code], any depenetration from the recovery phase is also reported as a collision; this is used e.g. by [CharacterBody2D] for improving floor detection during floor snapping.
 			</description>
 		</method>
 		<method name="remove_collision_exception_with">
@@ -48,11 +50,13 @@
 			<param index="1" name="distance" type="Vector2" />
 			<param index="2" name="collision" type="KinematicCollision2D" default="null" />
 			<param index="3" name="safe_margin" type="float" default="0.08" />
+			<param index="4" name="recovery_as_collision" type="bool" default="false" />
 			<description>
 				Checks for collisions without moving the body. In order to be frame rate independent in [method Node._physics_process] or [method Node._process], [param distance] should be computed using [code]delta[/code].
 				Virtually sets the node's position, scale and rotation to that of the given [Transform2D], then tries to move the body along the vector [param distance]. Returns [code]true[/code] if a collision would stop the body from moving along the whole path.
 				[param collision] is an optional object of type [KinematicCollision2D], which contains additional information about the collision when stopped, or when touching another body along the motion.
 				[param safe_margin] is the extra margin used for collision recovery (see [member CharacterBody2D.safe_margin] for more details).
+				If [param recovery_as_collision] is [code]true[/code], any depenetration from the recovery phase is also reported as a collision; this is useful for checking whether the body would [i]touch[/i] any other bodies.
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/PhysicsBody3D.xml b/doc/classes/PhysicsBody3D.xml
index 310671274f..bf7882a1ea 100644
--- a/doc/classes/PhysicsBody3D.xml
+++ b/doc/classes/PhysicsBody3D.xml
@@ -35,12 +35,14 @@
 			<param index="0" name="distance" type="Vector3" />
 			<param index="1" name="test_only" type="bool" default="false" />
 			<param index="2" name="safe_margin" type="float" default="0.001" />
-			<param index="3" name="max_collisions" type="int" default="1" />
+			<param index="3" name="recovery_as_collision" type="bool" default="false" />
+			<param index="4" name="max_collisions" type="int" default="1" />
 			<description>
 				Moves the body along the vector [param distance]. In order to be frame rate independent in [method Node._physics_process] or [method Node._process], [param distance] should be computed using [code]delta[/code].
 				The body will stop if it collides. Returns a [KinematicCollision3D], which contains information about the collision when stopped, or when touching another body along the motion.
 				If [param test_only] is [code]true[/code], the body does not move but the would-be collision information is given.
 				[param safe_margin] is the extra margin used for collision recovery (see [member CharacterBody3D.safe_margin] for more details).
+				If [param recovery_as_collision] is [code]true[/code], any depenetration from the recovery phase is also reported as a collision; this is used e.g. by [CharacterBody3D] for improving floor detection during floor snapping.
 				[param max_collisions] allows to retrieve more than one collision result.
 			</description>
 		</method>
@@ -65,12 +67,14 @@
 			<param index="1" name="distance" type="Vector3" />
 			<param index="2" name="collision" type="KinematicCollision3D" default="null" />
 			<param index="3" name="safe_margin" type="float" default="0.001" />
-			<param index="4" name="max_collisions" type="int" default="1" />
+			<param index="4" name="recovery_as_collision" type="bool" default="false" />
+			<param index="5" name="max_collisions" type="int" default="1" />
 			<description>
 				Checks for collisions without moving the body. In order to be frame rate independent in [method Node._physics_process] or [method Node._process], [param distance] should be computed using [code]delta[/code].
 				Virtually sets the node's position, scale and rotation to that of the given [Transform3D], then tries to move the body along the vector [param distance]. Returns [code]true[/code] if a collision would stop the body from moving along the whole path.
 				[param collision] is an optional object of type [KinematicCollision3D], which contains additional information about the collision when stopped, or when touching another body along the motion.
 				[param safe_margin] is the extra margin used for collision recovery (see [member CharacterBody3D.safe_margin] for more details).
+				If [param recovery_as_collision] is [code]true[/code], any depenetration from the recovery phase is also reported as a collision; this is useful for checking whether the body would [i]touch[/i] any other bodies.
 				[param max_collisions] allows to retrieve more than one collision result.
 			</description>
 		</method>
diff --git a/doc/classes/PhysicsTestMotionParameters2D.xml b/doc/classes/PhysicsTestMotionParameters2D.xml
index 4f2b62f2d9..d8f96511dd 100644
--- a/doc/classes/PhysicsTestMotionParameters2D.xml
+++ b/doc/classes/PhysicsTestMotionParameters2D.xml
@@ -29,8 +29,8 @@
 			Motion vector to define the length and direction of the motion to test.
 		</member>
 		<member name="recovery_as_collision" type="bool" setter="set_recovery_as_collision_enabled" getter="is_recovery_as_collision_enabled" default="false">
-			If set to [code]true[/code], any depenetration from the recovery phase is reported as a collision; this is used e.g. by [method CharacterBody2D.move_and_slide] for improving floor detection when floor snapping is disabled.
-			If set to [code]false[/code], only collisions resulting from the motion are reported; this is used e.g. by [method PhysicsBody2D.move_and_collide].
+			If set to [code]true[/code], any depenetration from the recovery phase is reported as a collision; this is used e.g. by [CharacterBody2D] for improving floor detection during floor snapping.
+			If set to [code]false[/code], only collisions resulting from the motion are reported, which is generally the desired behaviour.
 		</member>
 	</members>
 </class>
diff --git a/doc/classes/PhysicsTestMotionParameters3D.xml b/doc/classes/PhysicsTestMotionParameters3D.xml
index 5b07796a10..e8f80ae131 100644
--- a/doc/classes/PhysicsTestMotionParameters3D.xml
+++ b/doc/classes/PhysicsTestMotionParameters3D.xml
@@ -32,8 +32,8 @@
 			Motion vector to define the length and direction of the motion to test.
 		</member>
 		<member name="recovery_as_collision" type="bool" setter="set_recovery_as_collision_enabled" getter="is_recovery_as_collision_enabled" default="false">
-			If set to [code]true[/code], any depenetration from the recovery phase is reported as a collision; this is used e.g. by [method CharacterBody3D.move_and_slide] for improving floor detection when floor snapping is disabled.
-			If set to [code]false[/code], only collisions resulting from the motion are detected; this is used e.g. by [method PhysicsBody3D.move_and_collide].
+			If set to [code]true[/code], any depenetration from the recovery phase is reported as a collision; this is used e.g. by [CharacterBody3D] for improving floor detection during floor snapping.
+			If set to [code]false[/code], only collisions resulting from the motion are reported, which is generally the desired behaviour.
 		</member>
 	</members>
 </class>