From 8eb5443d0a5eeeb0ccdf82fad4936e73fe315b13 Mon Sep 17 00:00:00 2001
From: "Silc Lizard (Tokage) Renew"
 <61938263+TokageItLab@users.noreply.github.com>
Date: Fri, 17 Jan 2025 06:59:54 +0900
Subject: [PATCH] Clarify SpringBone's gravity unit and improve documentation

---
 doc/classes/SpringBoneSimulator3D.xml | 4 ++--
 scene/3d/spring_bone_simulator_3d.cpp | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/classes/SpringBoneSimulator3D.xml b/doc/classes/SpringBoneSimulator3D.xml
index 6c639105d9e..173a0515bca 100644
--- a/doc/classes/SpringBoneSimulator3D.xml
+++ b/doc/classes/SpringBoneSimulator3D.xml
@@ -459,7 +459,7 @@
 			<param index="0" name="index" type="int" />
 			<param index="1" name="gravity" type="float" />
 			<description>
-				Sets the gravity amount of the bone chain.
+				Sets the gravity amount of the bone chain. This value is not an acceleration, but a constant velocity of movement in [method set_gravity_direction].
 				If [param gravity] is not [code]0[/code], the modified pose will not return to the original pose since it is always affected by gravity.
 				The value is scaled by [method set_gravity_damping_curve] and cached in each joint setting in the joint list.
 			</description>
@@ -477,7 +477,7 @@
 			<param index="0" name="index" type="int" />
 			<param index="1" name="gravity_direction" type="Vector3" />
 			<description>
-				Sets the gravity direction of the bone chain.
+				Sets the gravity direction of the bone chain. This value is internally normalized and then multiplied by [method set_gravity].
 				The value is cached in each joint setting in the joint list.
 			</description>
 		</method>
diff --git a/scene/3d/spring_bone_simulator_3d.cpp b/scene/3d/spring_bone_simulator_3d.cpp
index db2755288bf..9d7af1e35ee 100644
--- a/scene/3d/spring_bone_simulator_3d.cpp
+++ b/scene/3d/spring_bone_simulator_3d.cpp
@@ -307,7 +307,7 @@ void SpringBoneSimulator3D::_get_property_list(List<PropertyInfo> *p_list) const
 		p_list->push_back(PropertyInfo(Variant::OBJECT, path + "stiffness/damping_curve", PROPERTY_HINT_RESOURCE_TYPE, "Curve"));
 		p_list->push_back(PropertyInfo(Variant::FLOAT, path + "drag/value", PROPERTY_HINT_RANGE, "0,1,0.01,or_greater"));
 		p_list->push_back(PropertyInfo(Variant::OBJECT, path + "drag/damping_curve", PROPERTY_HINT_RESOURCE_TYPE, "Curve"));
-		p_list->push_back(PropertyInfo(Variant::FLOAT, path + "gravity/value", PROPERTY_HINT_RANGE, "0,1,0.01,or_greater"));
+		p_list->push_back(PropertyInfo(Variant::FLOAT, path + "gravity/value", PROPERTY_HINT_RANGE, "0,1,0.01,or_greater,or_less,suffix:m/s"));
 		p_list->push_back(PropertyInfo(Variant::OBJECT, path + "gravity/damping_curve", PROPERTY_HINT_RESOURCE_TYPE, "Curve"));
 		p_list->push_back(PropertyInfo(Variant::VECTOR3, path + "gravity/direction"));
 		p_list->push_back(PropertyInfo(Variant::INT, path + "joint_count", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_DEFAULT | PROPERTY_USAGE_ARRAY, "Joints," + path + "joints/,static,const"));
@@ -319,7 +319,7 @@ void SpringBoneSimulator3D::_get_property_list(List<PropertyInfo> *p_list) const
 			p_list->push_back(PropertyInfo(Variant::FLOAT, joint_path + "radius", PROPERTY_HINT_RANGE, "0,1,0.001,or_greater,suffix:m"));
 			p_list->push_back(PropertyInfo(Variant::FLOAT, joint_path + "stiffness", PROPERTY_HINT_RANGE, "0,4,0.01,or_greater"));
 			p_list->push_back(PropertyInfo(Variant::FLOAT, joint_path + "drag", PROPERTY_HINT_RANGE, "0,1,0.01,or_greater"));
-			p_list->push_back(PropertyInfo(Variant::FLOAT, joint_path + "gravity", PROPERTY_HINT_RANGE, "0,1,0.01,or_greater"));
+			p_list->push_back(PropertyInfo(Variant::FLOAT, joint_path + "gravity", PROPERTY_HINT_RANGE, "0,1,0.01,or_greater,or_less,suffix:m/s"));
 			p_list->push_back(PropertyInfo(Variant::VECTOR3, joint_path + "gravity_direction"));
 		}
 		p_list->push_back(PropertyInfo(Variant::BOOL, path + "enable_all_child_collisions"));