Skip to content

Commit 860ddab

Browse files
TokageItLabTokageItLab
committed
Add BoneTwistDisperser3D to propagate IK target's twist
1 parent 7ed0b61 commit 860ddab

File tree

6 files changed

+1141
-0
lines changed

6 files changed

+1141
-0
lines changed

‎doc/classes/BoneTwistDisperser3D.xml‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="BoneTwistDisperser3D" inherits="SkeletonModifier3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
A node that propagates and disperses the child bone's twist to the parent bones.
5+
</brief_description>
6+
<description>
7+
This [BoneTwistDisperser3D] allows for smooth twist interpolation between multiple bones by dispersing the end bone's twist to the parents. This only changes the twist without changing the global position of each joint.
8+
This is useful for smoothly twisting bones in combination with [CopyTransformModifier3D] and IK.
9+
[b]Note:[/b] If there is a twist greater than 180 degrees, flipping occurs. This is similar to [ConvertTransformModifier3D].
10+
</description>
11+
<tutorials>
12+
</tutorials>
13+
<methods>
14+
<method name="clear_settings">
15+
<return type="void" />
16+
<description>
17+
Clears all settings.
18+
</description>
19+
</method>
20+
<method name="get_disperse_mode" qualifiers="const">
21+
<return type="int" enum="BoneTwistDisperser3D.DisperseMode" />
22+
<param index="0" name="index" type="int" />
23+
<description>
24+
Returns whether to use automatic weight assignment or to allow manual assignment.
25+
</description>
26+
</method>
27+
<method name="get_end_bone" qualifiers="const">
28+
<return type="int" />
29+
<param index="0" name="index" type="int" />
30+
<description>
31+
Returns the end bone index of the bone chain.
32+
</description>
33+
</method>
34+
<method name="get_end_bone_direction" qualifiers="const">
35+
<return type="int" enum="SkeletonModifier3D.BoneDirection" />
36+
<param index="0" name="index" type="int" />
37+
<description>
38+
Returns the tail direction of the end bone of the bone chain when [method is_end_bone_extended] is [code]true[/code].
39+
</description>
40+
</method>
41+
<method name="get_end_bone_name" qualifiers="const">
42+
<return type="String" />
43+
<param index="0" name="index" type="int" />
44+
<description>
45+
Returns the end bone name of the bone chain.
46+
</description>
47+
</method>
48+
<method name="get_joint_bone" qualifiers="const">
49+
<return type="int" />
50+
<param index="0" name="index" type="int" />
51+
<param index="1" name="joint" type="int" />
52+
<description>
53+
Returns the bone index at [param joint] in the bone chain's joint list.
54+
</description>
55+
</method>
56+
<method name="get_joint_bone_name" qualifiers="const">
57+
<return type="String" />
58+
<param index="0" name="index" type="int" />
59+
<param index="1" name="joint" type="int" />
60+
<description>
61+
Returns the bone name at [param joint] in the bone chain's joint list.
62+
</description>
63+
</method>
64+
<method name="get_joint_count" qualifiers="const">
65+
<return type="int" />
66+
<param index="0" name="index" type="int" />
67+
<description>
68+
Returns the joint count of the bone chain's joint list.
69+
</description>
70+
</method>
71+
<method name="get_joint_weight" qualifiers="const">
72+
<return type="float" />
73+
<param index="0" name="index" type="int" />
74+
<param index="1" name="joint" type="int" />
75+
<description>
76+
Returns the joint weight of the bone chain's joint list when [method get_disperse_mode] is [constant DISPERSE_MODE_CUSTOM].
77+
</description>
78+
</method>
79+
<method name="get_reference_bone" qualifiers="const">
80+
<return type="int" />
81+
<param index="0" name="index" type="int" />
82+
<description>
83+
Returns the reference bone of the setting at [param index].
84+
This bone will only be referenced and the global pose is not modified.
85+
This bone is either the end of the chain or its parent, depending on [method is_end_bone_extended].
86+
</description>
87+
</method>
88+
<method name="get_reference_bone_name" qualifiers="const">
89+
<return type="String" />
90+
<param index="0" name="index" type="int" />
91+
<description>
92+
Returns the reference bone name of the setting at [param index].
93+
This bone will only be referenced and the global pose is not modified.
94+
This bone is either the end of the chain or its parent, depending on [method is_end_bone_extended].
95+
</description>
96+
</method>
97+
<method name="get_root_bone" qualifiers="const">
98+
<return type="int" />
99+
<param index="0" name="index" type="int" />
100+
<description>
101+
Returns the root bone index of the bone chain.
102+
</description>
103+
</method>
104+
<method name="get_root_bone_name" qualifiers="const">
105+
<return type="String" />
106+
<param index="0" name="index" type="int" />
107+
<description>
108+
Returns the root bone name of the bone chain.
109+
</description>
110+
</method>
111+
<method name="get_twist_from" qualifiers="const">
112+
<return type="Quaternion" />
113+
<param index="0" name="index" type="int" />
114+
<description>
115+
Returns the rotation to an arbitrary state before twisting for the current bone pose to extract the twist when [method is_twist_from_rest] is [code]false[/code].
116+
</description>
117+
</method>
118+
<method name="is_end_bone_extended" qualifiers="const">
119+
<return type="bool" />
120+
<param index="0" name="index" type="int" />
121+
<description>
122+
Returns [code]true[/code] if the end bone is extended to have a tail.
123+
</description>
124+
</method>
125+
<method name="is_twist_from_rest" qualifiers="const">
126+
<return type="bool" />
127+
<param index="0" name="index" type="int" />
128+
<description>
129+
Returns [code]true[/code] if extracting the twist amount from the difference between the bone rest and the current bone pose.
130+
</description>
131+
</method>
132+
<method name="set_disperse_mode">
133+
<return type="void" />
134+
<param index="0" name="index" type="int" />
135+
<param index="1" name="disperse_mode" type="int" enum="BoneTwistDisperser3D.DisperseMode" />
136+
<description>
137+
Sets whether to use automatic weight assignment or to allow manual assignment.
138+
</description>
139+
</method>
140+
<method name="set_end_bone">
141+
<return type="void" />
142+
<param index="0" name="index" type="int" />
143+
<param index="1" name="bone" type="int" />
144+
<description>
145+
Sets the end bone index of the bone chain.
146+
</description>
147+
</method>
148+
<method name="set_end_bone_direction">
149+
<return type="void" />
150+
<param index="0" name="index" type="int" />
151+
<param index="1" name="bone_direction" type="int" enum="SkeletonModifier3D.BoneDirection" />
152+
<description>
153+
Sets the end bone tail direction of the bone chain when [method is_end_bone_extended] is [code]true[/code].
154+
</description>
155+
</method>
156+
<method name="set_end_bone_name">
157+
<return type="void" />
158+
<param index="0" name="index" type="int" />
159+
<param index="1" name="bone_name" type="String" />
160+
<description>
161+
Sets the end bone name of the bone chain.
162+
[b]Note:[/b] The end bone must be a child of the root bone.
163+
</description>
164+
</method>
165+
<method name="set_extend_end_bone">
166+
<return type="void" />
167+
<param index="0" name="index" type="int" />
168+
<param index="1" name="enabled" type="bool" />
169+
<description>
170+
If [param enabled] is [code]true[/code], the end bone is extended to have a tail.
171+
If [param enabled] is [code]false[/code], [method get_reference_bone] becomes a parent of the end bone and it uses the vector to the end bone as a twist axis.
172+
</description>
173+
</method>
174+
<method name="set_joint_weight">
175+
<return type="void" />
176+
<param index="0" name="index" type="int" />
177+
<param index="1" name="joint" type="int" />
178+
<param index="2" name="weight" type="float" />
179+
<description>
180+
Sets the joint weight of the bone chain's joint list when [method get_disperse_mode] is [constant DISPERSE_MODE_CUSTOM].
181+
</description>
182+
</method>
183+
<method name="set_root_bone">
184+
<return type="void" />
185+
<param index="0" name="index" type="int" />
186+
<param index="1" name="bone" type="int" />
187+
<description>
188+
Sets the root bone index of the bone chain.
189+
</description>
190+
</method>
191+
<method name="set_root_bone_name">
192+
<return type="void" />
193+
<param index="0" name="index" type="int" />
194+
<param index="1" name="bone_name" type="String" />
195+
<description>
196+
Sets the root bone name of the bone chain.
197+
</description>
198+
</method>
199+
<method name="set_twist_from">
200+
<return type="void" />
201+
<param index="0" name="index" type="int" />
202+
<param index="1" name="from" type="Quaternion" />
203+
<description>
204+
Sets the rotation to an arbitrary state before twisting for the current bone pose to extract the twist when [method is_twist_from_rest] is [code]false[/code].
205+
In other words, by calling [method set_twist_from] by [signal SkeletonModifier3D.modification_processed] of a specific [SkeletonModifier3D], you can extract only the twists generated by modifiers processed after that but before this [BoneTwistDisperser3D].
206+
</description>
207+
</method>
208+
<method name="set_twist_from_rest">
209+
<return type="void" />
210+
<param index="0" name="index" type="int" />
211+
<param index="1" name="enabled" type="bool" />
212+
<description>
213+
If [param enabled] is [code]true[/code], it extracts the twist amount from the difference between the bone rest and the current bone pose.
214+
If [param enabled] is [code]false[/code], it extracts the twist amount from the difference between [method get_twist_from] and the current bone pose. See also [method set_twist_from].
215+
</description>
216+
</method>
217+
</methods>
218+
<members>
219+
<member name="mutable_bone_axes" type="bool" setter="set_mutable_bone_axes" getter="are_bone_axes_mutable" default="true">
220+
If [code]true[/code], the solver retrieves the bone axis from the bone pose every frame.
221+
If [code]false[/code], the solver retrieves the bone axis from the bone rest and caches it.
222+
</member>
223+
<member name="setting_count" type="int" setter="set_setting_count" getter="get_setting_count" default="0">
224+
The number of settings.
225+
</member>
226+
</members>
227+
<constants>
228+
<constant name="DISPERSE_MODE_EVEN" value="0" enum="DisperseMode">
229+
Assigns weights evenly to all joints.
230+
</constant>
231+
<constant name="DISPERSE_MODE_WEIGHTED" value="1" enum="DisperseMode">
232+
Assign weights based on the length of the bones between chain segments.
233+
For example, if two bones with a length of [code]1.0[/code] exist between three joints, weights are assigned to each joint from root to end at ratios of [code]0.5[/code], [code]1.0[/code], [code]0.5[/code].
234+
</constant>
235+
<constant name="DISPERSE_MODE_CUSTOM" value="2" enum="DisperseMode">
236+
You can assign arbitrary weights to the joint list. They will be normalized in the result. See also [method set_joint_weight].
237+
The custom weight of the reference bone affects the remaining weights, but since the global pose of the reference bone remains unchanged, it does not affect the reference bone itself.
238+
When [method is_end_bone_extended] is [code]false[/code], a child of the reference bone exists solely to determine the twist axis, so its custom weight has absolutely no effect at all.
239+
</constant>
240+
</constants>
241+
</class>

‎doc/classes/ConvertTransformModifier3D.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
[b]Not Relative + Not Additive:[/b]
1616
- Extract reference pose absolutely and the apply bone's pose is replaced with it.
1717
[b]Note:[/b] Relative option is available only in the case [method BoneConstraint3D.get_reference_type] is [constant BoneConstraint3D.REFERENCE_TYPE_BONE]. See also [enum BoneConstraint3D.ReferenceType].
18+
[b]Note:[/b] If there is a rotation greater than 180 degrees with constrained axes, flipping may occurs.
1819
</description>
1920
<tutorials>
2021
</tutorials>

‎editor/icons/BoneTwistDisperser3D.svg‎

Lines changed: 1 addition & 0 deletions
Loading

0 commit comments

Comments
 (0)