Skip to content

Commit 5935356

Browse files
RepiteoRepiteo
committed
Merge pull request #100984 from TokageItLab/bone-constraint
Implement `BoneConstraint3D` with `CopyTransform`/`ConvertTransform`/`Aim` Modifiers
2 parents 7a3d2f6 + 4a2a956 commit 5935356

20 files changed

+3266
-0
lines changed

‎doc/classes/AimModifier3D.xml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="AimModifier3D" inherits="BoneConstraint3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
The [AimModifier3D] rotates a bone to look at a reference bone.
5+
</brief_description>
6+
<description>
7+
This is a simple version of [LookAtModifier3D] that only allows bone to the reference without advanced options such as angle limitation or time-based interpolation.
8+
The feature is simplified, but instead it is implemented with smooth tracking without euler, see [method set_use_euler].
9+
</description>
10+
<tutorials>
11+
</tutorials>
12+
<methods>
13+
<method name="get_forward_axis" qualifiers="const">
14+
<return type="int" enum="SkeletonModifier3D.BoneAxis" />
15+
<param index="0" name="index" type="int" />
16+
<description>
17+
Returns the forward axis of the bone.
18+
</description>
19+
</method>
20+
<method name="get_primary_rotation_axis" qualifiers="const">
21+
<return type="int" enum="Vector3.Axis" />
22+
<param index="0" name="index" type="int" />
23+
<description>
24+
Returns the axis of the first rotation. It is enabled only if [method is_using_euler] is [code]true[/code].
25+
</description>
26+
</method>
27+
<method name="is_using_euler" qualifiers="const">
28+
<return type="bool" />
29+
<param index="0" name="index" type="int" />
30+
<description>
31+
Returns [code]true[/code] if it provides rotation with using euler.
32+
</description>
33+
</method>
34+
<method name="is_using_secondary_rotation" qualifiers="const">
35+
<return type="bool" />
36+
<param index="0" name="index" type="int" />
37+
<description>
38+
Returns [code]true[/code] if it provides rotation by two axes. It is enabled only if [method is_using_euler] is [code]true[/code].
39+
</description>
40+
</method>
41+
<method name="set_forward_axis">
42+
<return type="void" />
43+
<param index="0" name="index" type="int" />
44+
<param index="1" name="axis" type="int" enum="SkeletonModifier3D.BoneAxis" />
45+
<description>
46+
Sets the forward axis of the bone.
47+
</description>
48+
</method>
49+
<method name="set_primary_rotation_axis">
50+
<return type="void" />
51+
<param index="0" name="index" type="int" />
52+
<param index="1" name="axis" type="int" enum="Vector3.Axis" />
53+
<description>
54+
Sets the axis of the first rotation. It is enabled only if [method is_using_euler] is [code]true[/code].
55+
</description>
56+
</method>
57+
<method name="set_use_euler">
58+
<return type="void" />
59+
<param index="0" name="index" type="int" />
60+
<param index="1" name="enabled" type="bool" />
61+
<description>
62+
If sets [param enabled] to [code]true[/code], it provides rotation with using euler.
63+
If sets [param enabled] to [code]false[/code], it provides rotation with using rotation by arc generated from the forward axis vector and the vector toward the reference.
64+
</description>
65+
</method>
66+
<method name="set_use_secondary_rotation">
67+
<return type="void" />
68+
<param index="0" name="index" type="int" />
69+
<param index="1" name="enabled" type="bool" />
70+
<description>
71+
If sets [param enabled] to [code]true[/code], it provides rotation by two axes. It is enabled only if [method is_using_euler] is [code]true[/code].
72+
</description>
73+
</method>
74+
</methods>
75+
<members>
76+
<member name="setting_count" type="int" setter="set_setting_count" getter="get_setting_count" default="0">
77+
The number of settings in the modifier.
78+
</member>
79+
</members>
80+
</class>

‎doc/classes/BoneConstraint3D.xml‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="BoneConstraint3D" inherits="SkeletonModifier3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
A node that may modify Skeleton3D's bone with associating the two bones.
5+
</brief_description>
6+
<description>
7+
Base class of [SkeletonModifier3D] that modifies the bone set in [method set_apply_bone] based on the transform of the bone retrieved by [method get_reference_bone].
8+
</description>
9+
<tutorials>
10+
</tutorials>
11+
<methods>
12+
<method name="clear_setting">
13+
<return type="void" />
14+
<description>
15+
Clear all settings.
16+
</description>
17+
</method>
18+
<method name="get_amount" qualifiers="const">
19+
<return type="float" />
20+
<param index="0" name="index" type="int" />
21+
<description>
22+
Returns the apply amount of the setting at [param index].
23+
</description>
24+
</method>
25+
<method name="get_apply_bone" qualifiers="const">
26+
<return type="int" />
27+
<param index="0" name="index" type="int" />
28+
<description>
29+
Returns the apply bone of the setting at [param index]. This bone will be modified.
30+
</description>
31+
</method>
32+
<method name="get_apply_bone_name" qualifiers="const">
33+
<return type="String" />
34+
<param index="0" name="index" type="int" />
35+
<description>
36+
Returns the apply bone name of the setting at [param index]. This bone will be modified.
37+
</description>
38+
</method>
39+
<method name="get_reference_bone" qualifiers="const">
40+
<return type="int" />
41+
<param index="0" name="index" type="int" />
42+
<description>
43+
Returns the reference bone of the setting at [param index].
44+
This bone will be only referenced and not modified by this modifier.
45+
</description>
46+
</method>
47+
<method name="get_reference_bone_name" qualifiers="const">
48+
<return type="String" />
49+
<param index="0" name="index" type="int" />
50+
<description>
51+
Returns the reference bone name of the setting at [param index].
52+
This bone will be only referenced and not modified by this modifier.
53+
</description>
54+
</method>
55+
<method name="get_setting_count" qualifiers="const">
56+
<return type="int" />
57+
<description>
58+
Returns the number of settings in the modifier.
59+
</description>
60+
</method>
61+
<method name="set_amount">
62+
<return type="void" />
63+
<param index="0" name="index" type="int" />
64+
<param index="1" name="amount" type="float" />
65+
<description>
66+
Sets the apply amount of the setting at [param index] to [param amount].
67+
</description>
68+
</method>
69+
<method name="set_apply_bone">
70+
<return type="void" />
71+
<param index="0" name="index" type="int" />
72+
<param index="1" name="bone" type="int" />
73+
<description>
74+
Sets the apply bone of the setting at [param index] to [param bone]. This bone will be modified.
75+
</description>
76+
</method>
77+
<method name="set_apply_bone_name">
78+
<return type="void" />
79+
<param index="0" name="index" type="int" />
80+
<param index="1" name="bone_name" type="String" />
81+
<description>
82+
Sets the apply bone of the setting at [param index] to [param bone_name]. This bone will be modified.
83+
</description>
84+
</method>
85+
<method name="set_reference_bone">
86+
<return type="void" />
87+
<param index="0" name="index" type="int" />
88+
<param index="1" name="bone" type="int" />
89+
<description>
90+
Sets the reference bone of the setting at [param index] to [param bone].
91+
This bone will be only referenced and not modified by this modifier.
92+
</description>
93+
</method>
94+
<method name="set_reference_bone_name">
95+
<return type="void" />
96+
<param index="0" name="index" type="int" />
97+
<param index="1" name="bone_name" type="String" />
98+
<description>
99+
Sets the reference bone of the setting at [param index] to [param bone_name].
100+
This bone will be only referenced and not modified by this modifier.
101+
</description>
102+
</method>
103+
<method name="set_setting_count">
104+
<return type="void" />
105+
<param index="0" name="count" type="int" />
106+
<description>
107+
Sets the number of settings in the modifier.
108+
</description>
109+
</method>
110+
</methods>
111+
</class>

‎doc/classes/ConvertTransformModifier3D.xml‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
<?xml version="1.0" encoding="UTF-8" ?>
2+
<class name="ConvertTransformModifier3D" inherits="BoneConstraint3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
3+
<brief_description>
4+
A [SkeletonModifier3D] that apply transform to the bone which converted from reference.
5+
</brief_description>
6+
<description>
7+
Apply the copied transform of the bone set by [method BoneConstraint3D.set_reference_bone] to the bone set by [method BoneConstraint3D.set_apply_bone] about the specific axis with remapping it with some options.
8+
There are 4 ways to apply the transform, depending on the combination of [method set_relative] and [method set_additive].
9+
[b]Relative + Additive:[/b]
10+
- Extract reference pose relative to the rest and add it to the apply bone's pose.
11+
[b]Relative + Not Additive:[/b]
12+
- Extract reference pose relative to the rest and add it to the apply bone's rest.
13+
[b]Not Relative + Additive:[/b]
14+
- Extract reference pose absolutely and add it to the apply bone's pose.
15+
[b]Not Relative + Not Additive:[/b]
16+
- Extract reference pose absolutely and the apply bone's pose is replaced with it.
17+
</description>
18+
<tutorials>
19+
</tutorials>
20+
<methods>
21+
<method name="get_apply_axis" qualifiers="const">
22+
<return type="int" enum="Vector3.Axis" />
23+
<param index="0" name="index" type="int" />
24+
<description>
25+
Returns the axis of the remapping destination transform.
26+
</description>
27+
</method>
28+
<method name="get_apply_range_max" qualifiers="const">
29+
<return type="float" />
30+
<param index="0" name="index" type="int" />
31+
<description>
32+
Returns the maximum value of the remapping destination range.
33+
</description>
34+
</method>
35+
<method name="get_apply_range_min" qualifiers="const">
36+
<return type="float" />
37+
<param index="0" name="index" type="int" />
38+
<description>
39+
Returns the minimum value of the remapping destination range.
40+
</description>
41+
</method>
42+
<method name="get_apply_transform_mode" qualifiers="const">
43+
<return type="int" enum="ConvertTransformModifier3D.TransformMode" />
44+
<param index="0" name="index" type="int" />
45+
<description>
46+
Returns the operation of the remapping destination transform.
47+
</description>
48+
</method>
49+
<method name="get_reference_axis" qualifiers="const">
50+
<return type="int" enum="Vector3.Axis" />
51+
<param index="0" name="index" type="int" />
52+
<description>
53+
Returns the axis of the remapping source transform.
54+
</description>
55+
</method>
56+
<method name="get_reference_range_max" qualifiers="const">
57+
<return type="float" />
58+
<param index="0" name="index" type="int" />
59+
<description>
60+
Returns the maximum value of the remapping source range.
61+
</description>
62+
</method>
63+
<method name="get_reference_range_min" qualifiers="const">
64+
<return type="float" />
65+
<param index="0" name="index" type="int" />
66+
<description>
67+
Returns the minimum value of the remapping source range.
68+
</description>
69+
</method>
70+
<method name="get_reference_transform_mode" qualifiers="const">
71+
<return type="int" enum="ConvertTransformModifier3D.TransformMode" />
72+
<param index="0" name="index" type="int" />
73+
<description>
74+
Returns the operation of the remapping source transform.
75+
</description>
76+
</method>
77+
<method name="is_additive" qualifiers="const">
78+
<return type="bool" />
79+
<param index="0" name="index" type="int" />
80+
<description>
81+
Returns [code]true[/code] if the additive option is enabled in the setting at [param index].
82+
</description>
83+
</method>
84+
<method name="is_relative" qualifiers="const">
85+
<return type="bool" />
86+
<param index="0" name="index" type="int" />
87+
<description>
88+
Returns [code]true[/code] if the relative option is enabled in the setting at [param index].
89+
</description>
90+
</method>
91+
<method name="set_additive">
92+
<return type="void" />
93+
<param index="0" name="index" type="int" />
94+
<param index="1" name="enabled" type="bool" />
95+
<description>
96+
Sets additive option in the setting at [param index] to [param enabled]. This mainly affects the process of applying transform to the [method BoneConstraint3D.set_apply_bone].
97+
If sets [param enabled] to [code]true[/code], the processed transform is added to the pose of the current apply bone.
98+
If sets [param enabled] to [code]false[/code], the pose of the current apply bone is replaced with the processed transform. However, if set [method set_relative] to [code]true[/code], the transform is relative to rest.
99+
</description>
100+
</method>
101+
<method name="set_apply_axis">
102+
<return type="void" />
103+
<param index="0" name="index" type="int" />
104+
<param index="1" name="axis" type="int" enum="Vector3.Axis" />
105+
<description>
106+
Sets the axis of the remapping destination transform.
107+
</description>
108+
</method>
109+
<method name="set_apply_range_max">
110+
<return type="void" />
111+
<param index="0" name="index" type="int" />
112+
<param index="1" name="range_max" type="float" />
113+
<description>
114+
Sets the maximum value of the remapping destination range.
115+
</description>
116+
</method>
117+
<method name="set_apply_range_min">
118+
<return type="void" />
119+
<param index="0" name="index" type="int" />
120+
<param index="1" name="range_min" type="float" />
121+
<description>
122+
Sets the minimum value of the remapping destination range.
123+
</description>
124+
</method>
125+
<method name="set_apply_transform_mode">
126+
<return type="void" />
127+
<param index="0" name="index" type="int" />
128+
<param index="1" name="transform_mode" type="int" enum="ConvertTransformModifier3D.TransformMode" />
129+
<description>
130+
Sets the operation of the remapping destination transform.
131+
</description>
132+
</method>
133+
<method name="set_reference_axis">
134+
<return type="void" />
135+
<param index="0" name="index" type="int" />
136+
<param index="1" name="axis" type="int" enum="Vector3.Axis" />
137+
<description>
138+
Sets the axis of the remapping source transform.
139+
</description>
140+
</method>
141+
<method name="set_reference_range_max">
142+
<return type="void" />
143+
<param index="0" name="index" type="int" />
144+
<param index="1" name="range_max" type="float" />
145+
<description>
146+
Sets the maximum value of the remapping source range.
147+
</description>
148+
</method>
149+
<method name="set_reference_range_min">
150+
<return type="void" />
151+
<param index="0" name="index" type="int" />
152+
<param index="1" name="range_min" type="float" />
153+
<description>
154+
Sets the minimum value of the remapping source range.
155+
</description>
156+
</method>
157+
<method name="set_reference_transform_mode">
158+
<return type="void" />
159+
<param index="0" name="index" type="int" />
160+
<param index="1" name="transform_mode" type="int" enum="ConvertTransformModifier3D.TransformMode" />
161+
<description>
162+
Sets the operation of the remapping source transform.
163+
</description>
164+
</method>
165+
<method name="set_relative">
166+
<return type="void" />
167+
<param index="0" name="index" type="int" />
168+
<param index="1" name="enabled" type="bool" />
169+
<description>
170+
Sets relative option in the setting at [param index] to [param enabled].
171+
If sets [param enabled] to [code]true[/code], the extracted and applying transform is relative to the rest.
172+
If sets [param enabled] to [code]false[/code], the extracted transform is absolute.
173+
</description>
174+
</method>
175+
</methods>
176+
<members>
177+
<member name="setting_count" type="int" setter="set_setting_count" getter="get_setting_count" default="0">
178+
The number of settings in the modifier.
179+
</member>
180+
</members>
181+
<constants>
182+
<constant name="TRANSFORM_MODE_POSITION" value="0" enum="TransformMode">
183+
Convert with position. Transfer the difference.
184+
</constant>
185+
<constant name="TRANSFORM_MODE_ROTATION" value="1" enum="TransformMode">
186+
Convert with rotation. The angle is the roll for the specified axis.
187+
</constant>
188+
<constant name="TRANSFORM_MODE_SCALE" value="2" enum="TransformMode">
189+
Convert with scale. Transfers the ratio, not the difference.
190+
</constant>
191+
</constants>
192+
</class>

0 commit comments

Comments
 (0)