Merge pull request #39126 from TwistedTwigleg/GSOC_2020_Working_Branch

Skeleton and Skeleton inspector low-level changes

1 files changed, 39 insertions, 0 deletions

diff --git a/doc/classes/Skeleton3D.xml b/doc/classes/Skeleton3D.xml
index 640cbe84f5..183fd5396f 100644
--- a/doc/classes/Skeleton3D.xml
+++ b/doc/classes/Skeleton3D.xml
@@ -31,6 +31,16 @@
 				[i]Deprecated soon.[/i]
 			</description>
 		</method>
+		<method name="bone_transform_to_world_transform">
+			<return type="Transform">
+			</return>
+			<argument index="0" name="bone_transform" type="Transform">
+			</argument>
+			<description>
+				Takes the given bone pose/transform and converts it to a world transform, relative to the [Skeleton3D] node.
+				This is useful for using the bone transform in calculations with transforms from [Node3D]-based nodes.
+			</description>
+		</method>
 		<method name="clear_bones">
 			<return type="void">
 			</return>
@@ -42,6 +52,7 @@
 			<return type="void">
 			</return>
 			<description>
+				Removes the global pose override on all bones in the skeleton.
 			</description>
 		</method>
 		<method name="find_bone" qualifiers="const">
@@ -136,12 +147,14 @@
 			<argument index="0" name="bone_idx" type="int">
 			</argument>
 			<description>
+				Returns whether the bone rest for the bone at [code]bone_idx[/code] is disabled.
 			</description>
 		</method>
 		<method name="localize_rests">
 			<return type="void">
 			</return>
 			<description>
+				Returns all bones in the skeleton to their rest poses.
 			</description>
 		</method>
 		<method name="physical_bones_add_collision_exception">
@@ -150,6 +163,8 @@
 			<argument index="0" name="exception" type="RID">
 			</argument>
 			<description>
+				Adds a collision exception to the physical bone.
+				Works just like the [RigidBody3D] node.
 			</description>
 		</method>
 		<method name="physical_bones_remove_collision_exception">
@@ -158,6 +173,8 @@
 			<argument index="0" name="exception" type="RID">
 			</argument>
 			<description>
+				Removes a collision exception to the physical bone.
+				Works just like the [RigidBody3D] node.
 			</description>
 		</method>
 		<method name="physical_bones_start_simulation">
@@ -166,12 +183,15 @@
 			<argument index="0" name="bones" type="StringName[]" default="[  ]">
 			</argument>
 			<description>
+				Tells the [PhysicalBone3D] nodes in the Skeleton to start simulating and reacting to the physics world.
+				Optionally, a list of bone names can be passed-in, allowing only the passed-in bones to be simulated.
 			</description>
 		</method>
 		<method name="physical_bones_stop_simulation">
 			<return type="void">
 			</return>
 			<description>
+				Tells the [PhysicalBone3D] nodes in the Skeleton to stop simulating.
 			</description>
 		</method>
 		<method name="register_skin">
@@ -180,6 +200,7 @@
 			<argument index="0" name="skin" type="Skin">
 			</argument>
 			<description>
+				Binds the given Skin to the Skeleton.
 			</description>
 		</method>
 		<method name="set_bone_custom_pose">
@@ -190,6 +211,8 @@
 			<argument index="1" name="custom_pose" type="Transform">
 			</argument>
 			<description>
+				Sets the custom pose transform, [code]custom_pose[/code], for the bone at [code]bone_idx[/code]. This pose is an addition to the bone rest pose.
+				[b]Note[/b]: The pose transform needs to be in bone space. Use [method world_transform_to_bone_transform] to convert a world transform, like one you can get from a [Node3D], to bone space.
 			</description>
 		</method>
 		<method name="set_bone_disable_rest">
@@ -200,6 +223,7 @@
 			<argument index="1" name="disable" type="bool">
 			</argument>
 			<description>
+				Disables the rest pose for the bone at [code]bone_idx[/code] if [code]true[/code], enables the bone rest if [code]false[/code].
 			</description>
 		</method>
 		<method name="set_bone_global_pose_override">
@@ -214,6 +238,9 @@
 			<argument index="3" name="persistent" type="bool" default="false">
 			</argument>
 			<description>
+				Sets the global pose transform, [code]pose[/code], for the bone at [code]bone_idx[/code].
+				[code]amount[/code] is the interpolation strengh that will be used when applying the pose, and [code]persistent[/code] determines if the applied pose will remain.
+				[b]Note[/b]: The pose transform needs to be in bone space. Use [method world_transform_to_bone_transform] to convert a world transform, like one you can get from a [Node3D], to bone space.
 			</description>
 		</method>
 		<method name="set_bone_parent">
@@ -237,6 +264,7 @@
 			</argument>
 			<description>
 				Returns the pose transform for bone [code]bone_idx[/code].
+				[b]Note[/b]: The pose transform needs to be in bone space. Use [method world_transform_to_bone_transform] to convert a world transform, like one you can get from a [Node3D], to bone space.
 			</description>
 		</method>
 		<method name="set_bone_rest">
@@ -267,6 +295,17 @@
 			<argument index="0" name="bone_idx" type="int">
 			</argument>
 			<description>
+				Unparents the bone at [code]bone_idx[/code] and sets its rest position to that of it's parent prior to being reset.
+			</description>
+		</method>
+		<method name="world_transform_to_bone_transform">
+			<return type="Transform">
+			</return>
+			<argument index="0" name="world_transform" type="Transform">
+			</argument>
+			<description>
+				Takes the given world transform, relative to the [Skeleton3D], and converts it to a bone pose/transform.
+				This is useful for using setting bone poses using transforms from [Node3D]-based nodes.
 			</description>
 		</method>
 	</methods>