Merge pull request #37880 from nekomatata/rigid-body-damping-override

Improved RigidDynamicBody linear/angular damping override

5 files changed, 80 insertions, 18 deletions

diff --git a/doc/classes/PhysicalBone3D.xml b/doc/classes/PhysicalBone3D.xml
index 710e96239b..a9963d59e8 100644
--- a/doc/classes/PhysicalBone3D.xml
+++ b/doc/classes/PhysicalBone3D.xml
@@ -37,8 +37,12 @@
 		</method>
 	</methods>
 	<members>
-		<member name="angular_damp" type="float" setter="set_angular_damp" getter="get_angular_damp" default="-1.0">
-			Damps the body's rotation if greater than [code]0[/code].
+		<member name="angular_damp" type="float" setter="set_angular_damp" getter="get_angular_damp" default="0.0">
+			Damps the body's rotation. By default, the body will use the [b]Default Angular Damp[/b] in [b]Project &gt; Project Settings &gt; Physics &gt; 3d[/b] or any value override set by an [Area3D] the body is in. Depending on [member angular_damp_mode], you can set [member angular_damp] to be added to or to replace the body's damping value.
+			See [member ProjectSettings.physics/3d/default_angular_damp] for more details about damping.
+		</member>
+		<member name="angular_damp_mode" type="int" setter="set_angular_damp_mode" getter="get_angular_damp_mode" enum="PhysicalBone3D.DampMode" default="0">
+			Defines how [member angular_damp] is applied. See [enum DampMode] for possible values.
 		</member>
 		<member name="body_offset" type="Transform3D" setter="set_body_offset" getter="get_body_offset" default="Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)">
 			Sets the body's transform.
@@ -64,14 +68,24 @@
 		<member name="joint_type" type="int" setter="set_joint_type" getter="get_joint_type" enum="PhysicalBone3D.JointType" default="0">
 			Sets the joint type. See [enum JointType] for possible values.
 		</member>
-		<member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="-1.0">
-			Damps the body's movement if greater than [code]0[/code].
+		<member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="0.0">
+			Damps the body's movement. By default, the body will use the [b]Default Linear Damp[/b] in [b]Project &gt; Project Settings &gt; Physics &gt; 3d[/b] or any value override set by an [Area3D] the body is in. Depending on [member linear_damp_mode], you can set [member linear_damp] to be added to or to replace the body's damping value.
+			See [member ProjectSettings.physics/3d/default_linear_damp] for more details about damping.
+		</member>
+		<member name="linear_damp_mode" type="int" setter="set_linear_damp_mode" getter="get_linear_damp_mode" enum="PhysicalBone3D.DampMode" default="0">
+			Defines how [member linear_damp] is applied. See [enum DampMode] for possible values.
 		</member>
 		<member name="mass" type="float" setter="set_mass" getter="get_mass" default="1.0">
 			The body's mass.
 		</member>
 	</members>
 	<constants>
+		<constant name="DAMP_MODE_COMBINE" value="0" enum="DampMode">
+			In this mode, the body's damping value is added to any value set in areas or the default value.
+		</constant>
+		<constant name="DAMP_MODE_REPLACE" value="1" enum="DampMode">
+			In this mode, the body's damping value replaces any value set in areas or the default value.
+		</constant>
 		<constant name="JOINT_TYPE_NONE" value="0" enum="JointType">
 		</constant>
 		<constant name="JOINT_TYPE_PIN" value="1" enum="JointType">
diff --git a/doc/classes/PhysicsServer2D.xml b/doc/classes/PhysicsServer2D.xml
index d55feff829..24a20b5613 100644
--- a/doc/classes/PhysicsServer2D.xml
+++ b/doc/classes/PhysicsServer2D.xml
@@ -926,15 +926,27 @@
 		<constant name="BODY_PARAM_GRAVITY_SCALE" value="5" enum="BodyParameter">
 			Constant to set/get a body's gravity multiplier.
 		</constant>
-		<constant name="BODY_PARAM_LINEAR_DAMP" value="6" enum="BodyParameter">
+		<constant name="BODY_PARAM_LINEAR_DAMP_MODE" value="6" enum="BodyParameter">
+			Constant to set/get a body's linear dampening mode. See [enum BodyDampMode] for possible values.
+		</constant>
+		<constant name="BODY_PARAM_ANGULAR_DAMP_MODE" value="7" enum="BodyParameter">
+			Constant to set/get a body's angular dampening mode. See [enum BodyDampMode] for possible values.
+		</constant>
+		<constant name="BODY_PARAM_LINEAR_DAMP" value="8" enum="BodyParameter">
 			Constant to set/get a body's linear dampening factor.
 		</constant>
-		<constant name="BODY_PARAM_ANGULAR_DAMP" value="7" enum="BodyParameter">
+		<constant name="BODY_PARAM_ANGULAR_DAMP" value="9" enum="BodyParameter">
 			Constant to set/get a body's angular dampening factor.
 		</constant>
-		<constant name="BODY_PARAM_MAX" value="8" enum="BodyParameter">
+		<constant name="BODY_PARAM_MAX" value="10" enum="BodyParameter">
 			Represents the size of the [enum BodyParameter] enum.
 		</constant>
+		<constant name="BODY_DAMP_MODE_COMBINE" value="0" enum="BodyDampMode">
+			The body's damping value is added to any value set in areas or the default value.
+		</constant>
+		<constant name="BODY_DAMP_MODE_REPLACE" value="1" enum="BodyDampMode">
+			The body's damping value replaces any value set in areas or the default value.
+		</constant>
 		<constant name="BODY_STATE_TRANSFORM" value="0" enum="BodyState">
 			Constant to set/get the current transform matrix of the body.
 		</constant>
diff --git a/doc/classes/PhysicsServer3D.xml b/doc/classes/PhysicsServer3D.xml
index 0e32d1defa..034bd55519 100644
--- a/doc/classes/PhysicsServer3D.xml
+++ b/doc/classes/PhysicsServer3D.xml
@@ -1294,15 +1294,27 @@
 		<constant name="BODY_PARAM_GRAVITY_SCALE" value="5" enum="BodyParameter">
 			Constant to set/get a body's gravity multiplier.
 		</constant>
-		<constant name="BODY_PARAM_LINEAR_DAMP" value="6" enum="BodyParameter">
+		<constant name="BODY_PARAM_LINEAR_DAMP_MODE" value="6" enum="BodyParameter">
+			Constant to set/get a body's linear dampening mode. See [enum BodyDampMode] for possible values.
+		</constant>
+		<constant name="BODY_PARAM_ANGULAR_DAMP_MODE" value="7" enum="BodyParameter">
+			Constant to set/get a body's angular dampening mode. See [enum BodyDampMode] for possible values.
+		</constant>
+		<constant name="BODY_PARAM_LINEAR_DAMP" value="8" enum="BodyParameter">
 			Constant to set/get a body's linear dampening factor.
 		</constant>
-		<constant name="BODY_PARAM_ANGULAR_DAMP" value="7" enum="BodyParameter">
+		<constant name="BODY_PARAM_ANGULAR_DAMP" value="9" enum="BodyParameter">
 			Constant to set/get a body's angular dampening factor.
 		</constant>
-		<constant name="BODY_PARAM_MAX" value="8" enum="BodyParameter">
+		<constant name="BODY_PARAM_MAX" value="10" enum="BodyParameter">
 			Represents the size of the [enum BodyParameter] enum.
 		</constant>
+		<constant name="BODY_DAMP_MODE_COMBINE" value="0" enum="BodyDampMode">
+			The body's damping value is added to any value set in areas or the default value.
+		</constant>
+		<constant name="BODY_DAMP_MODE_REPLACE" value="1" enum="BodyDampMode">
+			The body's damping value replaces any value set in areas or the default value.
+		</constant>
 		<constant name="BODY_STATE_TRANSFORM" value="0" enum="BodyState">
 			Constant to set/get the current transform matrix of the body.
 		</constant>
diff --git a/doc/classes/RigidDynamicBody2D.xml b/doc/classes/RigidDynamicBody2D.xml
index f503884192..b8680b99b3 100644
--- a/doc/classes/RigidDynamicBody2D.xml
+++ b/doc/classes/RigidDynamicBody2D.xml
@@ -82,10 +82,13 @@
 		</method>
 	</methods>
 	<members>
-		<member name="angular_damp" type="float" setter="set_angular_damp" getter="get_angular_damp" default="-1.0">
-			Damps the body's [member angular_velocity]. If [code]-1[/code], the body will use the [b]Default Angular Damp[/b] defined in [b]Project &gt; Project Settings &gt; Physics &gt; 2d[/b].
+		<member name="angular_damp" type="float" setter="set_angular_damp" getter="get_angular_damp" default="0.0">
+			Damps the body's rotation. By default, the body will use the [b]Default Angular Damp[/b] in [b]Project &gt; Project Settings &gt; Physics &gt; 2d[/b] or any value override set by an [Area2D] the body is in. Depending on [member angular_damp_mode], you can set [member angular_damp] to be added to or to replace the body's damping value.
 			See [member ProjectSettings.physics/2d/default_angular_damp] for more details about damping.
 		</member>
+		<member name="angular_damp_mode" type="int" setter="set_angular_damp_mode" getter="get_angular_damp_mode" enum="RigidDynamicBody2D.DampMode" default="0">
+			Defines how [member angular_damp] is applied. See [enum DampMode] for possible values.
+		</member>
 		<member name="angular_velocity" type="float" setter="set_angular_velocity" getter="get_angular_velocity" default="0.0">
 			The body's rotational velocity.
 		</member>
@@ -135,10 +138,13 @@
 			The body's moment of inertia. This is like mass, but for rotation: it determines how much torque it takes to rotate the body. The moment of inertia is usually computed automatically from the mass and the shapes, but this property allows you to set a custom value.
 			If set to [code]0[/code], inertia is automatically computed (default value).
 		</member>
-		<member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="-1.0">
-			Damps the body's [member linear_velocity]. If [code]-1[/code], the body will use the [b]Default Linear Damp[/b] in [b]Project &gt; Project Settings &gt; Physics &gt; 2d[/b].
+		<member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="0.0">
+			Damps the body's movement. By default, the body will use the [b]Default Linear Damp[/b] in [b]Project &gt; Project Settings &gt; Physics &gt; 2d[/b] or any value override set by an [Area2D] the body is in. Depending on [member linear_damp_mode], you can set [member linear_damp] to be added to or to replace the body's damping value.
 			See [member ProjectSettings.physics/2d/default_linear_damp] for more details about damping.
 		</member>
+		<member name="linear_damp_mode" type="int" setter="set_linear_damp_mode" getter="get_linear_damp_mode" enum="RigidDynamicBody2D.DampMode" default="0">
+			Defines how [member linear_damp] is applied. See [enum DampMode] for possible values.
+		</member>
 		<member name="linear_velocity" type="Vector2" setter="set_linear_velocity" getter="get_linear_velocity" default="Vector2(0, 0)">
 			The body's linear velocity.
 		</member>
@@ -217,6 +223,12 @@
 		<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.
 		</constant>
+		<constant name="DAMP_MODE_COMBINE" value="0" enum="DampMode">
+			In this mode, the body's damping value is added to any value set in areas or the default value.
+		</constant>
+		<constant name="DAMP_MODE_REPLACE" value="1" enum="DampMode">
+			In this mode, the body's damping value replaces any value set in areas or the default value.
+		</constant>
 		<constant name="CCD_MODE_DISABLED" value="0" enum="CCDMode">
 			Continuous collision detection disabled. This is the fastest way to detect body collisions, but can miss small, fast-moving objects.
 		</constant>
diff --git a/doc/classes/RigidDynamicBody3D.xml b/doc/classes/RigidDynamicBody3D.xml
index 6c8d190704..ba9acdf4bf 100644
--- a/doc/classes/RigidDynamicBody3D.xml
+++ b/doc/classes/RigidDynamicBody3D.xml
@@ -91,10 +91,13 @@
 		</method>
 	</methods>
 	<members>
-		<member name="angular_damp" type="float" setter="set_angular_damp" getter="get_angular_damp" default="-1.0">
-			Damps RigidDynamicBody3D's rotational forces.
+		<member name="angular_damp" type="float" setter="set_angular_damp" getter="get_angular_damp" default="0.0">
+			Damps the body's rotation. By default, the body will use the [b]Default Angular Damp[/b] in [b]Project &gt; Project Settings &gt; Physics &gt; 3d[/b] or any value override set by an [Area3D] the body is in. Depending on [member angular_damp_mode], you can set [member angular_damp] to be added to or to replace the body's damping value.
 			See [member ProjectSettings.physics/3d/default_angular_damp] for more details about damping.
 		</member>
+		<member name="angular_damp_mode" type="int" setter="set_angular_damp_mode" getter="get_angular_damp_mode" enum="RigidDynamicBody3D.DampMode" default="0">
+			Defines how [member angular_damp] is applied. See [enum DampMode] for possible values.
+		</member>
 		<member name="angular_velocity" type="Vector3" setter="set_angular_velocity" getter="get_angular_velocity" default="Vector3(0, 0, 0)">
 			RigidDynamicBody3D's rotational velocity.
 		</member>
@@ -138,10 +141,13 @@
 			The body's moment of inertia. This is like mass, but for rotation: it determines how much torque it takes to rotate the body on each axis. The moment of inertia is usually computed automatically from the mass and the shapes, but this property allows you to set a custom value.
 			If set to [code]Vector3.ZERO[/code], inertia is automatically computed (default value).
 		</member>
-		<member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="-1.0">
-			The body's linear damp. Cannot be less than -1.0. If this value is different from -1.0, any linear damp derived from the world or areas will be overridden.
+		<member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="0.0">
+			Damps the body's movement. By default, the body will use the [b]Default Linear Damp[/b] in [b]Project &gt; Project Settings &gt; Physics &gt; 3d[/b] or any value override set by an [Area3D] the body is in. Depending on [member linear_damp_mode], you can set [member linear_damp] to be added to or to replace the body's damping value.
 			See [member ProjectSettings.physics/3d/default_linear_damp] for more details about damping.
 		</member>
+		<member name="linear_damp_mode" type="int" setter="set_linear_damp_mode" getter="get_linear_damp_mode" enum="RigidDynamicBody3D.DampMode" default="0">
+			Defines how [member linear_damp] is applied. See [enum DampMode] for possible values.
+		</member>
 		<member name="linear_velocity" type="Vector3" setter="set_linear_velocity" getter="get_linear_velocity" default="Vector3(0, 0, 0)">
 			The body's linear velocity. Can be used sporadically, but [b]don't set this every frame[/b], because physics may run in another thread and runs at a different granularity. Use [method _integrate_forces] as your process loop for precise control of the body state.
 		</member>
@@ -222,5 +228,11 @@
 		<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.
 		</constant>
+		<constant name="DAMP_MODE_COMBINE" value="0" enum="DampMode">
+			In this mode, the body's damping value is added to any value set in areas or the default value.
+		</constant>
+		<constant name="DAMP_MODE_REPLACE" value="1" enum="DampMode">
+			In this mode, the body's damping value replaces any value set in areas or the default value.
+		</constant>
 	</constants>
 </class>