Add units and docs for Joint3D/2D stiffness and damping

Author: aaronfranke

doc/classes/ConeTwistJoint3D.xml

@@ -31,10 +31,12 @@
 			The higher, the faster.
 		</member>
 		<member name="relaxation" type="float" setter="set_param" getter="get_param" default="1.0">
-			Defines, how fast the swing- and twist-speed-difference on both sides gets synced.
+			The amount of relaxation, or inverse damping, applied to angular velocity when rotated beyond the swing span and/or twist span. It is measured in rad/N/m/s, or rad·s/kg/m² in SI base units. Unlike most joints in Godot which use damping, [ConeTwistJoint3D] uses inverse damping (relaxation), so higher values result in less damping and lower values result in more damping.
+			Higher relaxation values make the joint more elastic or bouncy. Lower values result in a smoother, more gradual reduction in swing and twist speed difference velocity, preventing oscillations or rapid rotation as the joint returns to its span limits.
 		</member>
 		<member name="softness" type="float" setter="set_param" getter="get_param" default="0.8">
-			The ease with which the joint starts to twist. If it's too low, it takes more force to start twisting the joint.
+			The stiffness factor applied to rotation beyond the swing span and twist span limits. It is measured in N·m/rad, or kg·m²/s²/rad in SI base units.
+			Higher angular stiffness results in a harder limit, which more strongly resists rotation beyond the limit. Lower values make the limit softer and more flexible.
 		</member>
 		<member name="swing_span" type="float" setter="set_param" getter="get_param" default="0.785398">
 			Swing is rotation from side to side, around the axis perpendicular to the twist axis.

doc/classes/DampedSpringJoint2D.xml

@@ -10,16 +10,18 @@
 	</tutorials>
 	<members>
 		<member name="damping" type="float" setter="set_damping" getter="get_damping" default="1.0">
-			The spring joint's damping ratio. A value between [code]0[/code] and [code]1[/code]. When the two bodies move into different directions the system tries to align them to the spring axis again. A high [member damping] value forces the attached bodies to align faster.
+			The amount of damping applied to by the spring joint. It is measured in kg/s.
+			Higher linear damping results in a more gradual reduction in linear velocity, creating smoother, gentler behavior as the spring returns to its equilibrium rest length, preventing oscillations or rapid movement. Lower values make the spring more elastic or bouncy.
 		</member>
 		<member name="length" type="float" setter="set_length" getter="get_length" default="50.0">
 			The spring joint's maximum length. The two attached bodies cannot stretch it past this value.
 		</member>
 		<member name="rest_length" type="float" setter="set_rest_length" getter="get_rest_length" default="0.0">
-			When the bodies attached to the spring joint move they stretch or squash it. The joint always tries to resize towards this length.
+			When the bodies attached to the spring joint move they stretch or squash it. The joint always tries to resize towards this length, known as the equilibrium length or rest length.
 		</member>
 		<member name="stiffness" type="float" setter="set_stiffness" getter="get_stiffness" default="20.0">
-			The higher the value, the less the bodies attached to the joint will deform it. The joint applies an opposing force to the bodies, the product of the stiffness multiplied by the size difference from its resting length.
+			The stiffness of the spring joint. It is measured in kg/s². The joint applies an opposing force to the bodies, the product of the stiffness multiplied by the size difference from its resting length.
+			Higher linear stiffness results in a more rigid spring, which more strongly resists being compressed or stretched away from its equilibrium rest length. Lower values make the spring more elastic or bouncy.
 		</member>
 	</members>
 </class>

doc/classes/Generic6DOFJoint3D.xml

@@ -51,9 +51,12 @@
 			The minimum rotation. Only active if [member angular_limit/enable] is [code]true[/code].
 		</member>
 		<member name="angular_limit/relaxation" type="float" setter="set_param" getter="get_param" default="1.0">
-			The lower this value, the more the rotation gets slowed down.
+			The amount of relaxation, or inverse damping, applied to angular velocity when the hinge is rotated beyond the angular limit around the Z axis. It is measured in rad/N/m/s, or rad·s/kg/m² in SI base units. Unlike most joints in Godot which use damping, HingeJoint3D uses inverse damping (relaxation), so higher values result in less damping and lower values result in more damping.
+			Higher relaxation values make the joint more elastic or bouncy. Lower values result in a smoother, more gradual reduction in angular velocity, preventing oscillations or rapid rotation as the joint returns to its angular limit.
 		</member>
 		<member name="angular_limit/softness" type="float" setter="set_param" getter="get_param" default="0.9" deprecated="This property is never set by the engine and is kept for compatibility purposes.">
+			The stiffness factor applied to rotation beyond the hinge's angular limit around the Z axis. It is measured in N·m/rad, or kg·m²/s²/rad in SI base units.
+			Higher angular stiffness results in a harder limit, which more strongly resists rotation beyond the limit. Lower values make the limit softer and more flexible.
 		</member>
 		<member name="angular_limit/upper" type="float" setter="set_param" getter="get_param" default="1.5708">
 			The maximum rotation. Only active if [member angular_limit/enable] is [code]true[/code].

doc/classes/HingeJoint3D.xml

@@ -25,7 +25,7 @@
 			Target speed for the motor. In radians per second.
 		</member>
 		<member name="softness" type="float" setter="set_softness" getter="get_softness" default="0.0">
-			The higher this value, the more the bond to the pinned partner can flex.
+			The higher this value, the more the bond to the pinned partner can flex. Lower values are stiffer, while higher values are softer. It is measured in s²/kg.
 		</member>
 	</members>
 </class>

doc/classes/PinJoint2D.xml

@@ -30,21 +30,23 @@
 			The force with which the pinned objects stay in positional relation to each other. The higher, the stronger.
 		</member>
 		<member name="params/damping" type="float" setter="set_param" getter="get_param" default="1.0">
-			The force with which the pinned objects stay in velocity relation to each other. The higher, the stronger.
+			The amount of damping applied to linear velocity. It is measured in N·s/m, or kg/s in SI base units.
+			Higher linear damping results in a more gradual reduction in linear velocity, creating smoother, gentler behavior as the joint returns to its limit, preventing oscillations or rapid movement. Lower values make the joint more elastic or bouncy.
 		</member>
 		<member name="params/impulse_clamp" type="float" setter="set_param" getter="get_param" default="0.0">
-			If above 0, this value is the maximum value for an impulse that this Joint3D produces.
+			If above 0, this value is the maximum value for an impulse that this Joint3D produces. It is measured in N·s, or kg·m/s in SI base units.
 		</member>
 	</members>
 	<constants>
 		<constant name="PARAM_BIAS" value="0" enum="Param">
 			The force with which the pinned objects stay in positional relation to each other. The higher, the stronger.
 		</constant>
 		<constant name="PARAM_DAMPING" value="1" enum="Param">
-			The force with which the pinned objects stay in velocity relation to each other. The higher, the stronger.
+			The amount of damping applied to linear velocity. It is measured in N·s/m, or kg/s in SI base units.
+			Higher linear damping results in a more gradual reduction in linear velocity, creating smoother, gentler behavior as the joint returns to its limit, preventing oscillations or rapid movement. Lower values make the joint more elastic or bouncy.
 		</constant>
 		<constant name="PARAM_IMPULSE_CLAMP" value="2" enum="Param">
-			If above 0, this value is the maximum value for an impulse that this Joint3D produces.
+			If above 0, this value is the maximum value for an impulse that this Joint3D produces. It is measured in N·s, or kg·m/s in SI base units.
 		</constant>
 	</constants>
 </class>

doc/classes/PinJoint3D.xml

@@ -27,40 +27,37 @@
 	</methods>
 	<members>
 		<member name="angular_limit/damping" type="float" setter="set_param" getter="get_param" default="0.0">
-			The amount of damping of the rotation when the limit is surpassed.
-			A lower damping value allows a rotation initiated by body A to travel to body B slower.
+			The amount of damping of the rotation when the limit is surpassed. A lower damping value allows a rotation initiated by body A to travel to body B slower. It is measured in N·m·s/rad, or kg·m²/s/rad in SI base units.
 		</member>
 		<member name="angular_limit/lower_angle" type="float" setter="set_param" getter="get_param" default="0.0">
 			The lower limit of rotation in the slider.
 		</member>
 		<member name="angular_limit/restitution" type="float" setter="set_param" getter="get_param" default="0.7">
-			The amount of restitution of the rotation when the limit is surpassed.
-			Does not affect damping.
+			The amount of restitution of the rotation when the limit is surpassed. Does not affect damping. Restitution is a dimensionless value.
 		</member>
 		<member name="angular_limit/softness" type="float" setter="set_param" getter="get_param" default="1.0">
-			A factor applied to the all rotation once the limit is surpassed.
-			Makes all rotation slower when between 0 and 1.
+			The stiffness factor applied to the all rotation once the limit is surpassed. Makes all rotation slower when between 0 and 1. Lower values are softer, while higher values are stiffer. It is measured in N·m/rad, or kg·m²/s²/rad in SI base units.
 		</member>
 		<member name="angular_limit/upper_angle" type="float" setter="set_param" getter="get_param" default="0.0">
 			The upper limit of rotation in the slider.
 		</member>
 		<member name="angular_motion/damping" type="float" setter="set_param" getter="get_param" default="1.0">
-			The amount of damping of the rotation in the limits.
+			The amount of damping of the rotation in the limits. It is measured in N·m·s/rad, or kg·m²/s/rad in SI base units.
 		</member>
 		<member name="angular_motion/restitution" type="float" setter="set_param" getter="get_param" default="0.7">
-			The amount of restitution of the rotation in the limits.
+			The amount of restitution of the rotation in the limits. Restitution is a dimensionless value.
 		</member>
 		<member name="angular_motion/softness" type="float" setter="set_param" getter="get_param" default="1.0">
-			A factor applied to the all rotation in the limits.
+			The stiffness factor applied to the all rotation in the limits. It is measured in N·m/rad, or kg·m²/s²/rad in SI base units.
 		</member>
 		<member name="angular_ortho/damping" type="float" setter="set_param" getter="get_param" default="1.0">
-			The amount of damping of the rotation across axes orthogonal to the slider.
+			The amount of damping of the rotation across axes orthogonal to the slider. It is measured in N·m·s/rad, or kg·m²/s/rad in SI base units.
 		</member>
 		<member name="angular_ortho/restitution" type="float" setter="set_param" getter="get_param" default="0.7">
-			The amount of restitution of the rotation across axes orthogonal to the slider.
+			The amount of restitution of the rotation across axes orthogonal to the slider. Restitution is a dimensionless value.
 		</member>
 		<member name="angular_ortho/softness" type="float" setter="set_param" getter="get_param" default="1.0">
-			A factor applied to the all rotation across axes orthogonal to the slider.
+			The stiffness factor applied to the all rotation across axes orthogonal to the slider. It is measured in N·m/rad, or kg·m²/s²/rad in SI base units.
 		</member>
 		<member name="linear_limit/damping" type="float" setter="set_param" getter="get_param" default="1.0">
 			The amount of damping that happens once the limit defined by [member linear_limit/lower_distance] and [member linear_limit/upper_distance] is surpassed.
@@ -69,31 +66,31 @@
 			The minimum difference between the pivot points on their X axis before damping happens.
 		</member>
 		<member name="linear_limit/restitution" type="float" setter="set_param" getter="get_param" default="0.7">
-			The amount of restitution once the limits are surpassed. The lower, the more velocity-energy gets lost.
+			The amount of restitution once the limits are surpassed. The lower, the more velocity-energy gets lost. Restitution is a dimensionless value.
 		</member>
 		<member name="linear_limit/softness" type="float" setter="set_param" getter="get_param" default="1.0">
-			A factor applied to the movement across the slider axis once the limits get surpassed. The lower, the slower the movement.
+			The stiffness factor applied to the movement across the slider axis once the limits get surpassed. The lower, the slower the movement. It is measured in N/m, or kg/s² in SI base units.
 		</member>
 		<member name="linear_limit/upper_distance" type="float" setter="set_param" getter="get_param" default="1.0">
 			The maximum difference between the pivot points on their X axis before damping happens.
 		</member>
 		<member name="linear_motion/damping" type="float" setter="set_param" getter="get_param" default="0.0">
-			The amount of damping inside the slider limits.
+			The amount of damping inside the slider limits. It is measured in N·s/m, or kg/s in SI base units.
 		</member>
 		<member name="linear_motion/restitution" type="float" setter="set_param" getter="get_param" default="0.7">
-			The amount of restitution inside the slider limits.
+			The amount of restitution inside the slider limits. Restitution is a dimensionless value.
 		</member>
 		<member name="linear_motion/softness" type="float" setter="set_param" getter="get_param" default="1.0">
-			A factor applied to the movement across the slider axis as long as the slider is in the limits. The lower, the slower the movement.
+			The stiffness factor applied to the movement across the slider axis as long as the slider is in the limits. The lower, the slower the movement. It is measured in N/m, or kg/s² in SI base units.
 		</member>
 		<member name="linear_ortho/damping" type="float" setter="set_param" getter="get_param" default="1.0">
-			The amount of damping when movement is across axes orthogonal to the slider.
+			The amount of damping when movement is across axes orthogonal to the slider. It is measured in N·s/m, or kg/s in SI base units.
 		</member>
 		<member name="linear_ortho/restitution" type="float" setter="set_param" getter="get_param" default="0.7">
-			The amount of restitution when movement is across axes orthogonal to the slider.
+			The amount of restitution when movement is across axes orthogonal to the slider. Restitution is a dimensionless value.
 		</member>
 		<member name="linear_ortho/softness" type="float" setter="set_param" getter="get_param" default="1.0">
-			A factor applied to the movement across axes orthogonal to the slider.
+			The stiffness factor applied to the movement across axes orthogonal to the slider. Lower values are softer, while higher values are stiffer. It is measured in N/m, or kg/s² in SI base units.
 		</member>
 	</members>
 	<constants>

doc/classes/SliderJoint3D.xml

@@ -120,8 +120,8 @@ void DampedSpringJoint2D::_bind_methods() {
 
 	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "length", PROPERTY_HINT_RANGE, "1,65535,1,exp,suffix:px"), "set_length", "get_length");
 	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "rest_length", PROPERTY_HINT_RANGE, "0,65535,1,exp,suffix:px"), "set_rest_length", "get_rest_length");
-	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "stiffness", PROPERTY_HINT_RANGE, "0.1,64,0.1,exp"), "set_stiffness", "get_stiffness");
-	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "damping", PROPERTY_HINT_RANGE, "0.01,16,0.01,exp"), "set_damping", "get_damping");
+	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "stiffness", PROPERTY_HINT_RANGE, U"0.1,64,0.1,exp,suffix:kg/s\u00B2"), "set_stiffness", "get_stiffness");
+	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "damping", PROPERTY_HINT_RANGE, "0.01,16,0.01,exp,suffix:kg/s"), "set_damping", "get_damping");
 }
 
 DampedSpringJoint2D::DampedSpringJoint2D() {

scene/2d/physics/joints/damped_spring_joint_2d.cpp

@@ -163,7 +163,7 @@ void PinJoint2D::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_angular_limit_enabled", "enabled"), &PinJoint2D::set_angular_limit_enabled);
 	ClassDB::bind_method(D_METHOD("is_angular_limit_enabled"), &PinJoint2D::is_angular_limit_enabled);
 
-	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "softness", PROPERTY_HINT_RANGE, "0.00,16,0.01,exp"), "set_softness", "get_softness");
+	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "softness", PROPERTY_HINT_RANGE, U"0.00,16,0.01,exp,suffix:s\u00B2/kg"), "set_softness", "get_softness");
 	ADD_GROUP("Angular Limit", "angular_limit_");
 	ADD_PROPERTY(PropertyInfo(Variant::BOOL, "angular_limit_enabled"), "set_angular_limit_enabled", "is_angular_limit_enabled");
 	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "angular_limit_lower", PROPERTY_HINT_RANGE, "-180,180,0.1,radians_as_degrees"), "set_angular_limit_lower", "get_angular_limit_lower");

scene/2d/physics/joints/pin_joint_2d.cpp

@@ -38,8 +38,8 @@ void ConeTwistJoint3D::_bind_methods() {
 	ADD_PROPERTYI(PropertyInfo(Variant::FLOAT, "twist_span", PROPERTY_HINT_RANGE, "-40000,40000,0.1,radians_as_degrees"), "set_param", "get_param", PARAM_TWIST_SPAN);
 
 	ADD_PROPERTYI(PropertyInfo(Variant::FLOAT, "bias", PROPERTY_HINT_RANGE, "0.01,16.0,0.01"), "set_param", "get_param", PARAM_BIAS);
-	ADD_PROPERTYI(PropertyInfo(Variant::FLOAT, "softness", PROPERTY_HINT_RANGE, "0.01,16.0,0.01"), "set_param", "get_param", PARAM_SOFTNESS);
-	ADD_PROPERTYI(PropertyInfo(Variant::FLOAT, "relaxation", PROPERTY_HINT_RANGE, "0.01,16.0,0.01"), "set_param", "get_param", PARAM_RELAXATION);
+	ADD_PROPERTYI(PropertyInfo(Variant::FLOAT, "softness", PROPERTY_HINT_RANGE, U"0.01,16.0,0.01,suffix:kg\u22C5m\u00B2/s\u00B2/rad (N\u22C5m/rad)"), "set_param", "get_param", PARAM_SOFTNESS);
+	ADD_PROPERTYI(PropertyInfo(Variant::FLOAT, "relaxation", PROPERTY_HINT_RANGE, U"0.01,16.0,0.01,suffix:rad\u22C5s/kg/m\u00B2 (rad/N/m/s) (inverse damping)"), "set_param", "get_param", PARAM_RELAXATION);
 
 	BIND_ENUM_CONSTANT(PARAM_SWING_SPAN);
 	BIND_ENUM_CONSTANT(PARAM_TWIST_SPAN);