AnimationTree 状态机
Godot 4 完全指南

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 需要四个步骤：

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）代表动画，而过渡（transition）定义了在它们之间切换的条件。

添加状态

一旦你的 AnimationTree 的 tree_root 变成了 AnimationNodeStateMachine，就在检查器中双击它打开状态机编辑器：

1. 在图表区域右键点击并选择 Add Animation
2. 从你的 AnimationPlayer 中选择一个动画（Idle、Walk、Run、Jump 等）
3. 对每一个你需要的动画状态重复上述操作

添加过渡

要在两个状态之间创建过渡：

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. 从代码控制状态机

驱动状态机主要有两种方式：设置条件参数（自动过渡）和调用 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

沿单一轴在两个或多个动画之间进行 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

使用两个轴进行 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. 故障排查