Skip to content

Commit 250ed2f

Browse files
TokageItLabTokageItLab
committed
Add ManyBoneIK3D
1 parent 0870525 commit 250ed2f

Some content is hidden

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

65 files changed

+6034
-161
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 result twist around forward vector will always be [code]0[/code].
9+
[b]Note:[/b] When the target is close to the root, it can cause unnatural movements, including joint flips and oscillations.
10+
</description>
11+
<tutorials>
12+
</tutorials>
13+
</class>

‎doc/classes/ChainIK3D.xml‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="ChainIK3D" inherits="ManyBoneIK3D" 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 arbitrary number of bones.
5+
</brief_description>
6+
<description>
7+
Base class of [SkeletonModifier3D] that automatically generates a joint list from the bones between root bone and 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 end bone's tail direction 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's 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 the 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] 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 the tail.
123+
The extended tail config is allocated to the last element in the joint list.
124+
In other words, if you set [param enabled] is [code]false[/code], the config of last element in the joint list has no effect in the simulated result.
125+
</description>
126+
</method>
127+
<method name="set_root_bone">
128+
<return type="void" />
129+
<param index="0" name="index" type="int" />
130+
<param index="1" name="bone" type="int" />
131+
<description>
132+
Sets the root bone index of the bone chain.
133+
</description>
134+
</method>
135+
<method name="set_root_bone_name">
136+
<return type="void" />
137+
<param index="0" name="index" type="int" />
138+
<param index="1" name="bone_name" type="String" />
139+
<description>
140+
Sets the root bone name of the bone chain.
141+
</description>
142+
</method>
143+
</methods>
144+
</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 [ManyBoneIK3D] 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 result twist around forward vector will always be [code]0[/code].
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/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 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 bone direction (in general parent to child) as +Y axis and [method get_joint_limitation_right_axis_vector] as +X axis.
45+
If +X and +Y axes are not orthogonal, +X axis is implicitly modified to make orthogonal.
46+
Also, if [method get_joint_limitation_right_axis_vector] length 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 bone direction (in general parent to child) as +Y axis and [method get_joint_limitation_right_axis_vector] as +X axis.
108+
If +X and +Y axes are not orthogonal, +X axis is implicitly modified to make orthogonal.
109+
Also, if [method get_joint_limitation_right_axis_vector] length 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+
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 end bone and target. If the distance is below this value, the IK solver stops 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 the 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 movements. It is particularly suited for biological animations.
8+
The result twist around forward vector will always be [code]0[/code].
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>

‎doc/classes/JointLimitation3D.xml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="JointLimitation3D" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
A base class of the limitation that interacts with [ChainIK3D].
5+
</brief_description>
6+
<description>
7+
Limitation is attached to each joint and limits the rotation of the bone.
8+
</description>
9+
<tutorials>
10+
</tutorials>
11+
</class>

‎doc/classes/JointLimitationCone3D.xml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="JointLimitationCone3D" inherits="JointLimitation3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
A cone shape limitation that interacts with [ChainIK3D].
5+
</brief_description>
6+
<description>
7+
A cone shape limitation that interacts with [ChainIK3D].
8+
</description>
9+
<tutorials>
10+
</tutorials>
11+
<members>
12+
<member name="radius_range" type="float" setter="set_radius_range" getter="get_radius_range" default="0.25">
13+
Sets the size of the hole made by the cone.
14+
[code]0[/code] is no hole, [code]0.5[/code] makes a hemisphere and [code]1.0[/code] makes a sphere (no limitation).
15+
</member>
16+
</members>
17+
</class>

0 commit comments

Comments
 (0)