1. Introductionはじめに

AnimationTree is Godot 4's system for complex animation blending and state transitions. If you have ever tried to manage multiple animations with AnimationPlayer.play() calls scattered throughout your code, you know how quickly it becomes unmanageable. AnimationTree solves this with a visual graph of states and transitions.

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

Despite being incredibly powerful, AnimationTree's official documentation is sparse and often leaves developers guessing. This guide walks through everything from basic setup to advanced blend trees, with real GDScript code you can copy into your project.

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

2. Prerequisites前提条件

Before setting up your AnimationTree, you need:

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

• An AnimationPlayer node with at least Idle, Walk, Run, and Jump animations already created
• Idle、Walk、Run、Jumpなどのアニメーションが作成済みのAnimationPlayerノード
• The AnimationPlayer must be a sibling or child of the node where you add the AnimationTree (typically both are children of your character root node)
• AnimationPlayerはAnimationTreeを追加するノードの兄弟または子である必要があります（通常、両方ともキャラクターのルートノードの子です）
• Godot 4.x (this guide uses Godot 4 API — the AnimationTree API changed significantly from Godot 3)
• Godot 4.x（このガイドはGodot 4のAPIを使用しています — AnimationTreeのAPIはGodot 3から大きく変更されました）

3. Basic Setup基本セットアップ

Setting up an AnimationTree takes four steps:

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

1. Add an AnimationTree nodeAnimationTreeノードを追加 — Add it as a child of your character (e.g., CharacterBody2D or CharacterBody3D), alongside your AnimationPlayer. — AnimationPlayerと並べて、キャラクター（例：CharacterBody2DまたはCharacterBody3D）の子として追加します。
2. Set anim_playeranim_playerを設定 — In the Inspector, point the "Anim Player" property to your AnimationPlayer node. — インスペクターで「Anim Player」プロパティをAnimationPlayerノードに向けます。
3. Set tree_roottree_rootを設定 — Click the "Tree Root" property in the Inspector and create a new AnimationNodeStateMachine. — インスペクターの「Tree Root」プロパティをクリックして、新しいAnimationNodeStateMachineを作成します。
4. Set active = trueactive = trueに設定 — Check the "Active" checkbox in the Inspector, or set it in code. — インスペクターで「Active」チェックボックスをオンにするか、コードで設定します。

Your scene tree should look like this:

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

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. State Machine Basicsステートマシンの基本

A state machine in AnimationTree works on a simple concept: states represent animations, and transitions define the conditions for switching between them.

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

Adding States

状態の追加

Once your AnimationTree's tree_root is an AnimationNodeStateMachine, double-click it in the Inspector to open the state machine editor:

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

1. Right-click in the graph area and select Add Animation
2. グラフエリアを右クリックし、Add Animationを選択
3. Choose an animation from your AnimationPlayer (Idle, Walk, Run, Jump, etc.)
4. AnimationPlayerからアニメーションを選択（Idle、Walk、Run、Jumpなど）
5. Repeat for each animation state you need
6. 必要な各アニメーション状態に対して繰り返します

Adding Transitions

トランジションの追加

To create a transition between two states:

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

1. Click on the source state node
2. ソースの状態ノードをクリック
3. Drag to the destination state to create a transition arrow
4. デスティネーションの状態にドラッグしてトランジション矢印を作成
5. Click the transition arrow to configure it in the Inspector
6. トランジション矢印をクリックしてインスペクターで設定

Transition Properties

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

A typical setup for a platformer character:

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

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. Controlling the State Machine from Codeコードからステートマシンを制御する

There are two main ways to drive the state machine: setting condition parameters (automatic transitions) and calling travel() (manual transitions). You can mix both approaches.

ステートマシンを駆動する方法は主に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() vs Conditionsと条件の使い分け

Condition-Based (Recommended for Locomotion)

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

Set boolean parameters each frame and let the transitions fire automatically. This is more declarative and keeps your code clean. The state machine handles transition logic, crossfades, and edge cases for you.

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

# 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() (Recommended for One-Off Actions)

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

travel() requests a state transition. It respects transition rules — if no valid path exists from the current state to the target, the call is ignored. This makes it safe to call repeatedly. Use it for one-off triggers like attacks, emotes, or cutscene animations.

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. Blend Treesブレンドツリー

Blend trees allow you to smoothly interpolate between multiple animations based on a continuous value, rather than hard-switching between discrete states. This is perfect for walk/run speed blending and directional movement.

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

BlendSpace1D

A 1D blend between two or more animations along a single axis. Common use: blending Walk and Run based on movement speed.

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

In the editor, create a BlendSpace1D node inside your state machine (or as a standalone tree root). Add animation points:

エディタで、ステートマシン内（またはスタンドアロンのツリールートとして）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

A 2D blend using two axes. Perfect for 8-directional movement or top-down games where the character can move in any direction.

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. Common Node Types主要なノードタイプ

AnimationTree supports several node types that can be combined to create complex animation behavior:

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

9. OneShot Pattern (Attacks, Emotes)OneShotパターン（攻撃・エモート）

The OneShot node is one of the most useful patterns in AnimationTree. It plays a one-time animation on top of your base animation (like playing an attack swing while walking), then automatically returns to the base animation.

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

Setup in BlendTree

BlendTree内のセットアップ

To use OneShot, your AnimationTree root (or a state within it) needs to be a 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.

Triggering from Code

コードからのトリガー

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 Request Constants

OneShotリクエスト定数

10. Practical Example: Full Character Controller実践例：完全なキャラクターコントローラー

Here is a complete 2D platformer character script that combines state machine locomotion with a OneShot attack. This is a production-ready pattern you can adapt to your own project.

ステートマシンによる移動と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. Troubleshootingトラブルシューティング