bone-attachment_skill

Overview

This skill provides a lightweight pattern for attaching meshes to bones of a skinned mesh in React Three Fiber, for example mounting a sword on a character's hand. It exposes a BoneChild pattern that parents a container group to a specific bone, allowing stable attachments that follow skeletal animation. The approach is TypeScript-friendly and works with GLTF nodes returned by useGLTF.

How this skill works

The BoneChild component takes a bone reference (from GLTF nodes) and, on mount, creates a container group that is added to the bone via bone.add(container). Child meshes are rendered inside that container so they inherit the bone transform as the skeleton animates. On unmount the component removes the container from the bone to avoid dangling references and memory leaks. You can pass position, rotation, and scale offsets to precisely position the attachment relative to the bone.

When to use it

• Attach weapons, props, or gear to a character that uses a skinned mesh and animations.
• Mount visual effects or lights to bones so they follow animated limbs.
• Temporarily attach objects (picked-up items, tools) that should move with the skeleton.
• When you need precise position/rotation offsets without modifying the source rig.
• Attach cosmetics or equipment dynamically at runtime in a game or interactive scene.

Best practices

• Obtain bone references from the GLTF nodes (e.g., nodes.HandR) so you attach to the exact joint.
• Use a small container group as the attachment root to isolate position/rotation/scale offsets.
• Always remove the container in cleanup to prevent memory leaks and unexpected parenting.
• Tune offsets in local space to match the mesh orientation of the model and the attached asset.
• Keep attached meshes lightweight and use instancing or LOD for many attachments to save performance.

Example use cases

• Attach a sword to the character's right hand and adjust translation/rotation so it sits in the grip.
• Parent a torch or lantern to a character's hand so the light follows animations.
• Attach armor plates or backpacks dynamically when equipping items in a game.
• Add particle emitters to a bone for localized VFX like a trail on a swinging weapon.
• Temporarily parent a picked-up object to the hand during interaction animations.