Made slide and reflect active verbs acting on itself in Vector2 and Vector3.

This is in alignment with other functions in vector classes.
Also added checks for normalization, fixed the sign of reflect (which now corresponds to reflection along a plane mathematically), added bounce method and updated docs.

Fixes #8201.

6 files changed, 72 insertions, 23 deletions

diff --git a/core/math/math_2d.cpp b/core/math/math_2d.cpp
index 8f942c423f..77cff6a052 100644
--- a/core/math/math_2d.cpp
+++ b/core/math/math_2d.cpp
@@ -61,6 +61,10 @@ Vector2 Vector2::normalized() const {
 	return v;
 }
 
+bool Vector2::is_normalized() const {
+	return Math::isequal_approx(length(), (real_t)1.0);
+}
+
 real_t Vector2::distance_to(const Vector2 &p_vector2) const {
 
 	return Math::sqrt((x - p_vector2.x) * (x - p_vector2.x) + (y - p_vector2.y) * (y - p_vector2.y));
@@ -274,13 +278,23 @@ Vector2 Vector2::cubic_interpolate(const Vector2 &p_b, const Vector2 &p_pre_a, c
 */
 }
 
-Vector2 Vector2::slide(const Vector2 &p_vec) const {
+// slide returns the component of the vector along the given plane, specified by its normal vector.
+Vector2 Vector2::slide(const Vector2 &p_n) const {
+#ifdef DEBUG_ENABLED
+	ERR_FAIL_COND_V(p_n.is_normalized() == false, Vector2());
+#endif
+	return *this - p_n * this->dot(p_n);
+}
 
-	return p_vec - *this * this->dot(p_vec);
+Vector2 Vector2::bounce(const Vector2 &p_n) const {
+	return -reflect(p_n);
 }
-Vector2 Vector2::reflect(const Vector2 &p_vec) const {
 
-	return p_vec - *this * this->dot(p_vec) * 2.0;
+Vector2 Vector2::reflect(const Vector2 &p_n) const {
+#ifdef DEBUG_ENABLED
+	ERR_FAIL_COND_V(p_n.is_normalized() == false, Vector2());
+#endif
+	return 2.0 * p_n * this->dot(p_n) - *this;
 }
 
 bool Rect2::intersects_segment(const Point2 &p_from, const Point2 &p_to, Point2 *r_pos, Point2 *r_normal) const {
diff --git a/core/math/math_2d.h b/core/math/math_2d.h
index af6437d7f1..50ebcb845f 100644
--- a/core/math/math_2d.h
+++ b/core/math/math_2d.h
@@ -82,6 +82,7 @@ struct Vector2 {
 
 	void normalize();
 	Vector2 normalized() const;
+	bool is_normalized() const;
 
 	real_t length() const;
 	real_t length_squared() const;
@@ -106,6 +107,7 @@ struct Vector2 {
 	Vector2 cubic_interpolate_soft(const Vector2 &p_b, const Vector2 &p_pre_a, const Vector2 &p_post_b, real_t p_t) const;
 
 	Vector2 slide(const Vector2 &p_vec) const;
+	Vector2 bounce(const Vector2 &p_vec) const;
 	Vector2 reflect(const Vector2 &p_vec) const;
 
 	Vector2 operator+(const Vector2 &p_v) const;
diff --git a/core/math/vector3.h b/core/math/vector3.h
index 951380e898..8550ae7009 100644
--- a/core/math/vector3.h
+++ b/core/math/vector3.h
@@ -107,6 +107,7 @@ struct Vector3 {
 	_FORCE_INLINE_ real_t angle_to(const Vector3 &p_b) const;
 
 	_FORCE_INLINE_ Vector3 slide(const Vector3 &p_vec) const;
+	_FORCE_INLINE_ Vector3 bounce(const Vector3 &p_vec) const;
 	_FORCE_INLINE_ Vector3 reflect(const Vector3 &p_vec) const;
 
 	/* Operators */
@@ -400,14 +401,23 @@ void Vector3::zero() {
 	x = y = z = 0;
 }
 
-Vector3 Vector3::slide(const Vector3 &p_vec) const {
-
-	return p_vec - *this * this->dot(p_vec);
+// slide returns the component of the vector along the given plane, specified by its normal vector.
+Vector3 Vector3::slide(const Vector3 &p_n) const {
+#ifdef DEBUG_ENABLED
+	ERR_FAIL_COND_V(p_n.is_normalized() == false, Vector3());
+#endif
+	return *this - p_n * this->dot(p_n);
 }
 
-Vector3 Vector3::reflect(const Vector3 &p_vec) const {
+Vector3 Vector3::bounce(const Vector3 &p_n) const {
+	return -reflect(p_n);
+}
 
-	return p_vec - *this * this->dot(p_vec) * 2.0;
+Vector3 Vector3::reflect(const Vector3 &p_n) const {
+#ifdef DEBUG_ENABLED
+	ERR_FAIL_COND_V(p_n.is_normalized() == false, Vector3());
+#endif
+	return 2.0 * p_n * this->dot(p_n) - *this;
 }
 
 #endif
diff --git a/core/variant_call.cpp b/core/variant_call.cpp
index 758500a873..9c435ea0e5 100644
--- a/core/variant_call.cpp
+++ b/core/variant_call.cpp
@@ -340,6 +340,7 @@ struct _VariantCall {
 	VCALL_LOCALMEM0R(Vector2, aspect);
 	VCALL_LOCALMEM1R(Vector2, dot);
 	VCALL_LOCALMEM1R(Vector2, slide);
+	VCALL_LOCALMEM1R(Vector2, bounce);
 	VCALL_LOCALMEM1R(Vector2, reflect);
 	VCALL_LOCALMEM0R(Vector2, angle);
 	//VCALL_LOCALMEM1R(Vector2,cross);
@@ -377,6 +378,7 @@ struct _VariantCall {
 	VCALL_LOCALMEM1R(Vector3, distance_squared_to);
 	VCALL_LOCALMEM1R(Vector3, angle_to);
 	VCALL_LOCALMEM1R(Vector3, slide);
+	VCALL_LOCALMEM1R(Vector3, bounce);
 	VCALL_LOCALMEM1R(Vector3, reflect);
 
 	VCALL_LOCALMEM0R(Plane, normalized);
@@ -1438,8 +1440,9 @@ void register_variant_methods() {
 	ADDFUNC1(VECTOR2, VECTOR2, Vector2, snapped, VECTOR2, "by", varray());
 	ADDFUNC0(VECTOR2, REAL, Vector2, aspect, varray());
 	ADDFUNC1(VECTOR2, REAL, Vector2, dot, VECTOR2, "with", varray());
-	ADDFUNC1(VECTOR2, VECTOR2, Vector2, slide, VECTOR2, "vec", varray());
-	ADDFUNC1(VECTOR2, VECTOR2, Vector2, reflect, VECTOR2, "vec", varray());
+	ADDFUNC1(VECTOR2, VECTOR2, Vector2, slide, VECTOR2, "n", varray());
+	ADDFUNC1(VECTOR2, VECTOR2, Vector2, bounce, VECTOR2, "n", varray());
+	ADDFUNC1(VECTOR2, VECTOR2, Vector2, reflect, VECTOR2, "n", varray());
 	//ADDFUNC1(VECTOR2,REAL,Vector2,cross,VECTOR2,"with",varray());
 	ADDFUNC0(VECTOR2, VECTOR2, Vector2, abs, varray());
 	ADDFUNC1(VECTOR2, VECTOR2, Vector2, clamped, REAL, "length", varray());
@@ -1475,8 +1478,9 @@ void register_variant_methods() {
 	ADDFUNC1(VECTOR3, REAL, Vector3, distance_to, VECTOR3, "b", varray());
 	ADDFUNC1(VECTOR3, REAL, Vector3, distance_squared_to, VECTOR3, "b", varray());
 	ADDFUNC1(VECTOR3, REAL, Vector3, angle_to, VECTOR3, "to", varray());
-	ADDFUNC1(VECTOR3, VECTOR3, Vector3, slide, VECTOR3, "by", varray());
-	ADDFUNC1(VECTOR3, VECTOR3, Vector3, reflect, VECTOR3, "by", varray());
+	ADDFUNC1(VECTOR3, VECTOR3, Vector3, slide, VECTOR3, "n", varray());
+	ADDFUNC1(VECTOR3, VECTOR3, Vector3, bounce, VECTOR3, "n", varray());
+	ADDFUNC1(VECTOR3, VECTOR3, Vector3, reflect, VECTOR3, "n", varray());
 
 	ADDFUNC0(PLANE, PLANE, Plane, normalized, varray());
 	ADDFUNC0(PLANE, VECTOR3, Plane, center, varray());
diff --git a/doc/base/classes.xml b/doc/base/classes.xml
index f3d73deaf0..7e4d536299 100644
--- a/doc/base/classes.xml
+++ b/doc/base/classes.xml
@@ -46992,6 +46992,15 @@ do_property].
 				Returns the ratio of X to Y.
 			</description>
 		</method>
+		<method name="bounce">
+			<return type="Vector2">
+			</return>
+			<argument index="0" name="n" type="Vector2">
+			</argument>
+			<description>
+				Bounce returns the vector "bounced off" from the given plane, specified by its normal vector.
+			</description>
+		</method>
 		<method name="clamped">
 			<return type="Vector2">
 			</return>
@@ -47084,10 +47093,10 @@ do_property].
 		<method name="reflect">
 			<return type="Vector2">
 			</return>
-			<argument index="0" name="vec" type="Vector2">
+			<argument index="0" name="n" type="Vector2">
 			</argument>
 			<description>
-				Like "slide", but reflects the Vector instead of continuing along the wall.
+				Reflects the vector along the given plane, specified by its normal vector.
 			</description>
 		</method>
 		<method name="rotated">
@@ -47102,10 +47111,10 @@ do_property].
 		<method name="slide">
 			<return type="Vector2">
 			</return>
-			<argument index="0" name="vec" type="Vector2">
+			<argument index="0" name="n" type="Vector2">
 			</argument>
 			<description>
-				Slides the vector by the other vector.
+				Slide returns the component of the vector along the given plane, specified by its normal vector.
 			</description>
 		</method>
 		<method name="snapped">
@@ -47178,6 +47187,15 @@ do_property].
 			<description>
 			</description>
 		</method>
+		<method name="bounce">
+			<return type="Vector3">
+			</return>
+			<argument index="0" name="n" type="Vector3">
+			</argument>
+			<description>
+				Bounce returns the vector "bounced off" from the given plane, specified by its normal vector.
+			</description>
+		</method>
 		<method name="ceil">
 			<return type="Vector3">
 			</return>
@@ -47308,10 +47326,10 @@ do_property].
 		<method name="reflect">
 			<return type="Vector3">
 			</return>
-			<argument index="0" name="by" type="Vector3">
+			<argument index="0" name="n" type="Vector3">
 			</argument>
 			<description>
-				Like "slide", but reflects the Vector instead of continuing along the wall.
+				Reflects the vector along the given plane, specified by its normal vector.
 			</description>
 		</method>
 		<method name="rotated">
@@ -47328,10 +47346,10 @@ do_property].
 		<method name="slide">
 			<return type="Vector3">
 			</return>
-			<argument index="0" name="by" type="Vector3">
+			<argument index="0" name="n" type="Vector3">
 			</argument>
 			<description>
-				Slides the vector along a wall.
+				Slide returns the component of the vector along the given plane, specified by its normal vector.
 			</description>
 		</method>
 		<method name="snapped">
diff --git a/scene/2d/physics_body_2d.cpp b/scene/2d/physics_body_2d.cpp
index 88845a7290..f820c955a7 100644
--- a/scene/2d/physics_body_2d.cpp
+++ b/scene/2d/physics_body_2d.cpp
@@ -1205,8 +1205,9 @@ Vector2 KinematicBody2D::move_and_slide(const Vector2 &p_linear_velocity, const
 				}
 			}
 
-			motion = get_collision_normal().slide(motion);
-			lv = get_collision_normal().slide(lv);
+			Vector2 n = get_collision_normal();
+			motion = motion.slide(n);
+			lv = lv.slide(n);
 			Variant collider = _get_collider();
 			if (collider.get_type() != Variant::NIL) {
 				move_and_slide_colliders.push_back(collider);