From 42c88d99aeb6277fcf8db0f469960b6b33e90b2c Mon Sep 17 00:00:00 2001
From: smix8 <>
Date: Thu, 15 Apr 2021 23:00:40 +0200
Subject: [PATCH] Add SkeletonIK function documentation

Add SkeletonIK function documentation

(cherry picked from commit 84e603ec7e271d711342c8280ec2e98ba3c8056f)
---
 doc/classes/SkeletonIK.xml | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/classes/SkeletonIK.xml b/doc/classes/SkeletonIK.xml
index d8c083cdaa1..7935675273f 100644
--- a/doc/classes/SkeletonIK.xml
+++ b/doc/classes/SkeletonIK.xml
@@ -1,8 +1,29 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="SkeletonIK" inherits="Node" version="3.3">
 	<brief_description>
+		SkeletonIK is used to place the end bone of a [Skeleton] bone chain at a certain point in 3D by rotating all bones in the chain accordingly.
 	</brief_description>
 	<description>
+		SkeletonIK is used to place the end bone of a [Skeleton] bone chain at a certain point in 3D by rotating all bones in the chain accordingly. A typical scenario for IK in games is to place a characters feet on the ground or a characters hands on a currently hold object. SkeletonIK uses FabrikInverseKinematic internally to solve the bone chain and applies the results to the [Skeleton] [code]bones_global_pose_override[/code] property for all affected bones in the chain. If fully applied this overwrites any bone transform from [Animation]s or bone custom poses set by users. The applied amount can be controlled with the [code]interpolation[/code] property.
+		[codeblock]
+		# Apply IK effect automatically on every new frame (not the current)
+		skeleton_ik_node.start()
+
+		# Apply IK effect only on the current frame
+		skeleton_ik_node.start(true)
+
+		# Stop IK effect and reset bones_global_pose_override on Skeleton
+		skeleton_ik_node.stop()
+
+		# Apply full IK effect
+		skeleton_ik_node.set_interpolation(1.0)
+
+		# Apply half IK effect
+		skeleton_ik_node.set_interpolation(0.5)
+
+		# Apply zero IK effect (a value at or below 0.01 also removes bones_global_pose_override on Skeleton)
+		skeleton_ik_node.set_interpolation(0.0)
+		[/codeblock]
 	</description>
 	<tutorials>
 		<link title="3D Inverse Kinematics Demo">https://godotengine.org/asset-library/asset/523</link>
@@ -12,12 +33,14 @@
 			<return type="Skeleton">
 			</return>
 			<description>
+				Returns the parent [Skeleton] Node that was present when SkeletonIK entered the [SceneTree]. Returns null if the parent node was not a [Skeleton] Node when SkeletonIK entered the [SceneTree].
 			</description>
 		</method>
 		<method name="is_running">
 			<return type="bool">
 			</return>
 			<description>
+				Returns [code]true[/code] if SkeletonIK is applying IK effects on continues frames to the [Skeleton] bones. Returns [code]false[/code] if SkeletonIK is stopped or [method start] was used with the [code]one_time[/code] parameter set to [code]true[/code].
 			</description>
 		</method>
 		<method name="start">
@@ -26,35 +49,47 @@
 			<argument index="0" name="one_time" type="bool" default="false">
 			</argument>
 			<description>
+				Starts applying IK effects on each frame to the [Skeleton] bones but will only take effect starting on the next frame. If [code]one_time[/code] is [code]true[/code], this will take effect immediately but also reset on the next frame.
 			</description>
 		</method>
 		<method name="stop">
 			<return type="void">
 			</return>
 			<description>
+				Stops applying IK effects on each frame to the [Skeleton] bones and also calls [method Skeleton.clear_bones_global_pose_override] to remove existing overrides on all bones.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="interpolation" type="float" setter="set_interpolation" getter="get_interpolation" default="1.0">
+			Interpolation value for how much the IK results are applied to the current skeleton bone chain. A value of [code]1.0[/code] will overwrite all skeleton bone transforms completely while a value of [code]0.0[/code] will visually disable the SkeletonIK. A value at or below [code]0.01[/code] also calls [method Skeleton.clear_bones_global_pose_override].
 		</member>
 		<member name="magnet" type="Vector3" setter="set_magnet_position" getter="get_magnet_position" default="Vector3( 0, 0, 0 )">
+			Secondary target position (first is [member target] property or [member target_node]) for the IK chain. Use magnet position (pole target) to control the bending of the IK chain. Only works if the bone chain has more than 2 bones. The middle chain bone position will be linearly interpolated with the magnet position.
 		</member>
 		<member name="max_iterations" type="int" setter="set_max_iterations" getter="get_max_iterations" default="10">
+			Number of iteration loops used by the IK solver to produce more accurate (and elegant) bone chain results.
 		</member>
 		<member name="min_distance" type="float" setter="set_min_distance" getter="get_min_distance" default="0.01">
+			The minimum distance between bone and goal target. If the distance is below this value, the IK solver stops further iterations.
 		</member>
 		<member name="override_tip_basis" type="bool" setter="set_override_tip_basis" getter="is_override_tip_basis" default="true">
+			If [code]true[/code] overwrites the rotation of the tip bone with the rotation of the [member target] (or [member target_node] if defined).
 		</member>
 		<member name="root_bone" type="String" setter="set_root_bone" getter="get_root_bone" default="&quot;&quot;">
+			The name of the current root bone, the first bone in the IK chain.
 		</member>
 		<member name="target" type="Transform" setter="set_target_transform" getter="get_target_transform" default="Transform( 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0 )">
+			First target of the IK chain where the tip bone is placed and, if [member override_tip_basis] is [code]true[/code], how the tip bone is rotated. If a [member target_node] path is available the nodes transform is used instead and this property is ignored.
 		</member>
 		<member name="target_node" type="NodePath" setter="set_target_node" getter="get_target_node" default="NodePath(&quot;&quot;)">
+			Target node [NodePath] for the IK chain. If available, the node's current [Transform] is used instead of the [member target] property.
 		</member>
 		<member name="tip_bone" type="String" setter="set_tip_bone" getter="get_tip_bone" default="&quot;&quot;">
+			The name of the current tip bone, the last bone in the IK chain placed at the [member target] transform (or [member target_node] if defined).
 		</member>
 		<member name="use_magnet" type="bool" setter="set_use_magnet" getter="is_using_magnet" default="false">
+			If [code]true[/code], instructs the IK solver to consider the secondary magnet target (pole target) when calculating the bone chain. Use the magnet position (pole target) to control the bending of the IK chain.
 		</member>
 	</members>
 	<constants>