BoneAttachment3D in Godot – Complete Guide

Welcome to our insightful and comprehensive tutorial on the BoneAttachment3D class in Godot 4! If you’re a game developer or aspiring to become one, you know that animation and character interaction within the 3D world are pivotal for a dynamic gaming experience. BoneAttachment3D is a class that holds the key to creating lifelike and responsive movements within your Godot projects. Whether you’re a beginner or have some experience under your belt, strap in; this tutorial will deepen your understanding of how skeleton-based animations work and open up new possibilities in your game development ventures.

What Is BoneAttachment3D?

Inherits: Node3D < Node < Object

BoneAttachment3D is a Godot node specifically designed for 3D animation. It allows developers to attach nodes to specific bones in a character’s skeleton. This plays a crucial role in making sure that objects, such as weapons, hats, or other accessories, follow the exact movements and transformations of the character’s bones they are attached to.

What Is It For?

The primary use of BoneAttachment3D is to maintain the spatial relationship between a node and a bone of a Skeleton3D. When a character moves, jumps, or performs any action, any node attached using BoneAttachment3D will move in sync with the corresponding bone. It is highly useful for:

  • Attaching equipment or items to characters
  • Animating secondary characters or objects that are directly influenced by the main character’s movement
  • Creating effects that need to follow the limb movements, like magic spells or flowing capes

Why Should I Learn It?

Understanding and utilizing BoneAttachment3D can be a significant leap forward in creating more polished and interactive games. By learning to use this powerful feature, you can:

  • Add an additional layer of realism to your characters
  • Reduce the need for complex animations for attached objects
  • Maximize your efficiency by automating movement coordination between objects and your characters

Moreover, with Godot’s increasing popularity for indie and professional game development alike, mastering BoneAttachment3D will equip you with more tools to make your game stand out in a crowded marketplace.

CTA Small Image

Creating a BoneAttachment3D Node

To get started with BoneAttachment3D, let’s first see how to create one and attach it to a bone in the Skeleton3D node of a character.

var bone_attachment =
var skeleton = $Character/Skeleton3D
bone_attachment.bone_name = "Right_Hand"

This script creates a new BoneAttachment3D node, finds the character’s skeleton, and attaches the new node to the right hand bone.

Attaching Objects to Bones

Now, let’s attach an object, such as a sword, to the same bone using the BoneAttachment3D we created earlier.

var sword = preload("res://Sword.tscn").instance()

This code snippet preloads a sword scene and instances it as a child of the bone attachment, effectively attaching the sword to the “Right_Hand” bone of the skeleton.

Positioning and Rotating Attached Objects

You may need to adjust the position or orientation of the object to fit the bone correctly. The following code positions and rotates the sword to align properly with the hand bone:

sword.translation = Vector3(0.0, 0.1, -0.2)
sword.rotation_degrees = Vector3(90.0, 0.0, 0.0)

Adjusting the translation and rotation degrees will depend on the specific model and scene setup.

Animating the Skeleton

Once the object is attached, animating the skeleton will automatically move the object along with the bone. Here is a simple animation code that moves the right hand bone up and down:

var animation_player = $Character/AnimationPlayer"Raise_Right_Hand")

This code plays an animation named “Raise_Right_Hand” using an AnimationPlayer node, showing how the sword attached to the right hand will follow the animation.

Scripting with BoneAttachment3D

We can also interact with BoneAttachment3D nodes through scripts for more complex behaviors. For instance, the following script checks if an attached object is within a bone attachment:

if bone_attachment.get_child_count() > 0:
    var child_node = bone_attachment.get_child(0)
    print("An object is attached to the bone: " +
    print("No objects are attached to this bone.")

This script checks if there are any children attached to the bone attachment and prints a message accordingly.

Detaching Objects

To detach an object from a bone, you can simply remove it from the BoneAttachment3D node:

if bone_attachment.get_child_count() > 0:
    var child_node = bone_attachment.get_child(0)

The above code removes the first child of the bone attachment, which would be the sword in our example, thus detaching it from the character’s hand.Great! Let’s dive deeper into how you can interact with BoneAttachment3D nodes in various scenarios within your Godot game projects.

Changing Attached Objects During Runtime

In a dynamic game, you might want to change the equipment or items your character is using. Below is an example of how you can swap out one object for another on the fly.

func swap_weapon(new_weapon_scene):
    if bone_attachment.get_child_count() > 0:
        var old_weapon = bone_attachment.get_child(0)
    var new_weapon = new_weapon_scene.instance()

This function removes the current weapon and replaces it with a new one provided by `new_weapon_scene`.

Accessing the Bone’s Transform

Sometimes, you’ll want to know the global transform of the bone to which an object is attached. This can be useful for certain gameplay mechanics, like launching a projectile precisely from the character’s hand.

var bone_global_transform = bone_attachment.global_transform

This line of code retrieves the global transform of the bone_attachment, which includes the position, rotation, and scale in the world space.

Using BoneAttachment3D with Inverse Kinematics (IK)

You might be using IK to control how certain bones move and rotate. BoneAttachment3D works perfectly in conjunction with IK systems.

var ik_node = $Character/SkeletonIK
ik_node.start_bone = "Right_Hand"
ik_node.end_bone = "Right_Hand_IK_Target"

This script configures an IK node to control the right hand based on a target node’s position, and updates it to apply the IK calculations.

Listening to Bone Movement with Signals

You can connect signals to detect when a bone has moved, which can be helpful to trigger events like sound effects or particle systems.

bone_attachment.connect("bone_transform_changed", self, "_on_Bone_transform_changed")

func _on_Bone_transform_changed():
    print("The attached bone has moved.")

This code connects a hypothetical `bone_transform_changed` signal to a local function that will print a message when the bone’s transform changes. Remember to replace the signal name with the actual signal you want to listen to if there is one exposed for the node.

Disabling BoneAttachment3D Temporarily

There might be cases where you want the attached objects to stop following the bone’s movements temporarily, without detaching them. You can disable the BoneAttachment3D node to do just that.

bone_attachment.disabled = true

# something while the attachment is inactive...

bone_attachment.disabled = false

The example above leverages the `disabled` property, setting it to true to stop the attachment from following the bone and false to resume its normal functionality.

Refreshing Attachments

If you’ve made changes to the Skeleton3D or BoneAttachment3D nodes, you may need to ensure that the attachments update accordingly.


This simple method call forces the BoneAttachment3D node to update its gizmo in the Godot editor, ensuring you see the changes immediately.

By now, you should have a firm grasp of how to utilize BoneAttachment3D nodes in your Godot projects. Implementing these techniques can greatly enhance the interactivity and realism of your game, allowing you to create complex character interactions with less effort. Remember to experiment and play around with the code examples provided to fully understand their impact on your game’s mechanics. Happy coding!Certainly! Let’s delve into some more advanced implementations of the BoneAttachment3D class to achieve sophisticated behaviours in your Godot games.

Advanced Uses of BoneAttachment3D

Imagine you want to make sure that the attached object not only follows the bone’s movement but also its scale and rotation. Here’s how you could implement this:

func sync_transform_with_bone(bone_attachment, skeleton):
    var bone_idx = skeleton.find_bone(bone_attachment.bone_name)
    var bone_transform = skeleton.get_bone_global_pose(bone_idx)
    bone_attachment.global_transform = bone_transform

With this function, any time you apply a new transformation to the bone, you can call `sync_transform_with_bone` to instantly update the BoneAttachment3D node with the latest transformation.

Sometimes, you might want to add an interaction when a bone reaches a certain position:

func check_bone_position(bone_attachment, target_position, threshold):
    if bone_attachment.global_transform.origin.distance_to(target_position) < threshold:
        print("Bone reached the target position!")

This function checks to see if the bone, through the BoneAttachment3D node, is within a certain distance (`threshold`) of a `target_position` and prints a message if it does.

For combat or interactive games, you might want the attached object to deal damage upon collision. Here’s how you can set up a simple collision detection using signals:

func _on_Sword_area_entered(area):
    if area.is_in_group("Damageable"):

sword.connect("area_entered", self, "_on_Sword_area_entered")

This code makes the assumption that there’s an Area node attached to the sword that detects collision through the `area_entered` signal. When something enters that area and is in the “Damageable” group, it receives damage.

Sometimes, you need to perform actions on all attached objects. It’s simple and straightforward:

for child in bone_attachment.get_children():
    if child.has_method("perform_action"):

This iterates over every object attached to the bone and calls a `perform_action` method if the child node has one defined.

For a situation where the character needs to release an object to the world, while maintaining the same velocity as the character:

var released_object_velocity = character_velocity + (character_rotation_speed * relative_position_to_character)
released_object.global_transform = bone_attachment.global_transform
released_object.apply_impulse(Vector3(), released_object_velocity)

This example calculates the velocity that should be applied to a released object (e.g., a ball) based on the character’s own movement and then releases it into the world by applying the calculated impulse.

Last but not least, you might find a scenario where you need to swap out many items at once, such as changing all the armor on a character:

func swap_armor(armor_pieces):
    for armor_piece in armor_pieces:
        var bone_name = armor_piece.bone_name
        var bone_attachment = skeleton.get_node_or_null(bone_name)
        if bone_attachment:
            var new_armor_piece = armor_piece.instance()
            new_armor_piece.bone_name = bone_name

This script would accept a dictionary or array of preloaded armor pieces, find their respective bone attachment points, remove the current piece, and then replace it with a new one.

These examples showcase a variety of ways in which the BoneAttachment3D node can be interacted with and manipulated to create dynamic, responsive, and interesting mechanics for your Godot games. Remember to adapt the snippets to fit your project’s needs and let your creativity take the lead!

Continuing Your Game Development Journey

You’ve taken an important step in mastering the intricacies of the BoneAttachment3D class in Godot 4, and we commend your dedication to learning. But don’t stop here—there’s an entire universe of game development knowledge waiting for you to unlock. To keep the momentum going and to dive even deeper into the world of game creation with Godot, we have the perfect resource for you.

Check out our Godot Game Development Mini-Degree, a meticulously curated selection of courses designed to take you from the fundamentals to building your own cross-platform games. Whether you’re interested in honing your skills in 2D, 3D, GDScript, or exploring specific game genres like RPGs or platformers, this Mini-Degree has you covered. It’s self-paced and project-based, ensuring a practical and flexible learning experience.

Moreover, to explore a more extensive variety of courses that span different aspects and advanced topics within Godot, our broad collection of Godot courses is available at your fingertips. At Zenva, we offer over 250 courses catering to both beginners and seasoned developers looking to refine their craft. Embark on your path to becoming a professional with us, and create games that captivate and amaze. Let’s build the extraordinary, together!


We hope you’ve found this tutorial on the BoneAttachment3D class in Godot 4 both enlightening and inspiring. As you continue to experiment and implement what you’ve learned, remember that every new line of code is a step towards crafting more immersive and dynamic worlds for your players to enjoy. The ability to seamlessly bind objects to a character’s skeleton unleashes a whole new level of interaction within your games, and we can’t wait to see what you create with it.

Before you go, remember to empower your learning journey with the comprehensive and hands-on experience provided by our Godot Game Development Mini-Degree. Your dream game is waiting to be brought to life, and with Zenva by your side, you’re equipped to make that dream a vivid reality. Continue to learn, create, and grow with us—the next level of your game development adventure is just one course away.

Python Blog Image

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