Skip to content

Commit 3a0315a

Browse files
TokageItLabTokageItLab
committed
Add IKModifier3D
1 parent 0870525 commit 3a0315a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

69 files changed

+6065
-180
lines changed

‎doc/classes/CCDIK3D.xml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="CCDIK3D" inherits="IterateIK3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
Rotation based cyclic coordinate descent inverse kinematics solver.
5+
</brief_description>
6+
<description>
7+
[CCDIK3D] is rotation based IK, enabling fast and effective tracking even with large joint rotations. It's especially suitable for chains with limitations, providing smoother and more stable target tracking compared to [FABRIK3D].
8+
The resulting twist around the forward vector will always be kept from the previous pose.
9+
[b]Note:[/b] When the target is close to the root, it can cause unnatural movement, including joint flips and oscillations.
10+
</description>
11+
<tutorials>
12+
</tutorials>
13+
</class>

‎doc/classes/ChainIK3D.xml‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="ChainIK3D" inherits="IKModifier3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
A [SkeletonModifier3D] to apply inverse kinematics to bone chains containing an arbitrary number of bones.
5+
</brief_description>
6+
<description>
7+
Base class of [SkeletonModifier3D] that automatically generates a joint list from the bones between the root bone and the end bone.
8+
</description>
9+
<tutorials>
10+
</tutorials>
11+
<methods>
12+
<method name="get_end_bone" qualifiers="const">
13+
<return type="int" />
14+
<param index="0" name="index" type="int" />
15+
<description>
16+
Returns the end bone index of the bone chain.
17+
</description>
18+
</method>
19+
<method name="get_end_bone_direction" qualifiers="const">
20+
<return type="int" enum="SkeletonModifier3D.BoneDirection" />
21+
<param index="0" name="index" type="int" />
22+
<description>
23+
Returns the tail direction of the end bone of the bone chain when [method is_end_bone_extended] is [code]true[/code].
24+
</description>
25+
</method>
26+
<method name="get_end_bone_length" qualifiers="const">
27+
<return type="float" />
28+
<param index="0" name="index" type="int" />
29+
<description>
30+
Returns the end bone tail length of the bone chain when [method is_end_bone_extended] is [code]true[/code].
31+
</description>
32+
</method>
33+
<method name="get_end_bone_name" qualifiers="const">
34+
<return type="String" />
35+
<param index="0" name="index" type="int" />
36+
<description>
37+
Returns the end bone name of the bone chain.
38+
</description>
39+
</method>
40+
<method name="get_joint_bone" qualifiers="const">
41+
<return type="int" />
42+
<param index="0" name="index" type="int" />
43+
<param index="1" name="joint" type="int" />
44+
<description>
45+
Returns the bone index at [param joint] in the bone chain's joint list.
46+
</description>
47+
</method>
48+
<method name="get_joint_bone_name" qualifiers="const">
49+
<return type="String" />
50+
<param index="0" name="index" type="int" />
51+
<param index="1" name="joint" type="int" />
52+
<description>
53+
Returns the bone name at [param joint] in the bone chain's joint list.
54+
</description>
55+
</method>
56+
<method name="get_joint_count" qualifiers="const">
57+
<return type="int" />
58+
<param index="0" name="index" type="int" />
59+
<description>
60+
Returns the joint count of the bone chain's joint list.
61+
</description>
62+
</method>
63+
<method name="get_root_bone" qualifiers="const">
64+
<return type="int" />
65+
<param index="0" name="index" type="int" />
66+
<description>
67+
Returns the root bone index of the bone chain.
68+
</description>
69+
</method>
70+
<method name="get_root_bone_name" qualifiers="const">
71+
<return type="String" />
72+
<param index="0" name="index" type="int" />
73+
<description>
74+
Returns the root bone name of the bone chain.
75+
</description>
76+
</method>
77+
<method name="is_end_bone_extended" qualifiers="const">
78+
<return type="bool" />
79+
<param index="0" name="index" type="int" />
80+
<description>
81+
Returns [code]true[/code] if the end bone is extended to have a tail.
82+
</description>
83+
</method>
84+
<method name="set_end_bone">
85+
<return type="void" />
86+
<param index="0" name="index" type="int" />
87+
<param index="1" name="bone" type="int" />
88+
<description>
89+
Sets the end bone index of the bone chain.
90+
</description>
91+
</method>
92+
<method name="set_end_bone_direction">
93+
<return type="void" />
94+
<param index="0" name="index" type="int" />
95+
<param index="1" name="bone_direction" type="int" enum="SkeletonModifier3D.BoneDirection" />
96+
<description>
97+
Sets the end bone tail direction of the bone chain when [method is_end_bone_extended] is [code]true[/code].
98+
</description>
99+
</method>
100+
<method name="set_end_bone_length">
101+
<return type="void" />
102+
<param index="0" name="index" type="int" />
103+
<param index="1" name="length" type="float" />
104+
<description>
105+
Sets the end bone tail length of the bone chain when [method is_end_bone_extended] is [code]true[/code].
106+
</description>
107+
</method>
108+
<method name="set_end_bone_name">
109+
<return type="void" />
110+
<param index="0" name="index" type="int" />
111+
<param index="1" name="bone_name" type="String" />
112+
<description>
113+
Sets the end bone name of the bone chain.
114+
[b]Note:[/b] The end bone must be the root bone or a child of the root bone. If they are the same, the tail must be extended by [method set_extend_end_bone] to modify the bone.
115+
</description>
116+
</method>
117+
<method name="set_extend_end_bone">
118+
<return type="void" />
119+
<param index="0" name="index" type="int" />
120+
<param index="1" name="enabled" type="bool" />
121+
<description>
122+
If [param enabled] is [code]true[/code], the end bone is extended to have a tail.
123+
The extended tail config is allocated to the last element in the joint list. In other words, if you set [param enabled] to [code]false[/code], the config of the last element in the joint list has no effect in the simulated result. </description>
124+
</method>
125+
<method name="set_root_bone">
126+
<return type="void" />
127+
<param index="0" name="index" type="int" />
128+
<param index="1" name="bone" type="int" />
129+
<description>
130+
Sets the root bone index of the bone chain.
131+
</description>
132+
</method>
133+
<method name="set_root_bone_name">
134+
<return type="void" />
135+
<param index="0" name="index" type="int" />
136+
<param index="1" name="bone_name" type="String" />
137+
<description>
138+
Sets the root bone name of the bone chain.
139+
</description>
140+
</method>
141+
</methods>
142+
</class>

‎doc/classes/EditorSettings.xml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -456,6 +456,9 @@
456456
<member name="editors/3d_gizmos/gizmo_colors/gridmap_grid" type="Color" setter="" getter="">
457457
The 3D editor gizmo color for the [GridMap] grid.
458458
</member>
459+
<member name="editors/3d_gizmos/gizmo_colors/ik_chain" type="Color" setter="" getter="">
460+
The 3D editor gizmo color for the [IKModifier3D] guides.
461+
</member>
459462
<member name="editors/3d_gizmos/gizmo_colors/instantiated" type="Color" setter="" getter="">
460463
The color override to use for 3D editor gizmos if the [Node3D] in question is part of an instantiated scene file (from the perspective of the current scene).
461464
</member>

‎doc/classes/FABRIK3D.xml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="FABRIK3D" inherits="IterateIK3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
Position based forward and backward reaching inverse kinematics solver.
5+
</brief_description>
6+
<description>
7+
[FABRIK3D] is position based IK, allowing precise and accurate tracking of targets. It's ideal for simple chains without limitations.
8+
The resulting twist around the forward vector will always be kept from the previous pose.
9+
[b]Note:[/b] When the target is close to the root, it tends to produce zig-zag patterns, resulting in unnatural visual movement.
10+
</description>
11+
<tutorials>
12+
</tutorials>
13+
</class>

‎doc/classes/IKModifier3D.xml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="IKModifier3D" inherits="SkeletonModifier3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
A node for inverse kinematics which may modify more than one bone.
5+
</brief_description>
6+
<description>
7+
Base class of [SkeletonModifier3D]s that has some joint lists and applies inverse kinematics. This class has some structs, enums, and helper methods which are useful to solve inverse kinematics.
8+
[b]Note:[/b] The IK classes that extend this handle rotation only, with bone lengths cached. It means that a position movement between processed chains can cause unintended movement.
9+
</description>
10+
<tutorials>
11+
</tutorials>
12+
<methods>
13+
<method name="clear_settings">
14+
<return type="void" />
15+
<description>
16+
Clears all settings.
17+
</description>
18+
</method>
19+
<method name="get_setting_count" qualifiers="const">
20+
<return type="int" />
21+
<description>
22+
Returns the number of settings.
23+
</description>
24+
</method>
25+
<method name="reset">
26+
<return type="void" />
27+
<description>
28+
Resets a state with respect to the current bone pose.
29+
</description>
30+
</method>
31+
<method name="set_setting_count">
32+
<return type="void" />
33+
<param index="0" name="count" type="int" />
34+
<description>
35+
Sets the number of settings.
36+
</description>
37+
</method>
38+
</methods>
39+
</class>

‎doc/classes/IterateIK3D.xml‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="IterateIK3D" inherits="ChainIK3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
A [SkeletonModifier3D] to approach the goal by repeating small rotations.
5+
</brief_description>
6+
<description>
7+
Base class of [SkeletonModifier3D] to approach the goal by repeating small rotations.
8+
Each bone chain (setting) has one effector, which is processed in order of the setting list. You can set some limitations for each joint.
9+
</description>
10+
<tutorials>
11+
</tutorials>
12+
<methods>
13+
<method name="get_joint_limitation" qualifiers="const">
14+
<return type="JointLimitation3D" />
15+
<param index="0" name="index" type="int" />
16+
<param index="1" name="joint" type="int" />
17+
<description>
18+
Returns the joint limitation at [param joint] in the bone chain's joint list.
19+
</description>
20+
</method>
21+
<method name="get_joint_limitation_right_axis" qualifiers="const">
22+
<return type="int" enum="SkeletonModifier3D.SecondaryDirection" />
23+
<param index="0" name="index" type="int" />
24+
<param index="1" name="joint" type="int" />
25+
<description>
26+
Returns the joint limitation right axis at [param joint] in the bone chain's joint list.
27+
</description>
28+
</method>
29+
<method name="get_joint_limitation_right_axis_vector" qualifiers="const">
30+
<return type="Vector3" />
31+
<param index="0" name="index" type="int" />
32+
<param index="1" name="joint" type="int" />
33+
<description>
34+
Returns the joint limitation right axis vector at [param joint] in the bone chain's joint list.
35+
If [method get_joint_limitation_right_axis] is [constant SkeletonModifier3D.SECONDARY_DIRECTION_NONE], this method returns [code]Vector3(0, 0, 0)[/code].
36+
</description>
37+
</method>
38+
<method name="get_joint_limitation_rotation_offset" qualifiers="const">
39+
<return type="Quaternion" />
40+
<param index="0" name="index" type="int" />
41+
<param index="1" name="joint" type="int" />
42+
<description>
43+
Returns the joint limitation rotation offset at [param joint] in the bone chain's joint list.
44+
Rotation is done in the local space which is constructed by the bone direction (in general parent to child) as the +Y axis and [method get_joint_limitation_right_axis_vector] as the +X axis.
45+
If the +X and +Y axes are not orthogonal, the +X axis is implicitly modified to make it orthogonal.
46+
Also, if the length of [method get_joint_limitation_right_axis_vector] is zero, the space is created by rotating the bone rest using the shortest arc that rotates the +Y axis of the bone rest to match the bone direction.
47+
</description>
48+
</method>
49+
<method name="get_joint_rotation_axis" qualifiers="const">
50+
<return type="int" enum="SkeletonModifier3D.RotationAxis" />
51+
<param index="0" name="index" type="int" />
52+
<param index="1" name="joint" type="int" />
53+
<description>
54+
Returns the rotation axis at [param joint] in the bone chain's joint list.
55+
</description>
56+
</method>
57+
<method name="get_joint_rotation_axis_vector" qualifiers="const">
58+
<return type="Vector3" />
59+
<param index="0" name="index" type="int" />
60+
<param index="1" name="joint" type="int" />
61+
<description>
62+
Returns the rotation axis vector for the specified joint in the bone chain. This vector represents the axis around which the joint can rotate. It is determined based on the rotation axis set for the joint.
63+
If [method get_joint_rotation_axis] is [constant SkeletonModifier3D.ROTATION_AXIS_ALL], this method returns [code]Vector3(0, 0, 0)[/code].
64+
</description>
65+
</method>
66+
<method name="get_target_node" qualifiers="const">
67+
<return type="NodePath" />
68+
<param index="0" name="index" type="int" />
69+
<description>
70+
Returns the target node that the end bone is trying to reach.
71+
</description>
72+
</method>
73+
<method name="set_joint_limitation">
74+
<return type="void" />
75+
<param index="0" name="index" type="int" />
76+
<param index="1" name="joint" type="int" />
77+
<param index="2" name="limitation" type="JointLimitation3D" />
78+
<description>
79+
Sets the joint limitation at [param joint] in the bone chain's joint list.
80+
</description>
81+
</method>
82+
<method name="set_joint_limitation_right_axis">
83+
<return type="void" />
84+
<param index="0" name="index" type="int" />
85+
<param index="1" name="joint" type="int" />
86+
<param index="2" name="direction" type="int" enum="SkeletonModifier3D.SecondaryDirection" />
87+
<description>
88+
Sets the joint limitation right axis at [param joint] in the bone chain's joint list.
89+
</description>
90+
</method>
91+
<method name="set_joint_limitation_right_axis_vector">
92+
<return type="void" />
93+
<param index="0" name="index" type="int" />
94+
<param index="1" name="joint" type="int" />
95+
<param index="2" name="vector" type="Vector3" />
96+
<description>
97+
Sets the optional joint limitation right axis vector at [param joint] in the bone chain's joint list.
98+
</description>
99+
</method>
100+
<method name="set_joint_limitation_rotation_offset">
101+
<return type="void" />
102+
<param index="0" name="index" type="int" />
103+
<param index="1" name="joint" type="int" />
104+
<param index="2" name="offset" type="Quaternion" />
105+
<description>
106+
Sets the joint limitation rotation offset at [param joint] in the bone chain's joint list.
107+
Rotation is done in the local space which is constructed by the bone direction (in general parent to child) as the +Y axis and [method get_joint_limitation_right_axis_vector] as the +X axis.
108+
If the +X and +Y axes are not orthogonal, the +X axis is implicitly modified to make it orthogonal.
109+
Also, if the length of [method get_joint_limitation_right_axis_vector] is zero, the space is created by rotating the bone rest using the shortest arc that rotates the +Y axis of the bone rest to match the bone direction.
110+
</description>
111+
</method>
112+
<method name="set_joint_rotation_axis">
113+
<return type="void" />
114+
<param index="0" name="index" type="int" />
115+
<param index="1" name="joint" type="int" />
116+
<param index="2" name="axis" type="int" enum="SkeletonModifier3D.RotationAxis" />
117+
<description>
118+
Sets the rotation axis at [param joint] in the bone chain's joint list.
119+
The axes are based on the [method Skeleton3D.get_bone_rest]'s space, if [param axis] is [constant SkeletonModifier3D.ROTATION_AXIS_CUSTOM], you can specify any axis.
120+
[b]Note:[/b] The rotation axis and the forward vector shouldn't be colinear to avoid unintended rotation since [ChainIK3D] does not factor in twisting forces.
121+
</description>
122+
</method>
123+
<method name="set_joint_rotation_axis_vector">
124+
<return type="void" />
125+
<param index="0" name="index" type="int" />
126+
<param index="1" name="joint" type="int" />
127+
<param index="2" name="axis_vector" type="Vector3" />
128+
<description>
129+
Sets the rotation axis vector for the specified joint in the bone chain.
130+
This vector is normalized by an internal process and represents the axis around which the bone chain can rotate.
131+
If the vector length is [code]0[/code], it is considered synonymous with [constant SkeletonModifier3D.ROTATION_AXIS_ALL].
132+
</description>
133+
</method>
134+
<method name="set_target_node">
135+
<return type="void" />
136+
<param index="0" name="index" type="int" />
137+
<param index="1" name="target_node" type="NodePath" />
138+
<description>
139+
Sets the target node that the end bone is trying to reach.
140+
</description>
141+
</method>
142+
</methods>
143+
<members>
144+
<member name="angular_delta_limit" type="float" setter="set_angular_delta_limit" getter="get_angular_delta_limit" default="0.034906585">
145+
The maximum amount each bone can rotate in a single iteration.
146+
[b]Note:[/b] This limitation is applied during each iteration. For example, if [member max_iterations] is [code]4[/code] and [member angular_delta_limit] is [code]5[/code] degrees, the maximum rotation possible in a single frame is [code]20[/code] degrees.
147+
</member>
148+
<member name="max_iterations" type="int" setter="set_max_iterations" getter="get_max_iterations" default="4">
149+
The number of iteration loops used by the IK solver to produce more accurate results.
150+
</member>
151+
<member name="min_distance" type="float" setter="set_min_distance" getter="get_min_distance" default="0.001">
152+
The minimum distance between the end bone and the target. If the distance is below this value, the IK solver stops any further iterations.
153+
</member>
154+
<member name="setting_count" type="int" setter="set_setting_count" getter="get_setting_count" default="0">
155+
The number of settings.
156+
</member>
157+
</members>
158+
</class>

‎doc/classes/JacobianIK3D.xml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="JacobianIK3D" inherits="IterateIK3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
Pseudo inverse Jacobian matrix based inverse kinematics solver.
5+
</brief_description>
6+
<description>
7+
[JacobianIK3D] calculates rotations for all joints simultaneously, producing natural and smooth movement. It is particularly suited for biological animations.
8+
The resulting twist around the forward vector will always be kept from the previous pose.
9+
[b]Note:[/b] It converges more slowly than other IK solvers, leading to gentler and less immediate tracking of targets.
10+
</description>
11+
<tutorials>
12+
</tutorials>
13+
</class>

0 commit comments

Comments
 (0)