SkeletonProfileHumanoid in Godot – Complete Guide

Welcome to our tutorial on the SkeletonProfileHumanoid class in Godot 4, a powerful tool for game developers looking to create human character animations with ease. As we delve into this subject, we hope to demystify the components of the SkeletonProfileHumanoid, showing how it can streamline your animation process. This tutorial aims to provide you with a comprehensive understanding of how this class functions and how it can be applied to your own game projects, helping you to standardize character movements and enhance overall gameplay experience.

What Is SkeletonProfileHumanoid?

The SkeletonProfileHumanoid is a predefined class in the Godot 4 engine designed to work smoothly with humanoid skeletons. It’s a subclass of SkeletonProfile, meaning it inherits a set of behaviours and properties customized for managing humanoid animations within the engine.

What Is It For?

The primary purpose of the SkeletonProfileHumanoid class is to provide developers with a standardized way to manage humanoid skeletal data. This standardization ensures a consistent approach to handling bones and movements for human-like characters, something that is incredibly important in games with multiple humanoid characters.

Why Should I Learn It?

Understanding the SkeletonProfileHumanoid class and its applications will equip you with the necessary tools to efficiently create realistic human animations. Learning to utilize this specialized class will save you time and resources, allowing you to focus more on the creative aspects of game development. It’s a valuable skillset for anyone working with character animations in the Godot engine.

Let’s get ready to dive deeper into the workings of SkeletonProfileHumanoid with practical examples and easy-to-understand explanations. Whether you’re just starting in the world of game development or looking to refine your animation skills, this tutorial is structured to cater to all levels of expertise.

CTA Small Image

Exploring the Basics of SkeletonProfileHumanoid

In this section of our tutorial, we’ll begin by exploring the fundamental components of the SkeletonProfileHumanoid class. This groundwork will help us understand how to properly instantiate the class and assign the profile to a humanoid armature in your Godot project.

var humanoid_profile =

Above, we’ve just created an instance of the SkeletonProfileHumanoid. At this stage, it doesn’t do much, but this act sets the stage for further customization and functionality.

Now, let’s assign this profile to a skeleton and see how it integrates:

var my_skeleton = $YourHumanoidSkeletonPath
my_skeleton.profile = humanoid_profile

With these lines, we’re fetching the skeleton node and then setting its profile to be the humanoid profile we’ve just instantiated. This allows Godot’s animation systems to recognize our skeleton as humanoid.

Next, we will define some bone mappings to associate the generic bones in the profile with our specific rig. This is crucial for retargeting animations and ensuring that the movements look correct on our character:

humanoid_profile.set_bone_name("hips", "Pelvis")
humanoid_profile.set_bone_name("spine", "Spine1")
humanoid_profile.set_bone_name("chest", "Spine2")
humanoid_profile.set_bone_name("upper_arm_l", "LeftArm")
humanoid_profile.set_bone_name("upper_arm_r", "RightArm")

In the above code, the first argument is the name of the bone as expected by the profile, and the second is the name of the bone in your specific skeleton.

Let’s run a simple check to ensure all bones have been mapped correctly:

for bone in humanoid_profile.get_mapped_bones():

This will print out all bone names that have been properly mapped between your skeleton and the profile. Ensuring that these mappings are correctly set up is fundamental before attempting to animate your characters.

Now, let’s see how to deal with bone rest poses, which are crucial for maintaining a consistent starting point for your animations:

humanoid_profile.set_bone_rest("upper_arm_l", Transform(Basis(), Vector3(0, 1, 0)))
humanoid_profile.set_bone_rest("upper_arm_r", Transform(Basis(), Vector3(0, -1, 0)))

Here, we’re defining rest poses for the left and right upper arms. The Transform requires a Basis (rotation) and Vector3 (position) which dictate the default pose of the bone.

We’ve now tackled the basics of creating a SkeletonProfileHumanoid, mapping bones, and setting rest poses. This covers the essentials you’ll need for most humanoid setups and prepares us for more complex operations in the next section.

Animating with SkeletonProfileHumanoid

With the skeleton set up and bones properly mapped, let’s animate our character. We’ll begin by playing a simple animation:

var my_animation = preload("res://path_to_your_animation.tres")"my_animation")

The code preloads an animation resource and starts playing it on the skeleton. However, this assumes you have an AnimationPlayer node set up properly with an animation named “my_animation.”

But what if we want to blend two animations together? Let’s do a basic blend:"walk_animation")"wave_animation", -1, 0.5)

This will play the “walk_animation” and blend it with “wave_animation” at a 50% blend ratio. A more sophisticated blend can involve the AnimationTree node, but that is a topic for another tutorial.

Suppose you want to programatically change a bone’s pose during an animation, consider using this:

var custom_pose = Transform(Basis(), Vector3(1, 0, 0))
my_skeleton.set_bone_custom_pose("upper_arm_l", custom_pose)

Setting a custom pose on ‘upper_arm_l’ overrides the animation for this particular frame. It’s essential for things like IK (Inverse Kinematics) adjustments or procedural animation effects.

And finally, here’s how you reset a bone’s custom pose:

my_skeleton.set_bone_custom_pose("upper_arm_l", Transform())

Resetting the custom pose for ‘upper_arm_l’ allows the normal animation to play out for this bone again.

Through this section, we’ve explored basic assignment, bone mapping, and a touch of animation handling within the SkeletonProfileHumanoid. These examples are fundamental stepping stones as you learn more about animating humanoid characters in Godot 4. In the next part, we’ll dive into slightly more advanced topics, further showcasing the versatility of the SkeletonProfileHumanoid class.As we move forward, let’s focus on how to utilize the SkeletonProfileHumanoid class to manage and modify animations at runtime. One of the critical aspects of animation is mirroring, which can be especially useful when you want to use the same animation for opposite limbs without manually creating them.

Suppose we have a punch animation with the right arm. Here’s how you mirror it to create a left punch:

my_skeleton.profile_mirror_xform("right_punch", "left_punch", true)

The `profile_mirror_xform` function creates a new animation called “left_punch” that mirrors the “right_punch” animation along the X-axis.

Next, let’s look at an example of how adding custom metadata to bones can help drive game logic. This metadata can be anything from hitbox sizes to sound effects, and it’s accessible during animation playback.

First, let’s add a metadata entry to a bone:

humanoid_profile.set_bone_meta("head", "hit_points", 100)

We’ve added a “hit_points” metadata with a value of 100 to the “head” bone.

To retrieve this metadata during your game logic, you could use the following code:

var bone_hit_points = humanoid_profile.get_bone_meta("head", "hit_points")

This prints out the “hit_points” metadata associated with the “head” bone, which in this case would print 100.

Let’s not forget about adding some dynamic influence to our predefined animations. You can modify the influence of a playback track to blend it with other tracks:

var anim_state = my_skeleton.get_animation_state()
anim_state.set_track_enabled(my_skeleton.find_animation_track("wave_animation"), true)
anim_state.set_track_mix("wave_animation", 0.75)

By modifying the track mix, we can control how much the “wave_animation” influences the current animation state, in this case setting it to 75%.

What if you want to dynamically adjust a bone’s position based on gameplay logic? You can do this easily by changing the bone’s global position:

var new_position_global = Vector3(1, 2, 3)
var bone_idx = my_skeleton.find_bone("head")
my_skeleton.set_bone_global_position(bone_idx, new_position_global)

This code snippet moves the “head” bone to the specific global position (1, 2, 3).

Lastly, it’s crucial to understand the flow of control when combining script-driven bone manipulation with animations:

my_skeleton.set_bone_custom_pose("spine", custom_pose)
my_skeleton.animation_process_mode = AnimationProcessMode.FIXED

The above code sets a custom pose for the “spine” bone and then sets the animation process mode to FIXED. This ensures that the animation updates happen in sync with the physics step, which can be important for maintaining consistency in physics-driven games.

By incorporating these code examples into your understanding of the SkeletonProfileHumanoid class, you’ll be equipped to manage and manipulate humanoid animations with great flexibility and control. The examples we’ve provided are only the beginning, and as you become more familiar with these functions, you’ll discover a wealth of possibilities in animating your humanoid characters in Godot 4. Remember, experimenting with these methods will deepen your mastery and enable you to create more compelling and dynamic animations in your games.Continuing with our exploration of the SkeletonProfileHumanoid class, let’s consider scenarios where you’d want to adjust animations based on in-game interactions. For instance, altering a character’s posture to respond to being hit or interact with objects.

Imagine your character needs to duck when a projectile comes their way. Here’s how you’d adjust the spine bones to create a quick ducking motion:

var duck_pose = Transform(Basis(), Vector3(0, -0.5, 0)) 
my_skeleton.set_bone_custom_pose("spine", duck_pose)
my_skeleton.set_bone_custom_pose("chest", duck_pose)

This will move the spine and chest bones downwards by 0.5 units, simulating a ducking position.

Now, suppose your character should look at a point of interest, such as a character talking or an object to interact with. You might use code like this to rotate the head bone towards that point:

var target_global_position = Vector3(5, 1, 2)
var head_global_transform = my_skeleton.global_transform * my_skeleton.get_bone_global_pose_no_override(my_skeleton.find_bone("head"))
var look_at_transform = head_global_transform.looking_at(target_global_position, Vector3.UP)
my_skeleton.set_bone_custom_pose("head", my_skeleton.global_transform.inverse() * look_at_transform)

This will calculate the transform needed for the “head” bone to face the target position and apply it as a custom pose.

Animations often need to adapt to the game environment. For instance, your character might need to change stance when on uneven terrain. You can adjust the leg bones accordingly:

var left_leg_adjust = Transform(Basis(), Vector3(0, 0.3, 0))
var right_leg_adjust = Transform(Basis(), Vector3(0, -0.2, 0))
my_skeleton.set_bone_custom_pose("upper_leg_l", left_leg_adjust)
my_skeleton.set_bone_custom_pose("upper_leg_r", right_leg_adjust)

These adjustments raise and lower the left and right upper legs respectively, simulating a stance on a slope.

Let’s say you want to reverse an animation, playing it backwards. This can be useful for creating dynamic reactions or rewinding actions. Here’s a way to do that:

var anim_name = "jump_animation"
var is_playing_backwards = true
var playback_speed = is_playing_backwards ? -1.0 : 1.0
my_skeleton.set_animation_speed(anim_name, playback_speed)

Setting a negative playback speed causes the animation to play in reverse.

How about changing the character’s movement speed based on in-game actions, such as sprinting? You can dynamically modify the animation speed to achieve this:

var sprinting = true
var sprint_multiplier = 2.0 
var walk_anim_name = "walk_animation" 
var current_speed = sprinting ? sprint_multiplier : 1.0
my_skeleton.set_animation_speed(walk_anim_name, current_speed)

By adjusting the animation speed, the walk animation will play faster, creating the effect of sprinting.

Handling complex interactions, such as a character picking up an object, can be broken down into sub-animations:

my_skeleton.set_animation_process_mode(AnimationProcessMode.FIXED)"reach_out")"grip_object", -1, 1.0, true)

In this case, ‘reach_out’ might be the animation for extending the character’s arm, and ‘grip_object’ is for closing the hand, played with a delay and blend time to create a realistic reaching and gripping motion.

Remember, combining these tools and techniques with clever game design will create immersive and responsive animations that can dramatically improve the player’s experience. By mastering the SkeletonProfileHumanoid class and understanding how to manipulate humanoid skeletons programmatically, you open up a world of possibilities in character animation within the Godot 4 engine.

Continue Your Game Development Journey

Your exploration into the SkeletonProfileHumanoid class in Godot 4 is just the beginning of a rewarding journey in game development. To keep expanding your skills and knowledge, we invite you to check out our comprehensive Godot Game Development Mini-Degree. This series of project-based courses is tailored to equip both beginners and experienced developers with the tools needed to create their own games using the Godot 4 engine.

Our mini-degree covers a range of essential topics, helping you master 2D and 3D assets, understand GDScript, and learn how to implement gameplay control flow. You’ll gain hands-on experience building player and enemy combat systems, item collection mechanics, UI systems, and delve into various game genres like RPG, RTS, survival, and platformers. With Zenva’s self-paced online learning, you can access these lessons anytime, on any device, accommodation your learning around your schedule.

Furthermore, we have a broad collection of courses available for those looking to delve deeper into specific aspects of game creation with Godot. Discover the full range of our Godot courses to continue honing your craft and taking your game development ambitions to new heights. With Zenva, transform your passion into expertise and open doors to a future in the game development industry.


As we’ve seen, the SkeletonProfileHumanoid class in Godot 4 is an incredibly robust tool for animating humanoid characters. By learning to use it effectively, you’ve taken a significant step towards creating the rich, interactive worlds that players crave. Remember, game development is all about bringing creative visions to life and constantly learning new ways to engage your audience. Keep experimenting, pushing the boundaries of what you can achieve with Godot, and most importantly, enjoy the process of bringing your games to life.

Embark on the next stage of your development journey with us; our Godot Game Development Mini-Degree is ready to welcome you. It’s more than just a series of tutorials—it’s a path to becoming a well-rounded developer capable of crafting compelling game experiences. Embrace the challenge, join our community of learners, and let’s create something amazing together.

Python Blog Image

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