Up to date

This page is up to date for Godot 4.0. If you still find outdated information, please open an issue.

Retargeting 3D Skeletons

To share animations among multiple Skeletons

Godot has Position/Rotation/Scale 3D tracks (which this document calls "Transform" tracks) with Nodepaths to bones for Skeleton bone animation. This means you can't share animations between multiple Skeletons just by using the same bone names.

Godot allows each bone to have a parent-child relationship and can have rotation and scale as well as position, which means that bones that share a name can still have different Transform values.

The Skeleton stores the Transform values necessary for the default pose as Bone Rest. If Bone Pose is equal to Bone Rest, it means that the Skeleton is in the default pose.

Note

Godot 3.x and Godot 4.0+ have different Bone Pose behaviors. In Godot 3.x, Bone Pose is relative to Bone Rest, but in Godot 4.0+, it includes Bone Rest. See this article.

Skeletal models have different Bone Rests depending on the environment from which they were exported. For example, the bones of a glTF model output from Blender have "Edit Bone Orientation" as the Bone Rest rotation. However, there are skeletal models without any Bone Rest rotations, such as the glTF model output from Maya.

To share animations in Godot, it is necessary to match Bone Rests as well as Bone Names to remove unwanted tracks in some cases. In Godot 4.0+, you can do that using the scene importer.

Options for Retargeting

Bone Map

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 property bone_map.

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.

Note

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.

Note

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.

Remove Tracks

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.

Unimportant Positions

Removes Position tracks other than root_bone and scale_base_bone 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.

Unmapped Bones

Removes unmapped bone Transform tracks from