AnimationTree 狀態機
於 Godot 4

1. 簡介

AnimationTree 是 Godot 4 用於複雜動畫混合與狀態轉換的系統。如果你曾經試著用散落在整份程式碼中的 AnimationPlayer.play() 呼叫來管理多個動畫，你就會知道那有多快變得難以維護。AnimationTree 透過一張由狀態與轉場組成的視覺化圖表解決了這個問題。

儘管 AnimationTree 功能極為強大，官方文件卻相當單薄，常常讓開發者摸不著頭緒。本指南會帶你走過一切 – 從基本設定到進階的 Blend Tree – 並附上可直接複製到你專案中的真實 GDScript 程式碼。

2. 前置需求

在設定 AnimationTree 之前，你需要：

• 一個至少已建立 Idle、Walk、Run 與 Jump 動畫的 AnimationPlayer 節點
• AnimationPlayer 必須是你新增 AnimationTree 的那個節點的同層或子節點（通常兩者都是角色根節點的子節點）
• Godot 4.x（本指南使用 Godot 4 的 API — AnimationTree 的 API 相較於 Godot 3 有大幅變動）

3. 基本設定

設定一個 AnimationTree 分為四個步驟：

1. 新增一個 AnimationTree 節點 — 將它與 AnimationPlayer 並列，新增為角色（例如 CharacterBody2D 或 CharacterBody3D）的子節點。
2. 設定 anim_player — 在 Inspector 中將「Anim Player」屬性指向你的 AnimationPlayer 節點。
3. 設定 tree_root — 在 Inspector 中點按「Tree Root」屬性，並建立一個新的 AnimationNodeStateMachine。
4. 設定 active = true — 在 Inspector 中勾選「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）代表動畫，而轉場（transition）則定義在狀態間切換的條件。

新增狀態

一旦你的 AnimationTree 的 tree_root 是 AnimationNodeStateMachine，就在 Inspector 中對它按兩下以開啟狀態機編輯器：

1. 在圖表區域按右鍵，選擇 Add Animation
2. 從你的 AnimationPlayer 中選擇一個動畫（Idle、Walk、Run、Jump 等）
3. 對你需要的每個動畫狀態重複此步驟

新增轉場

要在兩個狀態之間建立轉場：

1. 點按來源狀態節點
2. 拖曳到目標狀態，以建立一個轉場箭頭
3. 點按該轉場箭頭，在 Inspector 中設定它

轉場屬性

平台跳躍類角色的典型設定：

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. 從程式碼控制狀態機

驅動狀態機主要有兩種方式：設定條件參數（自動轉場）與呼叫 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. Blend Tree

Blend Tree 讓你能依據一個連續數值在多個動畫之間平滑地內插，而不是在離散狀態間硬切換。這非常適合用於走路／奔跑速度的混合，以及具方向性的移動。

BlendSpace1D

沿單一軸在兩個或更多動畫之間的 1D 混合。常見用途：依據移動速度混合 Walk 與 Run。

在編輯器中，於你的狀態機內建立一個 BlendSpace1D 節點（或作為獨立的 tree root）。加入動畫點：

# 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

使用兩個軸的 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. 實戰範例：完整角色控制器

這裡是一份完整的 2D 平台跳躍角色腳本，結合了狀態機移動與一記 OneShot 攻擊。這是一套可用於正式產品的模式，你能依自己的專案加以調整。

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. 疑難排解