godot/doc/classes/SkeletonProfile.xml
2024-03-30 20:57:55 +01:00

214 lines
9.6 KiB
XML

<?xml version="1.0" encoding="UTF-8" ?>
<class name="SkeletonProfile" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Base class for a profile of a virtual skeleton used as a target for retargeting.
</brief_description>
<description>
This resource is used in [EditorScenePostImport]. Some parameters are referring to bones in [Skeleton3D], [Skin], [Animation], and some other nodes are rewritten based on the parameters of [SkeletonProfile].
[b]Note:[/b] These parameters need to be set only when creating a custom profile. In [SkeletonProfileHumanoid], they are defined internally as read-only values.
</description>
<tutorials>
<link title="Retargeting 3D Skeletons">$DOCS_URL/tutorials/assets_pipeline/retargeting_3d_skeletons.html</link>
</tutorials>
<methods>
<method name="find_bone" qualifiers="const">
<return type="int" />
<param index="0" name="bone_name" type="StringName" />
<description>
Returns the bone index that matches [param bone_name] as its name.
</description>
</method>
<method name="get_bone_name" qualifiers="const">
<return type="StringName" />
<param index="0" name="bone_idx" type="int" />
<description>
Returns the name of the bone at [param bone_idx] that will be the key name in the [BoneMap].
In the retargeting process, the returned bone name is the bone name of the target skeleton.
</description>
</method>
<method name="get_bone_parent" qualifiers="const">
<return type="StringName" />
<param index="0" name="bone_idx" type="int" />
<description>
Returns the name of the bone which is the parent to the bone at [param bone_idx]. The result is empty if the bone has no parent.
</description>
</method>
<method name="get_bone_tail" qualifiers="const">
<return type="StringName" />
<param index="0" name="bone_idx" type="int" />
<description>
Returns the name of the bone which is the tail of the bone at [param bone_idx].
</description>
</method>
<method name="get_group" qualifiers="const">
<return type="StringName" />
<param index="0" name="bone_idx" type="int" />
<description>
Returns the group of the bone at [param bone_idx].
</description>
</method>
<method name="get_group_name" qualifiers="const">
<return type="StringName" />
<param index="0" name="group_idx" type="int" />
<description>
Returns the name of the group at [param group_idx] that will be the drawing group in the [BoneMap] editor.
</description>
</method>
<method name="get_handle_offset" qualifiers="const">
<return type="Vector2" />
<param index="0" name="bone_idx" type="int" />
<description>
Returns the offset of the bone at [param bone_idx] that will be the button position in the [BoneMap] editor.
This is the offset with origin at the top left corner of the square.
</description>
</method>
<method name="get_reference_pose" qualifiers="const">
<return type="Transform3D" />
<param index="0" name="bone_idx" type="int" />
<description>
Returns the reference pose transform for bone [param bone_idx].
</description>
</method>
<method name="get_tail_direction" qualifiers="const">
<return type="int" enum="SkeletonProfile.TailDirection" />
<param index="0" name="bone_idx" type="int" />
<description>
Returns the tail direction of the bone at [param bone_idx].
</description>
</method>
<method name="get_texture" qualifiers="const">
<return type="Texture2D" />
<param index="0" name="group_idx" type="int" />
<description>
Returns the texture of the group at [param group_idx] that will be the drawing group background image in the [BoneMap] editor.
</description>
</method>
<method name="is_required" qualifiers="const">
<return type="bool" />
<param index="0" name="bone_idx" type="int" />
<description>
Returns whether the bone at [param bone_idx] is required for retargeting.
This value is used by the bone map editor. If this method returns [code]true[/code], and no bone is assigned, the handle color will be red on the bone map editor.
</description>
</method>
<method name="set_bone_name">
<return type="void" />
<param index="0" name="bone_idx" type="int" />
<param index="1" name="bone_name" type="StringName" />
<description>
Sets the name of the bone at [param bone_idx] that will be the key name in the [BoneMap].
In the retargeting process, the setting bone name is the bone name of the target skeleton.
</description>
</method>
<method name="set_bone_parent">
<return type="void" />
<param index="0" name="bone_idx" type="int" />
<param index="1" name="bone_parent" type="StringName" />
<description>
Sets the bone with name [param bone_parent] as the parent of the bone at [param bone_idx]. If an empty string is passed, then the bone has no parent.
</description>
</method>
<method name="set_bone_tail">
<return type="void" />
<param index="0" name="bone_idx" type="int" />
<param index="1" name="bone_tail" type="StringName" />
<description>
Sets the bone with name [param bone_tail] as the tail of the bone at [param bone_idx].
</description>
</method>
<method name="set_group">
<return type="void" />
<param index="0" name="bone_idx" type="int" />
<param index="1" name="group" type="StringName" />
<description>
Sets the group of the bone at [param bone_idx].
</description>
</method>
<method name="set_group_name">
<return type="void" />
<param index="0" name="group_idx" type="int" />
<param index="1" name="group_name" type="StringName" />
<description>
Sets the name of the group at [param group_idx] that will be the drawing group in the [BoneMap] editor.
</description>
</method>
<method name="set_handle_offset">
<return type="void" />
<param index="0" name="bone_idx" type="int" />
<param index="1" name="handle_offset" type="Vector2" />
<description>
Sets the offset of the bone at [param bone_idx] that will be the button position in the [BoneMap] editor.
This is the offset with origin at the top left corner of the square.
</description>
</method>
<method name="set_reference_pose">
<return type="void" />
<param index="0" name="bone_idx" type="int" />
<param index="1" name="bone_name" type="Transform3D" />
<description>
Sets the reference pose transform for bone [param bone_idx].
</description>
</method>
<method name="set_required">
<return type="void" />
<param index="0" name="bone_idx" type="int" />
<param index="1" name="required" type="bool" />
<description>
Sets the required status for bone [param bone_idx] to [param required].
</description>
</method>
<method name="set_tail_direction">
<return type="void" />
<param index="0" name="bone_idx" type="int" />
<param index="1" name="tail_direction" type="int" enum="SkeletonProfile.TailDirection" />
<description>
Sets the tail direction of the bone at [param bone_idx].
[b]Note:[/b] This only specifies the method of calculation. The actual coordinates required should be stored in an external skeleton, so the calculation itself needs to be done externally.
</description>
</method>
<method name="set_texture">
<return type="void" />
<param index="0" name="group_idx" type="int" />
<param index="1" name="texture" type="Texture2D" />
<description>
Sets the texture of the group at [param group_idx] that will be the drawing group background image in the [BoneMap] editor.
</description>
</method>
</methods>
<members>
<member name="bone_size" type="int" setter="set_bone_size" getter="get_bone_size" default="0">
The amount of bones in retargeting section's [BoneMap] editor. For example, [SkeletonProfileHumanoid] has 56 bones.
The size of elements in [BoneMap] updates when changing this property in it's assigned [SkeletonProfile].
</member>
<member name="group_size" type="int" setter="set_group_size" getter="get_group_size" default="0">
The amount of groups of bones in retargeting section's [BoneMap] editor. For example, [SkeletonProfileHumanoid] has 4 groups.
This property exists to separate the bone list into several sections in the editor.
</member>
<member name="root_bone" type="StringName" setter="set_root_bone" getter="get_root_bone" default="&amp;&quot;&quot;">
A bone name that will be used as the root bone in [AnimationTree]. This should be the bone of the parent of hips that exists at the world origin.
</member>
<member name="scale_base_bone" type="StringName" setter="set_scale_base_bone" getter="get_scale_base_bone" default="&amp;&quot;&quot;">
A bone name which will use model's height as the coefficient for normalization. For example, [SkeletonProfileHumanoid] defines it as [code]Hips[/code].
</member>
</members>
<signals>
<signal name="profile_updated">
<description>
This signal is emitted when change the value in profile. This is used to update key name in the [BoneMap] and to redraw the [BoneMap] editor.
[b]Note:[/b] This signal is not connected directly to editor to simplify the reference, instead it is passed on to editor through the [BoneMap].
</description>
</signal>
</signals>
<constants>
<constant name="TAIL_DIRECTION_AVERAGE_CHILDREN" value="0" enum="TailDirection">
Direction to the average coordinates of bone children.
</constant>
<constant name="TAIL_DIRECTION_SPECIFIC_CHILD" value="1" enum="TailDirection">
Direction to the coordinates of specified bone child.
</constant>
<constant name="TAIL_DIRECTION_END" value="2" enum="TailDirection">
Direction is not calculated.
</constant>
</constants>
</class>