Merge pull request #52889 from fabriceci/multiple_collision-support-fab

Port 2D improvements to move and slide 3D (with extras)

6 files changed, 223 insertions, 27 deletions

diff --git a/doc/classes/CharacterBody2D.xml b/doc/classes/CharacterBody2D.xml
index 7637356f63..882aa8bd71 100644
--- a/doc/classes/CharacterBody2D.xml
+++ b/doc/classes/CharacterBody2D.xml
@@ -170,7 +170,7 @@
 			Apply when notions of walls, ceiling and floor are relevant. In this mode the body motion will react to slopes (acceleration/slowdown). This mode is suitable for sided games like platformers.
 		</constant>
 		<constant name="MOTION_MODE_FREE" value="1" enum="MotionMode">
-			Apply when there is no notion of floor or ceiling. All collisions will be reported as [code]on_wall[/code]. In this mode, when you slide, the speed will be always constant. This mode is suitable for top-down games.
+			Apply when there is no notion of floor or ceiling. All collisions will be reported as [code]on_wall[/code]. In this mode, when you slide, the speed will always be constant. This mode is suitable for top-down games.
 		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/CharacterBody3D.xml b/doc/classes/CharacterBody3D.xml
index fab845fea4..f13796bfe7 100644
--- a/doc/classes/CharacterBody3D.xml
+++ b/doc/classes/CharacterBody3D.xml
@@ -29,6 +29,12 @@
 				Returns the surface normal of the floor at the last collision point. Only valid after calling [method move_and_slide] and when [method is_on_floor] returns [code]true[/code].
 			</description>
 		</method>
+		<method name="get_last_motion" qualifiers="const">
+			<return type="Vector3" />
+			<description>
+				Returns the last motion applied to the [CharacterBody3D] during the last call to [method move_and_slide]. The movement can be split if needed into multiple motion, this method return the last one, it's useful to retrieve the current direction of the movement.
+			</description>
+		</method>
 		<method name="get_last_slide_collision">
 			<return type="KinematicCollision3D" />
 			<description>
@@ -41,6 +47,18 @@
 				Returns the linear velocity of the floor at the last collision point. Only valid after calling [method move_and_slide] and when [method is_on_floor] returns [code]true[/code].
 			</description>
 		</method>
+		<method name="get_position_delta" qualifiers="const">
+			<return type="Vector3" />
+			<description>
+				Returns the travel (position delta) that occurred during the last call to [method move_and_slide].
+			</description>
+		</method>
+		<method name="get_real_velocity" qualifiers="const">
+			<return type="Vector3" />
+			<description>
+				Returns the current real velocity since the last call to [method move_and_slide]. For example, when you climb a slope, you will move diagonally even though the velocity is horizontal. This method returns the diagonal movement, as opposed to [member linear_velocity] which returns the requested velocity.
+			</description>
+		</method>
 		<method name="get_slide_collision">
 			<return type="KinematicCollision3D" />
 			<argument index="0" name="slide_idx" type="int" />
@@ -54,6 +72,12 @@
 				Returns the number of times the body collided and changed direction during the last call to [method move_and_slide].
 			</description>
 		</method>
+		<method name="get_wall_normal" qualifiers="const">
+			<return type="Vector3" />
+			<description>
+				Returns the surface normal of the wall at the last collision point. Only valid after calling [method move_and_slide] and when [method is_on_wall] returns [code]true[/code].
+			</description>
+		</method>
 		<method name="is_on_ceiling" qualifiers="const">
 			<return type="bool" />
 			<description>
@@ -108,24 +132,66 @@
 			A higher value means it's more flexible for detecting collision, which helps with consistently detecting walls and floors.
 			A lower value forces the collision algorithm to use more exact detection, so it can be used in cases that specifically require precision, e.g at very low scale to avoid visible jittering, or for stability with a stack of character bodies.
 		</member>
+		<member name="floor_block_on_wall" type="bool" setter="set_floor_block_on_wall_enabled" getter="is_floor_block_on_wall_enabled" default="true">
+			If [code]true[/code], the body will be able to move on the floor only. This option avoids to be able to walk on walls, it will however allow to slide down along them.
+		</member>
+		<member name="floor_constant_speed" type="bool" setter="set_floor_constant_speed_enabled" getter="is_floor_constant_speed_enabled" default="false">
+			If [code]false[/code] (by default), the body will move faster on downward slopes and slower on upward slopes.
+			If [code]true[/code], the body will always move at the same speed on the ground no matter the slope. Note that you need to use [member floor_snap_length] to stick along a downward slope at constant speed.
+		</member>
 		<member name="floor_max_angle" type="float" setter="set_floor_max_angle" getter="get_floor_max_angle" default="0.785398">
 			Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling [method move_and_slide]. The default value equals 45 degrees.
 		</member>
+		<member name="floor_snap_length" type="float" setter="set_floor_snap_length" getter="get_floor_snap_length" default="0.1">
+			Sets a snapping distance. When set to a value different from [code]0.0[/code], the body is kept attached to slopes when calling [method move_and_slide]. The snapping vector is determined by the given distance along the opposite direction of the [member up_direction].
+			As long as the snapping vector is in contact with the ground and the body moves against `up_direction`, the body will remain attached to the surface. Snapping is not applied if the body moves along `up_direction`, so it will be able to detach from the ground when jumping.
+		</member>
 		<member name="floor_stop_on_slope" type="bool" setter="set_floor_stop_on_slope_enabled" getter="is_floor_stop_on_slope_enabled" default="false">
 			If [code]true[/code], the body will not slide on slopes when you include gravity in [code]linear_velocity[/code] when calling [method move_and_slide] and the body is standing still.
 		</member>
 		<member name="linear_velocity" type="Vector3" setter="set_linear_velocity" getter="get_linear_velocity" default="Vector3(0, 0, 0)">
 			Current velocity vector (typically meters per second), used and modified during calls to [method move_and_slide].
 		</member>
-		<member name="max_slides" type="int" setter="set_max_slides" getter="get_max_slides" default="4">
+		<member name="max_slides" type="int" setter="set_max_slides" getter="get_max_slides" default="6">
 			Maximum number of times the body can change direction before it stops when calling [method move_and_slide].
 		</member>
-		<member name="snap" type="Vector3" setter="set_snap" getter="get_snap" default="Vector3(0, 0, 0)">
-			When set to a value different from [code]Vector3(0, 0, 0)[/code], the body is kept attached to slopes when calling [method move_and_slide].
-			As long as the [code]snap[/code] vector is in contact with the ground, the body will remain attached to the surface. This means you must disable snap in order to jump, for example. You can do this by setting [code]snap[/code] to [code]Vector3(0, 0, 0)[/code].
+		<member name="motion_mode" type="int" setter="set_motion_mode" getter="get_motion_mode" enum="CharacterBody3D.MotionMode" default="0">
+			Sets the motion mode which defines the behaviour of [method move_and_slide]. See [enum MotionMode] constants for available modes.
+		</member>
+		<member name="moving_platform_apply_velocity_on_leave" type="int" setter="set_moving_platform_apply_velocity_on_leave" getter="get_moving_platform_apply_velocity_on_leave" enum="CharacterBody3D.MovingPlatformApplyVelocityOnLeave" default="0">
+			Sets the behaviour to apply when you leave a moving platform. By default, to be physically accurate, when you leave the last platform velocity is applied. See [enum MovingPlatformApplyVelocityOnLeave] constants for available behaviour.
+		</member>
+		<member name="moving_platform_floor_layers" type="int" setter="set_moving_platform_floor_layers" getter="get_moving_platform_floor_layers" default="4294967295">
+			Collision layers that will be included for detecting floor bodies that will act as moving platforms to be followed by the [CharacterBody2D]. By default, all floor bodies are detected and propagate their velocity.
+		</member>
+		<member name="moving_platform_wall_layers" type="int" setter="set_moving_platform_wall_layers" getter="get_moving_platform_wall_layers" default="0">
+			Collision layers that will be included for detecting wall bodies that will act as moving platforms to be followed by the [CharacterBody2D]. By default, all wall bodies are ignored.
+		</member>
+		<member name="slide_on_ceiling" type="bool" setter="set_slide_on_ceiling_enabled" getter="is_slide_on_ceiling_enabled" default="true">
+			If [code]true[/code], during a jump against the ceiling, the body will slide, if [code]false[/code] it will be stopped and will fall vertically.
 		</member>
 		<member name="up_direction" type="Vector3" setter="set_up_direction" getter="get_up_direction" default="Vector3(0, 1, 0)">
 			Direction vector used to determine what is a wall and what is a floor (or a ceiling), rather than a wall, when calling [method move_and_slide]. Defaults to [code]Vector3.UP[/code]. If set to [code]Vector3(0, 0, 0)[/code], everything is considered a wall. This is useful for topdown games.
 		</member>
+		<member name="wall_min_slide_angle" type="float" setter="set_wall_min_slide_angle" getter="get_wall_min_slide_angle" default="0.261799">
+			Minimum angle (in radians) where the body is allowed to slide when it encounters a slope. The default value equals 15 degrees. In [code]MOTION_MODE_GROUNDED[/code], it works only when [member floor_block_on_wall] is [code]true[/code].
+		</member>
 	</members>
+	<constants>
+		<constant name="MOTION_MODE_GROUNDED" value="0" enum="MotionMode">
+			Apply when notions of walls, ceiling and floor are relevant. In this mode the body motion will react to slopes (acceleration/slowdown). This mode is suitable for grounded games like platformers.
+		</constant>
+		<constant name="MOTION_MODE_FREE" value="1" enum="MotionMode">
+			Apply when there is no notion of floor or ceiling. All collisions will be reported as [code]on_wall[/code]. In this mode, when you slide, the speed will always be constant. This mode is suitable for games without ground like space games.
+		</constant>
+		<constant name="PLATFORM_VEL_ON_LEAVE_ALWAYS" value="0" enum="MovingPlatformApplyVelocityOnLeave">
+			Add the last platform velocity to the [member linear_velocity] when you leave a moving platform.
+		</constant>
+		<constant name="PLATFORM_VEL_ON_LEAVE_UPWARD_ONLY" value="1" enum="MovingPlatformApplyVelocityOnLeave">
+			Add the last platform velocity to the [member linear_velocity] when you leave a moving platform, but any downward motion is ignored. It's useful to keep full jump height even when the platform is moving down.
+		</constant>
+		<constant name="PLATFORM_VEL_ON_LEAVE_NEVER" value="2" enum="MovingPlatformApplyVelocityOnLeave">
+			Do nothing when leaving a platform.
+		</constant>
+	</constants>
 </class>
diff --git a/doc/classes/KinematicCollision3D.xml b/doc/classes/KinematicCollision3D.xml
index bc2d80218d..db32cf57bc 100644
--- a/doc/classes/KinematicCollision3D.xml
+++ b/doc/classes/KinematicCollision3D.xml
@@ -12,41 +12,114 @@
 	<methods>
 		<method name="get_angle" qualifiers="const">
 			<return type="float" />
-			<argument index="0" name="up_direction" type="Vector3" default="Vector3(0, 1, 0)" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<argument index="1" name="up_direction" type="Vector3" default="Vector3(0, 1, 0)" />
 			<description>
 				The collision angle according to [code]up_direction[/code], which is [code]Vector3.UP[/code] by default. This value is always positive.
 			</description>
 		</method>
+		<method name="get_collider" qualifiers="const">
+			<return type="Object" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+				Returns the collider by index (the latest by default).
+			</description>
+		</method>
+		<method name="get_collider_id" qualifiers="const">
+			<return type="int" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+				Returns the collider ID by index (the latest by default).
+			</description>
+		</method>
+		<method name="get_collider_metadata" qualifiers="const">
+			<return type="Variant" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+				Returns the collider metadata by index (the latest by default).
+			</description>
+		</method>
+		<method name="get_collider_rid" qualifiers="const">
+			<return type="RID" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+				Returns the collider RID by index (the latest by default).
+			</description>
+		</method>
+		<method name="get_collider_shape" qualifiers="const">
+			<return type="Object" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+				Returns the collider shape by index (the latest by default).
+			</description>
+		</method>
+		<method name="get_collider_shape_index" qualifiers="const">
+			<return type="int" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+				Returns the collider shape index by index (the latest by default).
+			</description>
+		</method>
+		<method name="get_collider_velocity" qualifiers="const">
+			<return type="Vector3" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+				Returns the collider velocity by index (the latest by default).
+			</description>
+		</method>
+		<method name="get_local_shape" qualifiers="const">
+			<return type="Object" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+				Returns the collider velocity by index (the latest by default).
+			</description>
+		</method>
+		<method name="get_normal" qualifiers="const">
+			<return type="Vector3" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+				Returns the collider normal by index (the latest by default).
+			</description>
+		</method>
+		<method name="get_position" qualifiers="const">
+			<return type="Vector3" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+				Returns the collider collision point by index (the latest by default).
+			</description>
+		</method>
 	</methods>
 	<members>
-		<member name="collider" type="Object" setter="" getter="get_collider">
+		<member name="collider" type="Object" setter="" getter="get_best_collider">
 			The colliding body.
 		</member>
-		<member name="collider_id" type="int" setter="" getter="get_collider_id" default="0">
+		<member name="collider_id" type="int" setter="" getter="get_best_collider_id" default="0">
 			The colliding body's unique instance ID. See [method Object.get_instance_id].
 		</member>
-		<member name="collider_metadata" type="Variant" setter="" getter="get_collider_metadata">
+		<member name="collider_metadata" type="Variant" setter="" getter="get_best_collider_metadata">
 			The colliding body's metadata. See [Object].
 		</member>
-		<member name="collider_rid" type="RID" setter="" getter="get_collider_rid">
+		<member name="collider_rid" type="RID" setter="" getter="get_best_collider_rid">
 			The colliding body's [RID] used by the [PhysicsServer3D].
 		</member>
-		<member name="collider_shape" type="Object" setter="" getter="get_collider_shape">
+		<member name="collider_shape" type="Object" setter="" getter="get_best_collider_shape">
 			The colliding body's shape.
 		</member>
-		<member name="collider_shape_index" type="int" setter="" getter="get_collider_shape_index" default="0">
+		<member name="collider_shape_index" type="int" setter="" getter="get_best_collider_shape_index" default="0">
 			The colliding shape's index. See [CollisionObject3D].
 		</member>
-		<member name="collider_velocity" type="Vector3" setter="" getter="get_collider_velocity" default="Vector3(0, 0, 0)">
+		<member name="collider_velocity" type="Vector3" setter="" getter="get_best_collider_velocity" default="Vector3(0, 0, 0)">
 			The colliding object's velocity.
 		</member>
-		<member name="local_shape" type="Object" setter="" getter="get_local_shape">
+		<member name="collision_count" type="int" setter="" getter="get_collision_count" default="0">
+		</member>
+		<member name="local_shape" type="Object" setter="" getter="get_best_local_shape">
 			The moving object's colliding shape.
 		</member>
-		<member name="normal" type="Vector3" setter="" getter="get_normal" default="Vector3(0, 0, 0)">
+		<member name="normal" type="Vector3" setter="" getter="get_best_normal" default="Vector3(0, 0, 0)">
 			The colliding body's shape's normal at the point of collision.
 		</member>
-		<member name="position" type="Vector3" setter="" getter="get_position" default="Vector3(0, 0, 0)">
+		<member name="position" type="Vector3" setter="" getter="get_best_position" default="Vector3(0, 0, 0)">
 			The point of collision, in global coordinates.
 		</member>
 		<member name="remainder" type="Vector3" setter="" getter="get_remainder" default="Vector3(0, 0, 0)">
diff --git a/doc/classes/PhysicsBody3D.xml b/doc/classes/PhysicsBody3D.xml
index 8b50bb7bd9..174e49ea2d 100644
--- a/doc/classes/PhysicsBody3D.xml
+++ b/doc/classes/PhysicsBody3D.xml
@@ -35,10 +35,12 @@
 			<argument index="0" name="rel_vec" type="Vector3" />
 			<argument index="1" name="test_only" type="bool" default="false" />
 			<argument index="2" name="safe_margin" type="float" default="0.001" />
+			<argument index="3" name="max_collisions" type="int" default="1" />
 			<description>
 				Moves the body along the vector [code]rel_vec[/code]. The body will stop if it collides. Returns a [KinematicCollision3D], which contains information about the collision.
 				If [code]test_only[/code] is [code]true[/code], the body does not move but the would-be collision information is given.
 				[code]safe_margin[/code] is the extra margin used for collision recovery (see [member CharacterBody3D.collision/safe_margin] for more details).
+				[code]max_collisions[/code] allows to retrieve more than one collision result.
 			</description>
 		</method>
 		<method name="remove_collision_exception_with">
@@ -62,10 +64,12 @@
 			<argument index="1" name="rel_vec" type="Vector3" />
 			<argument index="2" name="collision" type="KinematicCollision3D" default="null" />
 			<argument index="3" name="safe_margin" type="float" default="0.001" />
+			<argument index="4" name="max_collisions" type="int" default="1" />
 			<description>
 				Checks for collisions without moving the body. Virtually sets the node's position, scale and rotation to that of the given [Transform3D], then tries to move the body along the vector [code]rel_vec[/code]. Returns [code]true[/code] if a collision would occur.
 				[code]collision[/code] is an optional object of type [KinematicCollision3D], which contains additional information about the collision (should there be one).
 				[code]safe_margin[/code] is the extra margin used for collision recovery (see [member CharacterBody3D.collision/safe_margin] for more details).
+				[code]max_collisions[/code] allows to retrieve more than one collision result.
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/PhysicsServer3D.xml b/doc/classes/PhysicsServer3D.xml
index 5497ae7412..9f48c36b62 100644
--- a/doc/classes/PhysicsServer3D.xml
+++ b/doc/classes/PhysicsServer3D.xml
@@ -583,6 +583,7 @@
 			<argument index="4" name="result" type="PhysicsTestMotionResult3D" default="null" />
 			<argument index="5" name="collide_separation_ray" type="bool" default="false" />
 			<argument index="6" name="exclude" type="Array" default="[]" />
+			<argument index="7" name="max_collisions" type="int" default="1" />
 			<description>
 				Returns [code]true[/code] if a collision would result from moving in the given direction from a given point in space. Margin increases the size of the shapes involved in the collision detection. [PhysicsTestMotionResult3D] can be passed to return additional information in.
 			</description>
diff --git a/doc/classes/PhysicsTestMotionResult3D.xml b/doc/classes/PhysicsTestMotionResult3D.xml
index c2d6709412..8aa087e99a 100644
--- a/doc/classes/PhysicsTestMotionResult3D.xml
+++ b/doc/classes/PhysicsTestMotionResult3D.xml
@@ -6,30 +6,82 @@
 	</description>
 	<tutorials>
 	</tutorials>
+	<methods>
+		<method name="get_collider" qualifiers="const">
+			<return type="Object" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+			</description>
+		</method>
+		<method name="get_collider_id" qualifiers="const">
+			<return type="int" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+			</description>
+		</method>
+		<method name="get_collider_rid" qualifiers="const">
+			<return type="RID" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+			</description>
+		</method>
+		<method name="get_collider_shape" qualifiers="const">
+			<return type="int" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+			</description>
+		</method>
+		<method name="get_collider_velocity" qualifiers="const">
+			<return type="Vector3" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+			</description>
+		</method>
+		<method name="get_collision_depth" qualifiers="const">
+			<return type="float" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+			</description>
+		</method>
+		<method name="get_collision_normal" qualifiers="const">
+			<return type="Vector3" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+			</description>
+		</method>
+		<method name="get_collision_point" qualifiers="const">
+			<return type="Vector3" />
+			<argument index="0" name="collision_index" type="int" default="0" />
+			<description>
+			</description>
+		</method>
+	</methods>
 	<members>
-		<member name="collider" type="Object" setter="" getter="get_collider">
+		<member name="collider" type="Object" setter="" getter="get_best_collider">
 		</member>
-		<member name="collider_id" type="int" setter="" getter="get_collider_id" default="0">
+		<member name="collider_id" type="int" setter="" getter="get_best_collider_id" default="0">
 		</member>
-		<member name="collider_rid" type="RID" setter="" getter="get_collider_rid">
+		<member name="collider_rid" type="RID" setter="" getter="get_best_collider_rid">
 		</member>
-		<member name="collider_shape" type="int" setter="" getter="get_collider_shape" default="0">
+		<member name="collider_shape" type="int" setter="" getter="get_best_collider_shape" default="0">
 		</member>
-		<member name="collider_velocity" type="Vector3" setter="" getter="get_collider_velocity" default="Vector3(0, 0, 0)">
+		<member name="collider_velocity" type="Vector3" setter="" getter="get_best_collider_velocity" default="Vector3(0, 0, 0)">
 		</member>
-		<member name="collision_depth" type="float" setter="" getter="get_collision_depth" default="0.0">
+		<member name="collision_count" type="int" setter="" getter="get_collision_count" default="0">
 		</member>
-		<member name="collision_normal" type="Vector3" setter="" getter="get_collision_normal" default="Vector3(0, 0, 0)">
+		<member name="collision_depth" type="float" setter="" getter="get_best_collision_depth" default="0.0">
 		</member>
-		<member name="collision_point" type="Vector3" setter="" getter="get_collision_point" default="Vector3(0, 0, 0)">
+		<member name="collision_normal" type="Vector3" setter="" getter="get_best_collision_normal" default="Vector3(0, 0, 0)">
 		</member>
-		<member name="collision_safe_fraction" type="float" setter="" getter="get_collision_safe_fraction" default="0.0">
-		</member>
-		<member name="collision_unsafe_fraction" type="float" setter="" getter="get_collision_unsafe_fraction" default="0.0">
+		<member name="collision_point" type="Vector3" setter="" getter="get_best_collision_point" default="Vector3(0, 0, 0)">
 		</member>
 		<member name="remainder" type="Vector3" setter="" getter="get_remainder" default="Vector3(0, 0, 0)">
 		</member>
+		<member name="safe_fraction" type="float" setter="" getter="get_safe_fraction" default="0.0">
+		</member>
 		<member name="travel" type="Vector3" setter="" getter="get_travel" default="Vector3(0, 0, 0)">
 		</member>
+		<member name="unsafe_fraction" type="float" setter="" getter="get_unsafe_fraction" default="0.0">
+		</member>
 	</members>
 </class>