Work in progress
Godot documentation is being updated to reflect the latest changes in version
4.0. Some documentation pages may
still state outdated information. This banner will tell you if you're reading one of such pages.
The contents of this page are up to date. If you can still find outdated information, please open an issue.
Retargeting 3D Skeletons¶
Options for Retargeting¶
When you select the Skeleton3D node in the advanced scene import menu, a menu will appear
on the right-hand side containing the "Retarget" section. The Retarget section has a single
With the Skeleton node selected, first set up a new BoneMap and SkeletonProfile. Godot has a preset called SkeletonProfileHumanoid for humanoid models. This tutorial proceeds with the assumption that you are using SkeletonProfileHumanoid.
If you need a profile for a model such as a beast or creature, you can export a SkeletonProfile from SkeletonEditor with some information converted from Skeleton.
When you use SkeletonProfileHumanoid, auto-mapping will be performed when the SkeletonProfile is set. If the auto-mapping does not work well, you can map bones manually.
Any missing, duplicate or incorrect parent-child relationship mappings will be indicated by a magenta / red button (depending on the editor setting). It does not block the import process, but it warns that animations may not be shared correctly.
The auto-mapping uses pattern matching for the bone names. So we recommend to use common English names for bones.
After you set up the
bone_map, several options are available in the sections below.
If you import resources as an AnimationLibrary that will be shared, we recommend to enable these options. However, if you import resources as scenes, these should be disabled in some cases. For example, if you import a character with animated accessories, these options may cause the accessories to not animate.
Except Bone Transform¶
Removes any tracks except the bone Transform track from the animations.
Removes Position tracks other than
defined in SkeletonProfile from the animations. In SkeletonProfileHumanoid,
this means that to remove Position tracks other than "Root" and "Hips".
Since Godot 4.0+, animations include Bone Rest in the Transform value. If you disable this option,
the animation may change the body shape unpredictably.
Removes unmapped bone Transform tracks from the animations.
Rename the mapped bones.
Makes Skeleton a unique node with the name specified in the
This allows the animation track paths to be unified independent of the scene hierarchy.
Reference poses defined in SkeletonProfileHumanoid have the following rules:
The humanoid is T-pose
The humanoid is facing +Z in the Right-Handed Y-UP Coordinate System
The humanoid should not have a Transform as Node
Directs the +Y axis from the parent joint to the child joint
+X rotation bends the joint like a muscle contracting
These rules are convenient definitions for blend animation and Inverse Kinematics (IK). If your model does not match this definition, you need to fix it with these options.
Apply Node Transform¶
If the asset is not exported correctly for sharing, the imported Skeleton may have a Transform as a Node. For example, a glTF exported from Blender with no "Apply Transform" executed is one such case. It looks like the model matches the definition, but the internal Transforms are different from the definition. This option fixes such models by applying Transforms on import.
If the imported scene contains objects other than Skeletons, this option may have a negative effect.
Normalize Position Tracks¶
Position track is used mostly for model movement, but sharing the moving animation
between models with different heights may cause the appearance of slipping
due to the difference in stride length. This option normalizes the Position track values
based on the
scale_base_bone height. The
scale_base_bone height is stored
in the Skeleton as the
motion_scale, and the normalized Position track values is
multiplied by that value on playback. If this option is disabled, the Position tracks
is not normalized and the Skeleton's
motion_scale is always imported as
scale_base_bone is "Hips", therefore the Hips' height is used as the
Unifies the models' Bone Rests by overwriting it to match the reference poses defined in the SkeletonProfile.
This is the most important option for sharing animations in Godot 4.0+, but be aware that this option can produce horrible results if the original Bone Rest set externally is important. If you want to share animations with keeping the original Bone Rest, consider to use the Realtime Retarget Module.
Attempts to make the model's silhouette match that of the reference poses defined in the SkeletonProfile, such as T-Pose. This cannot fix silhouettes which are too different, and it may not work for fixing bone roll.
With SkeletonProfileHumanoid, this option does not need to be enabled for T-pose models,
but should be enabled for A-pose models. However in that case, the fixed foot results
may be bad depending on the heel height of the model, so it may be necessary to add
the SkeletonProfile bone names you do not want fixed in the
filter array, as in the below example.
Also, for models with bent knees or feet, it may be necessary to adjust the
For that, you can use