BoneMap in Godot – Complete Guide

Understanding the Skeletal Harmony: Introducing BoneMap in Godot 4

When diving into the world of 3D animation and game design, managing complex character movements becomes a challenging yet vital task. Animators and developers are often faced with the need to repurpose animations to fit different character rigs. This is where BoneMap in Godot 4 enters the picture, serving as a bridge between different skeletal structures. In this tutorial, we explore the capabilities of Godot 4’s BoneMap class, a feature that enables efficient animation retargeting in your game development projects.

What is BoneMap?

BoneMap is a resource within the Godot 4 engine designed to assist with animation retargeting for 3D models. It operates as a dictionary mapping one skeleton’s bone names to another, using a predefined SkeletonProfile. This mapping process ensures that animations intended for one skeletal structure can be translated onto another, promoting the reusability of animations across various character models.

What is it for?

Animation retargeting can be incredibly useful for game developers who want to apply the same set of animations to multiple characters with different skeletal setups. Rather than animating each character from scratch, developers can create a versatile animation database that is adaptable to various character rigs.

Why should I learn it?

Leveraging BoneMap in your Godot projects can offer several benefits:
– **Efficiency:** Save time by reusing animations across multiple characters.
– **Consistency:** Maintain the quality and consistency of animations throughout your game.
– **Flexibility:** Easily adjust and retarget animations to fit new character models or rigs.

Understanding and implementing BoneMap will not only streamline your animation workflow but also deepen your expertise in Godot 4’s powerful animation tools, opening up new possibilities for your game development projects. Let’s move on and see BoneMap in action through practical code examples.

CTA Small Image

Setting Up Your BoneMap

Before diving into code examples, let’s set up a BoneMap in Godot 4. Start by creating a new BoneMap resource:

var bone_map =

You’ll then need to create a new SkeletonProfile that defines the reference skeleton which your animations are based on:

var skeleton_profile =

After creating the SkeletonProfile, you can define the bone names of your reference skeleton. This is an essential step as it allows Godot to understand your animation’s structure:


Now, it’s time to map these bones to the corresponding bones in a different skeleton:

bone_map.set_bone_name("Arm", "RightForearm")
bone_map.set_bone_name("Leg", "RightCalf")
bone_map.set_bone_name("Head", "Neck")

Applying the BoneMap to an Animation

With the bone names mapped, you can apply the BoneMap to an AnimationPlayer node. First, ensure you have an AnimationPlayer node with animations loaded. The BoneMap can be applied as follows:

var animation_player = $YourCharacterPath/AnimationPlayer
animation_player.get_animation("walk").apply_bone_map(bone_map, skeleton_profile)

The code above applies the BoneMap to the “walk” animation of your character, retargeting the animation based on the mappings provided.

Retargeting Animations in Real-Time

Sometimes you may want to retarget animations during gameplay. This can be achieved by applying the BoneMap on-the-fly:

func retarget_animation(animation_name):
    var anim = animation_player.get_animation(animation_name)
    anim.apply_bone_map(bone_map, skeleton_profile)

Call ‘retarget_animation’ with the name of the animation you want to play, and the animation will be applied to your character, considering the BoneMap’s settings.

Creating Dynamic BoneMaps

There might be instances where you need to create BoneMaps dynamically based on user input or procedural characters. For example, imagine a character customization system where players adjust their character’s arm length; you would need to create a different mapping:

func create_dynamic_bone_map(character):
    var dynamic_bone_map =
    for bone_name in character.get_bone_list():
        dynamic_bone_map.set_bone_name(bone_name, "Custom" + bone_name)
    return dynamic_bone_map

The function above would create a BoneMap for a provided character, prefixing ‘Custom’ to each bone name to match a specific naming convention.

Saving and Loading BoneMaps

Finally, saving and loading BoneMaps is straightforward in Godot. To save your BoneMap, use the following code:

func save_bone_map(path):
    var file =
    if, File.WRITE) == OK:

Loading a saved BoneMap is a matter of reading from the saved file:

func load_bone_map(path):
    var file =
    if, File.READ) == OK:
        var loaded_bone_map = file.get_var()
        return loaded_bone_map

These snippets create a framework for managing BoneMaps within your Godot 4 games. By mastering these fundamentals, you’re equipping yourself with a powerful system to handle complex animation retargeting. Continue to the next part of our tutorial where we’ll explore advanced techniques and troubleshooting.

Remember, mastering BoneMap functionality in Godot 4 is a process. But by breaking down the tasks into manageable chunks and understanding each aspect of its application, you’ll be well on your way to creating more dynamic and diverse animations in your games. Stay tuned for more insights on how we leverage Godot 4 to breathe life into our characters.

Advanced Animation Retargeting Techniques

In more advanced scenarios, you might require not only simple bone name mapping but also to adjust transformations for a more accurate retargeting process. Godot 4 provides the functionality to modify these transformations directly.

Here’s how you can adjust the transformation of a specific bone when applying a BoneMap:

func adjust_bone_transform(bone_name, transform):
    var new_bone_map = bone_map.duplicate()
    var current_transform = new_bone_map.get_bone_transform(bone_name)
    new_bone_map.set_bone_transform(bone_name, current_transform * transform)

In the code above, ‘get_bone_transform’ is used to fetch the current transform of the bone, and ‘set_bone_transform’ updates it, multiplying it by another transform matrix provided by ‘transform’.

Sometimes, animation retargeting might involve scaling bones to fit the character rig correctly. Let’s consider a code snippet that scales bone transformations in a BoneMap:

func scale_bone_transforms(scale_factor):
    for bone_name in bone_map.get_bone_list():
        var bone_transform = bone_map.get_bone_transform(bone_name)
        bone_transform = bone_transform.scaled(Vector3(scale_factor, scale_factor, scale_factor))
        bone_map.set_bone_transform(bone_name, bone_transform)

The loop iterates over each bone name in the BoneMap, fetching, scaling, and then setting the new scaled transform back into the BoneMap.

Automating BoneMap Creation

Creating a BoneMap manually can be painstaking, especially for characters with a large number of bones. Automating the process is more efficient:

func generate_bone_map_from_skeleton(skeleton):
    var bone_map =
    for i in range(skeleton.get_bone_count()):
        var bone_name = skeleton.get_bone_name(i)
        bone_map.set_bone_name(bone_name, bone_name + "_Target")
    return bone_map

The function ‘generate_bone_map_from_skeleton’ generates a BoneMap for a given skeleton by iterating through all bones and adding each one to the BoneMap with “_Target” appended to the names.

Handling Changes in BoneMap

Live updates to a BoneMap while animations are playing can lead to unexpected results. If your game design requires updates to the BoneMap during runtime, you may need to refresh the animations to apply the changes:

func update_bone_map_and_refresh_animations(anim_player, new_bone_map):
    for animation_name in anim_player.get_animation_list():
        var anim = anim_player.get_animation(animation_name)
        anim.apply_bone_map(new_bone_map, skeleton_profile)
    anim_player.advance(0)  # Refresh animations

Whenever a new BoneMap is applied via ‘update_bone_map_and_refresh_animations’, the function iterates through all loaded animations, applying the new BoneMap and forcing an update call on the AnimationPlayer.

Debugging BoneMap Issues

When an animated character does not behave as expected after applying a BoneMap, you might need to debug the issue. This may involve checking for missing or incorrect bone mappings:

func debug_bone_map(bone_map):
    var missing_bones = []
    var skeleton = $YourCharacterPath/Skeleton
    for i in range(skeleton.get_bone_count()):
        var bone_name = skeleton.get_bone_name(i)
        if not bone_map.has_bone_name(bone_name):
    if missing_bones.size() > 0:
        print("BoneMap missing bones: ", missing_bones.join(", "))

This function provides a simple debugging mechanism, ‘debug_bone_map’, by collecting and printing the list of bones from the character’s Skeleton that are not present in the provided BoneMap.

Each code example advances your understanding of BoneMap usage, and with these advanced and troubleshooting techniques, you can ensure your characters move as intended. Remember that careful mapping and testing are key to successful animation retargeting in Godot 4. Happy animating!Here, we’ll explore more complex scenarios where we might want to blend animations from different sources or adjust the blending properties.

When you work with multiple animation layers, it’s crucial to control how they influence the final pose of the character. In Godot 4, you can define the blend amount per bone or per animation:

func set_animation_blend_amount(anim_player, animation_name, bone_name, blend_amount):
    anim_player.get_animation(animation_name).track_set_importance(anim_player.find_track(bone_name), blend_amount)

This code sets how much a particular bone’s track in an animation affects the final pose in an AnimationPlayer. A blend amount of 0 means the track has no influence, and 1 means full influence.

Sometimes, you may also want to interpolate between different BoneMaps to transition from one character’s movement style to another’s. Interpolating BoneMaps can create a seamless transition:

func interpolate_bone_maps(bone_map_a, bone_map_b, weight):
    var interpolated_bone_map =
    for bone_name in bone_map_a.get_bone_list():
        var transform_a = bone_map_a.get_bone_transform(bone_name)
        var transform_b = bone_map_b.get_bone_transform(bone_name)
        var interpolated_transform = transform_a.interpolate_with(transform_b, weight)
        interpolated_bone_map.set_bone_transform(bone_name, interpolated_transform)
    return interpolated_bone_map

Using ‘interpolate_with’ from the Transform class allows us to blend two BoneMap transformations by a given weight, which controls how much influence each BoneMap has in the transition.

Retargeting animations often leads to the need of inverting a BoneMap, especially when characters are symmetric, and you want to mirror animations:

func invert_bone_map(bone_map):
    var inverted_bone_map =
    for bone_name in bone_map.get_bone_list():
        var-target_bone_name = bone_map.get_bone_name(bone_name)
        inverted_bone_map.set_bone_name(target_bone_name, bone_name)
    return inverted_bone_map

This snippet creates a new BoneMap where each mapping is reversed, which can be useful for applying mirrored animations to a character, such as walking in the opposite direction.

When dealing with physics-based animations or procedural animations, you may need to apply BoneMap changes directly to a PhysicsBone:

func apply_bone_map_to_physics_bone(physics_bone, bone_map):
    for bone_name in bone_map.get_bone_list():
        var target_bone_transform = bone_map.get_bone_transform(bone_name)
        physics_bone.set_bone_custom_pose(bone_name, target_bone_transform)

This function applies the bone transformations from a BoneMap to a PhysicsBone, letting you manipulate physics-based animations dynamically.

If your game involves characters with various sizes, such as giants or miniatures, you might need to scale entire animations using a BoneMap:

func scale_animation(animation, bone_map, scale_factor):
    for bone_name in bone_map.get_bone_list():
        var track_index = animation.find_track(bone_name)
        if track_index != -1:
            var keys = animation.track_get_key_count(track_index)
            for i in range(keys):
                var key = animation.track_get_key(track_index, i)
                if key has_method("get_value"):
                    var transform = key.get_value()
                    transform = transform.scaled(Vector3(scale_factor, scale_factor, scale_factor))
                    animation.track_set_key_value(track_index, i, transform)

Here, each keyframe’s transformation for a specified bone in an animation is scaled by the ‘scale_factor’, applying different character size adjustments while preserving the original animation’s integrity.

These examples further enhance your toolset when working with BoneMap retargeting in Godot 4. From blending animations to processing physics-bone movements, you now have the knowledge to tackle complex animation challenges within your projects. Continue experimenting and integrating these techniques to create smooth and responsive animations for your game characters.

Expanding Your Game Development Horizons

Delving into the intricacies of BoneMap and animation retargeting in Godot 4 is just the beginning of your game development journey. To keep advancing your skills and creations, we encourage you to continue exploring and experimenting with Godot’s vast features. When you’re ready to dive deeper and seek structured learning experiences, our Godot Game Development Mini-Degree offers a comprehensive curriculum designed to take you from beginner to confident game developer using the powerful and versatile Godot 4 engine.

Our Mini-Degree covers essential topics such as 2D and 3D game creation, gameplay programming, and designing complex game systems, adapting to different game genres. Each course is project-based, providing you with hands-on experience to solidify your learning and enabling you to build a robust portfolio. What’s more, with Zenva’s flexible learning options, including live coding lessons and quizzes, you’ll have all the resources at your fingertips to succeed at your own pace.

But why stop there? For those eager to expand their knowledge further, we feature a broader collection of Godot courses, catering to various interests within the realm of game development. Whether you are new to the field or seeking to enhance your existing skill set, Zenva provides over 250 courses that can propel your career to new heights. With us, you can go from learning the basics to mastering professional game development techniques. So take the next step in your development journey with Zenva and start creating games that captivate players around the world!


Diving into the world of BoneMap and animation retargeting within Godot 4 is a significant stride in mastering game development. These skills refine the animations that bring your characters to life, ensuring a memorable experience for players. We hope this tutorial has ignited your passion for 3D animation and given you the confidence to tackle animation challenges with ease.

As your adventure in game development continues, never stop learning and pushing the boundaries of your creativity. Check out our Godot Game Development Mini-Degree to unlock your full potential and translate your newfound knowledge into breathtaking games that resonate with audiences. Embrace the artist within you, and let Zenva be your guide on this exciting journey of game creation.

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.