Godot入門：BoneAttachment3Dの使い方と活用法

はじめに
BoneAttachment3Dとは？
このノードを使うべき場面
主なプロパティと機能
もっと使いこなす：カスタマイズできるパラメータ
まとめ
シリーズ：Godot 4 ノード解説

はじめに

3Dアニメーションキャラクターの特定の骨（ボーン）に武器やアクセサリーを正確に追従させたいことはありませんか？BoneAttachment3Dはそのような場面で大活躍するノードです。このノードを使うことで、スケルトン（骨組み）の動きに自動で合わせて、子オブジェクトを追従させられます。

BoneAttachment3Dとは？

BoneAttachment3Dは、Skeleton3Dの特定ボーンに子ノードを追従させるためのノードです。ボーンの位置・回転に応じて、自動的に子要素が動きます。

継承ツリー：
BoneAttachment3D
  ↓
Node3D
  ↓
Node

Skeleton3DとBoneAttachment3Dの構成 — Skeleton3DノードにBoneAttachment3Dを配置し、その子に武器やアクセサリーを配置します

このノードを使うべき場面

使うべき場面：

キャラクターの手に武器（剣、銃、杖）を装備させたい
盾や弓をキャラクターに追従させたい
帽子、眼鏡、冠などのアクセサリーをボーンに固定したい
ポーションボトルやランプなどの装備品をベルトに取り付けたい
スケルトンアニメーションの動きに合わせて各種オブジェクトを自動追従させたい

使わない場面：

ボーンアニメーションではなく、単純な親子関係だけが必要な場合（通常のNode3Dで十分）
複数のスケルトンから独立したオブジェクト管理

主なプロパティと機能

プロパティ	型	説明	使用例
`bone_name`	String	追従するボーンの名前（例：”RightHand”）	bone_attachment.bone_name = “RightHand”
`bone_idx`	int	ボーンのインデックス番号（自動的にbone_nameから算出）	読み取り用。通常は編集不要
`override_pose`	bool	外部からポーズを上書きするか（Skeleton3Dの動きに従うか）	override_pose = false（通常はfalse）
`use_external_skeleton`	bool	親以外のSkeletonを参照するか	use_external_skeleton = true で別Skeleton3Dに接続

GDScriptコード例1：基本的な武器アタッチメント


extends Node3D

@onready var skeleton = $Skeleton3D
@onready var bone_attachment = $Skeleton3D/BoneAttachment3D

func _ready():
    # 右手ボーンに追従するよう設定
    bone_attachment.bone_name = "RightHand"

    # 子に武器ノード（MeshInstance3D など）を配置済み
    # これで自動的に右手の動きに合わせて武器も動く
    print("武器が右手に装備されました：%s" % bone_attachment.bone_name)

GDScriptコード例2：外部Skeletonを参照する場合


extends Node3D

@onready var bone_attachment = $BoneAttachment3D
@onready var external_skeleton = $AnotherCharacter/Skeleton3D

func _ready():
    # 別のスケルトンを参照
    bone_attachment.use_external_skeleton = true
    bone_attachment.external_skeleton = NodePath("../../AnotherCharacter/Skeleton3D")
    bone_attachment.bone_name = "LeftHand"

    print("外部スケルトンの左手に接続しました")

もっと使いこなす：カスタマイズできるパラメータ

まずは基本を動かしてみてから、余裕が出たら試してみてください。

パラメータ	型	説明	実装例
`external_skeleton`	NodePath	use_external_skeletonがtrueの場合の参照先Skeleton3D	NodePath(“../OtherCharacter/Skeleton3D”)
`position`（継承）	Vector3	ボーンからのローカルオフセット位置	bone_attachment.position = Vector3(0.1, 0, 0)
`rotation`（継承）	Vector3	ボーンからのローカル回転（ラジアン）	bone_attachment.rotation = Vector3(PI/4, 0, 0)
`scale`（継承）	Vector3	ボーンに対する拡大縮小率	bone_attachment.scale = Vector3(1.2, 1.0, 1.0)
`get_bone_index()`	メソッド	指定名のボーンインデックスを取得	var idx = skeleton.find_bone(“RightHand”)

カスタマイズの実装例：複数装備の管理


extends Node3D

func _ready():
    # 複数のボーンアタッチメントを設定
    var equipment_points = {
        "RightHand": load("res://models/sword.tscn"),
        "LeftHand": load("res://models/shield.tscn"),
        "Head": load("res://models/helmet.tscn")
    }

    for bone_name in equipment_points:
        var attachment = BoneAttachment3D.new()
        attachment.bone_name = bone_name
        $Skeleton3D.add_child(attachment)

        var equipment = equipment_points[bone_name].instantiate()
        attachment.add_child(equipment)

        print("装備 '%s' を '%s' に配置" % [equipment.name, bone_name])