virtualx-engine/doc/classes/SkeletonProfile.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>