godot-animation

Godot Animation (4.x)

適切なアニメーションツールを選んで動かします。AnimationPlayer（クリップ）、AnimationTree （ブレンド／ステートマシン）、または Tween（短いプロシージャルな動き）を使います。対象は Godot 4.7 です。

使用する場面

• キーフレームアニメーションの再生、歩行／走行／待機状態のブレンド、スプライトシートのアニメーション、またはコードによる UI／オブジェクトのトゥイーン処理に使用します。

使用しない場面： 再生する状態を決める移動のロジック → godot-2d-movement、UI レイアウト（UI のトゥイーン処理ではなく）→ godot-ui-control、シェーダーによるエフェクト → godot-shaders。

基本的なワークフロー

1. ツールを選びます：
   • AnimationPlayer — キーフレームクリップ（トランスフォーム、プロパティ、メソッド呼び出し、オーディオ、さらには他のアニメーション）を作成します。クリップデータの信頼できる唯一の情報源です。
   • AnimationTree — ステートマシンやブレンドスペースを使って、実行時にクリップ間をブレンドして遷移します。クリップを取得するために AnimationPlayer が必要です。
   • Tween — コード内でプロシージャルな補間を実行します（create_tween()）。UI のポップ、フェード、一度きりの動きに最適です。
2. 2D スプライトシートの場合： AnimatedSprite2D + SpriteFrames を使うか、AnimationPlayer で frame プロパティにキーフレームを設定します。
3. キャラクターの場合： AnimationPlayer でクリップを作成してから、AnimationTree （active = true）を追加し、anim_player を設定して、ツリーのルートとして AnimationNodeStateMachine または AnimationNodeBlendSpace2D を構成します。
4. コードから遷移を動かします。 再生オブジェクト（travel）を使うか、ブレンドパラメーターを設定します。
5. クリップのイベントに反応します。 animation_finished シグナルとコール／メソッドトラックを使います。

パターン

1. AnimationPlayer：クリップを再生して完了を待つ

@onready var anim: AnimationPlayer = $AnimationPlayer

func attack() -> void:
    anim.play("attack")
    await anim.animation_finished     # resume after the clip ends
    anim.play("idle")

2. AnimationTree ステートマシン：状態間を遷移する

@onready var tree: AnimationTree = $AnimationTree

func _ready() -> void:
    tree.active = true                # the tree drives animation; AnimationPlayer is the source

func set_state(state: StringName) -> void:
    # The playback object controls an AnimationNodeStateMachine root.
    var sm: AnimationNodeStateMachinePlayback = tree.get("parameters/playback")
    sm.travel(state)                  # transitions using the graph's connections

func _physics_process(_d: float) -> void:
    set_state(&"run" if velocity.length() > 5.0 else &"idle")

3. ブレンドスペース：2D パラメーターで走行方向をブレンドする

# Root is an AnimationNodeBlendSpace2D named "Move" with idle/run points placed in it.
func update_locomotion(input_dir: Vector2) -> void:
    # Parameter path = "parameters/<node name>/blend_position".
    tree.set("parameters/Move/blend_position", input_dir)

4. Tween：UI 要素をフェードして拡大縮小する（コード駆動）

func pop_in(node: Control) -> void:
    node.scale = Vector2.ZERO
    node.modulate.a = 0.0
    var tw := create_tween()                          # bound to this node's tree
    tw.set_parallel(true)                             # run the two tweens together
    tw.tween_property(node, "scale", Vector2.ONE, 0.2) \
      .set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
    tw.tween_property(node, "modulate:a", 1.0, 0.2)   # sub-property via ":"

注意点

• AnimationTree.active が false のまま → アニメーションが再生されず、travel() を呼び出しても何も起きないように見えます。active = true を設定し、anim_player のパスを割り当ててください。
• パラメーターのパスが間違っている。 ブレンド／条件のパスは "parameters/<NodeName>/..." で、ツリー内のノード名と正確に一致させる必要があります（例："parameters/playback"、 "parameters/Move/blend_position"）。タイプミスがあってもエラーにならず、何も起きません。
• AnimationPlayer と AnimationTree が競合する。 AnimationTree が有効なときは、同じトラックに対して AnimationPlayer.play() も呼び出さないでください。再生はツリーに任せます。
• 3.x の Tween ノードはなくなりました。 4.x では追加できる Tween ノードはありません。コード内で create_tween() を使ってトゥイーンを作成してください（Tween を返します）。トゥイーンは自動的に開始し、自身を解放します。
• 完了したトゥイーンを再利用する。 トゥイーンは一度だけ実行されます。新しいアニメーションには、再度 create_tween() を呼び出してください。繰り返す場合は set_loops() を使います。
• yield／yield(anim, "...") はなくなりました。 await anim.animation_finished を使います。
• サブプロパティのトゥイーンではコロンを使います："modulate:a"、"position:x"。プロパティ全体をトゥイーンすると、兄弟プロパティが上書きされます。

参考資料

• ステートマシンの遷移／条件、ルートモーション、ワンショット／ブレンドノード、メソッドトラックとコールトラック、SpriteFrames／AnimatedSprite2D、Tween のイージング／連結／コールバックについては、 references/animation-tree-and-tween.md を参照してください。

関連スキル

• godot-2d-movement — アニメーションを選択する速度／状態を提供します。
• godot-ui-control — Tween でアニメーションさせる UI です。
• godot-3d-essentials — AnimationTree で動かす 3D キャラクターシーンです。
• game-ai — アニメーション状態に対応するステートマシンです。