Godot 4のAnimationTree
ステートマシン完全ガイド

1. はじめに

AnimationTreeはGodot 4における複雑なアニメーションブレンディングと状態遷移のためのシステムです。AnimationPlayer.play()の呼び出しをコード中にばらまいて複数のアニメーションを管理しようとした経験があるなら、それがいかに早く手に負えなくなるかご存知でしょう。AnimationTreeはビジュアルな状態とトランジションのグラフでこの問題を解決します。

AnimationTreeは非常に強力であるにもかかわらず、公式ドキュメントは不十分で、開発者が手探りになることも少なくありません。このガイドでは、基本セットアップから高度なブレンドツリーまで、プロジェクトにそのままコピーできる実践的なGDScriptコードとともに全てを解説します。

2. 前提条件

AnimationTreeをセットアップする前に、以下が必要です：

• Idle、Walk、Run、Jumpなどのアニメーションが作成済みのAnimationPlayerノード
• AnimationPlayerはAnimationTreeを追加するノードの兄弟または子である必要があります（通常、両方ともキャラクターのルートノードの子です）
• Godot 4.x（このガイドはGodot 4のAPIを使用しています — AnimationTreeのAPIはGodot 3から大きく変更されました）

3. 基本セットアップ

AnimationTreeのセットアップは4ステップです：

1. AnimationTreeノードを追加 — AnimationPlayerと並べて、キャラクター（例：CharacterBody2DまたはCharacterBody3D）の子として追加します。
2. anim_playerを設定 — インスペクターで「Anim Player」プロパティをAnimationPlayerノードに向けます。
3. tree_rootを設定 — インスペクターの「Tree Root」プロパティをクリックして、新しいAnimationNodeStateMachineを作成します。
4. active = trueに設定 — インスペクターで「Active」チェックボックスをオンにするか、コードで設定します。

シーンツリーは以下のようになります：

CharacterBody2D (or CharacterBody3D)
  +-- Sprite2D (or Sprite3D)
  +-- CollisionShape2D
  +-- AnimationPlayer      <-- has Idle, Walk, Run, Jump animations
  +-- AnimationTree         <-- points to AnimationPlayer above

# Minimal code setup (usually done via the editor instead):
@onready var anim_tree: AnimationTree = $AnimationTree

func _ready() -> void:
    # If you set these in the Inspector, you don't need this code
    anim_tree.anim_player = ^"../AnimationPlayer"
    anim_tree.tree_root = AnimationNodeStateMachine.new()
    anim_tree.active = true

4. ステートマシンの基本

AnimationTreeのステートマシンはシンプルなコンセプトで動作します：状態（state）はアニメーションを表し、トランジションは状態間の切り替え条件を定義します。

状態の追加

AnimationTreeのtree_rootがAnimationNodeStateMachineに設定されたら、インスペクターでダブルクリックしてステートマシンエディタを開きます：

1. グラフエリアを右クリックし、Add Animationを選択
2. AnimationPlayerからアニメーションを選択（Idle、Walk、Run、Jumpなど）
3. 必要な各アニメーション状態に対して繰り返します

トランジションの追加

2つの状態間にトランジションを作成するには：

1. ソースの状態ノードをクリック
2. デスティネーションの状態にドラッグしてトランジション矢印を作成
3. トランジション矢印をクリックしてインスペクターで設定

トランジションのプロパティ

プラットフォーマーキャラクターの典型的なセットアップ：

Start --> Idle
Idle  --> Walk   (condition: is_moving)
Walk  --> Idle   (condition: is_idle)
Idle  --> Jump   (condition: is_jumping)
Walk  --> Jump   (condition: is_jumping)
Jump  --> Fall   (condition: is_falling)
Fall  --> Idle   (condition: is_on_floor, switch_mode: Immediate)

5. コードからステートマシンを制御する

ステートマシンを駆動する方法は主に2つあります：条件パラメータの設定（自動トランジション）とtravel()の呼び出し（手動トランジション）です。両方のアプローチを組み合わせることもできます。

extends CharacterBody2D

@onready var anim_tree: AnimationTree = $AnimationTree
@onready var state_machine: AnimationNodeStateMachinePlayback = anim_tree.get("parameters/playback")

func _physics_process(delta: float) -> void:
    # ... movement logic here ...
    move_and_slide()
    _update_animation_parameters()

func _update_animation_parameters() -> void:
    # Approach 1: Set condition parameters — transitions fire automatically
    anim_tree.set("parameters/conditions/is_moving", velocity.length() > 10.0)
    anim_tree.set("parameters/conditions/is_idle", velocity.length() <= 10.0)
    anim_tree.set("parameters/conditions/is_on_floor", is_on_floor())
    anim_tree.set("parameters/conditions/is_jumping", velocity.y < 0 and not is_on_floor())
    anim_tree.set("parameters/conditions/is_falling", velocity.y > 0 and not is_on_floor())

    # Approach 2: Use travel() for direct control
    # if velocity.length() > 10.0:
    #     state_machine.travel("Walk")
    # else:
    #     state_machine.travel("Idle")

6. travel() と条件の使い分け

条件ベース（移動系に推奨）

毎フレームブールパラメータを設定し、トランジションを自動発火させます。より宣言的でコードがクリーンになります。ステートマシンがトランジションロジック、クロスフェード、エッジケースを処理します。

# Declarative: just describe the current state of the world
anim_tree.set("parameters/conditions/is_moving", velocity.length() > 10.0)
anim_tree.set("parameters/conditions/is_on_floor", is_on_floor())

travel()（単発アクションに推奨）

travel()は状態遷移をリクエストします。トランジションルールを尊重するため、現在の状態からターゲットへの有効なパスがなければ呼び出しは無視されます。繰り返し呼んでも安全です。攻撃、エモート、カットシーンアニメーションなどの単発トリガーに使用します。

# travel() — requests a transition (respects transition rules)
state_machine.travel("Jump")

# Get current state name
var current: StringName = state_machine.get_current_node()
print(current)  # "Idle", "Walk", etc.

# Check if travel is possible
var is_playing: bool = state_machine.is_playing()
print(is_playing)

7. ブレンドツリー

ブレンドツリーは、離散的な状態間のハードスイッチではなく、連続値に基づいて複数のアニメーション間をスムーズに補間できます。歩行/走行速度のブレンドや方向移動に最適です。

BlendSpace1D

単一軸に沿った2つ以上のアニメーション間の1Dブレンド。一般的な使用例：移動速度に基づくWalkとRunのブレンド。

エディタで、ステートマシン内（またはスタンドアロンのツリールートとして）BlendSpace1Dノードを作成します。アニメーションポイントを追加：

# BlendSpace1D setup (in editor):
# Point 0.0 = Walk animation
# Point 1.0 = Run animation

# Control from code:
var speed_factor: float = clamp(velocity.length() / max_speed, 0.0, 1.0)
anim_tree.set("parameters/WalkRun/blend_position", speed_factor)

BlendSpace2D

2軸を使った2Dブレンド。8方向移動やキャラクターが任意の方向に移動できるトップダウンゲームに最適です。

# BlendSpace2D setup (in editor):
# Place animations at positions:
#   Idle at (0, 0)
#   WalkRight at (1, 0), WalkLeft at (-1, 0)
#   WalkUp at (0, -1), WalkDown at (0, 1)
#   Diagonals at corners

# Control from code:
var input_dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
anim_tree.set("parameters/Movement/blend_position", input_dir)

8. 主要なノードタイプ

AnimationTreeは複数のノードタイプをサポートし、組み合わせることで複雑なアニメーション動作を作成できます：

9. OneShotパターン（攻撃・エモート）

OneShotノードはAnimationTreeで最も有用なパターンの一つです。ベースアニメーションの上にワンタイムアニメーションを再生し（歩行中に攻撃スイングを再生するなど）、終了後に自動的にベースアニメーションに戻ります。

BlendTree内のセットアップ

OneShotを使うには、AnimationTreeのルート（またはその中の状態）がBlendTreeである必要があります：

# BlendTree graph setup:
#
#   [StateMachine] ---> [OneShot "AttackOneShot"] ---> [Output]
#   (base locomotion)      ^
#                          |
#                   [Animation "Attack"]
#                   (shot input)
#
# The StateMachine provides the base (idle/walk/run).
# The Attack animation is connected to the OneShot's "shot" input.

コードからのトリガー

extends CharacterBody2D

@onready var anim_tree: AnimationTree = $AnimationTree

func _input(event: InputEvent) -> void:
    if event.is_action_pressed("attack"):
        _play_attack()

func _play_attack() -> void:
    # Fire the one-shot animation
    anim_tree.set(
        "parameters/AttackOneShot/request",
        AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE
    )

func _process(delta: float) -> void:
    # Check if the one-shot is currently active
    var is_attacking: bool = anim_tree.get("parameters/AttackOneShot/active")
    if is_attacking:
        # Optionally disable movement during attack
        pass

OneShotリクエスト定数

10. 実践例：完全なキャラクターコントローラー

ステートマシンによる移動とOneShot攻撃を組み合わせた、完全な2Dプラットフォーマーキャラクタースクリプトです。プロジェクトに合わせて応用できる実用的なパターンです。

extends CharacterBody2D

const SPEED := 200.0
const JUMP_VELOCITY := -350.0
const SPRINT_MULTIPLIER := 1.6

@onready var anim_tree: AnimationTree = $AnimationTree
@onready var playback: AnimationNodeStateMachinePlayback = anim_tree.get("parameters/playback")
@onready var sprite: Sprite2D = $Sprite2D

var gravity: float = ProjectSettings.get_setting("physics/2d/default_gravity")

func _ready() -> void:
    anim_tree.active = true

func _physics_process(delta: float) -> void:
    _apply_gravity(delta)
    _handle_jump()
    _handle_movement()
    move_and_slide()
    _update_animation()

func _apply_gravity(delta: float) -> void:
    if not is_on_floor():
        velocity.y += gravity * delta

func _handle_jump() -> void:
    if Input.is_action_just_pressed("jump") and is_on_floor():
        velocity.y = JUMP_VELOCITY

func _handle_movement() -> void:
    var direction := Input.get_axis("move_left", "move_right")
    var is_sprinting := Input.is_action_pressed("sprint")
    var current_speed := SPEED * (SPRINT_MULTIPLIER if is_sprinting else 1.0)

    if direction != 0.0:
        velocity.x = direction * current_speed
        sprite.flip_h = direction < 0.0
    else:
        velocity.x = move_toward(velocity.x, 0.0, SPEED)

func _update_animation() -> void:
    # Skip animation updates during attack
    var is_attacking: bool = anim_tree.get("parameters/AttackOneShot/active")
    if is_attacking:
        return

    if not is_on_floor():
        if velocity.y < 0:
            playback.travel("Jump")
        else:
            playback.travel("Fall")
    elif abs(velocity.x) > 10.0:
        if Input.is_action_pressed("sprint"):
            playback.travel("Run")
        else:
            playback.travel("Walk")
    else:
        playback.travel("Idle")

func _input(event: InputEvent) -> void:
    if event.is_action_pressed("attack") and is_on_floor():
        anim_tree.set(
            "parameters/AttackOneShot/request",
            AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE
        )

11. トラブルシューティング