🧭 三种核心组织方式：先选对“大脑”

AnimationTree 的根节点决定了它的调度方式，最常用的是以下三种：

实际项目中，状态机与混合空间通常是嵌套配合的：状态机负责“当前处于什么大状态”（如 Locomotion），而该状态内部的具体方向或速度变化，交给嵌套的 BlendSpace2D 处理。

⚙️ 前置设置：两步让树跑起来

在写任何代码之前，AnimationTree 需要两个明确的配置，否则它不会驱动任何东西：

1. anim_player 指向数据源：在检查器中将 AnimationTree 的 anim_player 属性指向场景中已有的 AnimationPlayer。
2. active = true：AnimationTree 默认不激活，必须在检查器中勾选，或在 _ready() 中设置 active = true。

🧩 示例一：最简状态机 —— travel() 事件驱动

适用场景：由代码逻辑直接命令的状态切换，如跳跃、攻击、死亡。

树的结构（在 AnimationTree 编辑器中创建 AnimationNodeStateMachine，添加状态并连线）：

1
2
3
4

StateMachine
├── Idle
├── Walk
└── Jump

关键代码：状态机播放控制器通过 playback 参数获取，travel() 会立即中断当前状态并转向目标状态，并自动寻找最短路径。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

extends CharacterBody2D

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

func _physics_process(_delta: float) -> void:
    var input_dir := Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
    var target_state: String

    if Input.is_action_just_pressed("jump"):
        state_machine.travel("Jump")
        return  # 这一帧不再处理移动状态，让跳跃优先

    if input_dir != Vector2.ZERO:
        target_state = "Walk"
    else:
        target_state = "Idle"

    # 避免每帧重复 travel 同一状态（travel 到当前状态通常不会重置）
    if state_machine.get_current_node() != target_state:
        state_machine.travel(target_state)

要点：travel() 适合事件（一次性、需要立即打断当前动作的情况）；对于 idle ↔ walk 这类连续状态，下一节的“条件驱动”是更稳健的选择。

🧩 示例二：条件驱动状态切换 —— 声明式过渡

适用场景：idle ↔ walk 这类由持续状态（速度是否为零）决定的切换，不希望用命令式的 travel() 每帧去“推”。

树的结构：在状态机的过渡线（Transition）上，设置 Advance Condition，填入一个布尔参数名：

1
2

Idle → Walk 的过渡线：Advance Condition = "moving"
Walk → Idle 的过渡线：Advance Condition = "not_moving"

关键代码：每一帧写入条件参数，条件满足时状态机自动完成过渡。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

extends CharacterBody2D

@onready var anim_tree: AnimationTree = $AnimationTree

func _physics_process(_delta: float) -> void:
    var input_dir := Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
    var is_moving := input_dir.x != 0.0

    # 两个条件互斥，且每帧都写入，避免“残留 true”把状态机卡死
    anim_tree.set("parameters/moving", is_moving)
    anim_tree.set("parameters/not_moving", not is_moving)

两条铁律：每个条件每帧都要写入（残留的 true 会让状态机永远卡在一个状态）；条件之间应当互斥，否则过渡结果会取决于节点在编辑器中的顺序，行为不可预测。

🧩 示例三：BlendSpace2D 方向混合 —— 8 方向移动

适用场景：角色需要根据输入方向，在多个方向的动画之间连续插值，而不是硬切 8 个独立状态。

树的结构：在状态机内创建一个 Locomotion 状态，将该状态的内容设为 BlendSpace2D，并在 2D 平面上放置各方向的动画点：

关键代码：每一帧将输入方向写入 blend_position；停止移动时也要写入 Vector2.ZERO，否则角色会“停在最后一次的方向”上，看起来像 idle 动画出了 bug。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

extends CharacterBody2D

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

const SPEED := 200.0

func _physics_process(_delta: float) -> void:
    var input_dir := Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")

    # 方向混合：每一帧都写入，停止时写 Vector2.ZERO
    anim_tree.set("parameters/Locomotion/blend_position", input_dir.normalized())

    # 条件驱动 Idle ↔ Locomotion（假设过渡条件已设好）
    anim_tree.set("parameters/moving", input_dir != Vector2.ZERO)
    anim_tree.set("parameters/not_moving", input_dir == Vector2.ZERO)

    velocity = input_dir * SPEED
    move_and_slide()

BlendSpace2D 的坐标值不需要是单位长度，节点在混合时会自动归一化，但代码写入的坐标系必须与编辑器中放置动画点的坐标系一致。

🧩 示例四：OneShot 一次性叠加 —— 走路时开枪

适用场景：在基础动画（走/跑/待机）之上，短暂播放一个上半身或全身动作，播完后自动返回基础动画，不打断底层状态。

树的结构：将根节点改为 AnimationNodeBlendTree，放入一个 OneShot 节点，将基础动画接到 OneShot 的 in 端口，一次性动作（如 shoot）接到 shot 端口。

关键代码：通过 request 参数触发一次性动画；OneShot 会在播完后自动清除请求并回到 in 端口的基础动画。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

extends CharacterBody2D

@onready var anim_tree: AnimationTree = $AnimationTree

func _process(_delta: float) -> void:
    if Input.is_action_just_pressed("shoot"):
        # 触发一次性射击动画，播完后自动回到走路/待机
        anim_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE)

    if Input.is_action_just_pressed("melee"):
        # 另一种一次性动作，同样叠加在基础动画上
        anim_tree.set("parameters/MeleeOneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE)

如果需要在一次性动画尚未播完时强制打断，可以使用 ONE_SHOT_REQUEST_ABORT（硬切）或 ONE_SHOT_REQUEST_FADE_OUT（淡出中断）。

📋 参数路径速查

AnimationTree 的所有控制都通过字符串路径读写参数，路径由编辑器中的节点名称决定：

路径不匹配是 AnimationTree 最常见的“不工作”原因：检查器中的参数名必须与代码中的字符串完全一致（包括大小写和层级），否则设置会被静默忽略。

⚠️ 三个高频陷阱

① 条件残留：Advance Condition 对应的布尔参数如果某一帧没有被写入，它会保留上一帧的值。一个残留的 true 会让状态机永久卡死在某条过渡上。每个条件每帧都写入是唯一可靠的做法。

② travel() 与条件混用时的竞争：travel() 是“排队”执行的，而条件过渡在下一帧就会生效。如果先用 travel("Jump")，但下一帧条件驱动又把状态拉回 Locomotion，跳跃动画可能根本来不及播放。事件用 travel()，持续状态用条件，不要用条件去抢 travel() 刚设置的目标。

③ 忘记设置 active = true：AnimationTree 创建后默认不激活，即使 anim_player 已正确指向，它也不会输出任何动画。

💎 学习路径小结

从 travel() 驱动的事件状态机开始，把 idle → walk → jump 跑通；然后引入 Advance Condition 替代 travel() 来管理 idle ↔ walk；再在一个 Locomotion 状态内部嵌入 BlendSpace2D 处理方向；最后用 OneShot 解决“在移动中叠加动作”的需求。每一步都只增加一个概念，而不是一次性把所有节点类型堆上去——AnimationTree 的复杂度来自参数路径的精确性和条件逻辑的严谨性，而不是节点本身的数量。

🧱 先建立正确的场景结构

AnimationPlayer 继承自裸 Node，而不是 Node2D 或 Node3D。这意味着它不传递变换——如果把带有 2D/3D 变换的节点设为它的子节点，子节点不会继承父级的位移、旋转或缩放，视觉上会出现位置偏移或异常。

正确的结构是让 AnimationPlayer 与被动画的节点平级：

1
2
3

Player (CharacterBody2D)
├── Sprite2D
└── AnimationPlayer

AnimationPlayer 可以通过轨道路径驱动任意兄弟或子节点的属性：位置、旋转、缩放、modulate、visible、碰撞形状的 disabled 状态，甚至方法调用和音频播放。

🗂️ 轨道类型：不止是属性

在动画面板中点击“添加轨道”，你会看到多种类型。常用的是以下四种：

方法轨道的关键配置：默认的调用模式是 CALL_MODE_CONTINUOUS，在关键帧前后拖拽播放头时可能每帧重复触发。对于“伤害判定只该发生一次”的逻辑，必须在代码中将调用模式设为 CALL_MODE_DISCRETE，确保函数在越过关键帧时只执行一次。

▶️ 代码控制：播放、混合与队列

基础播放与状态驱动

1
2
3
4
5
6
7
8

@onready var anim_player: AnimationPlayer = $AnimationPlayer

func _physics_process(_delta: float) -> void:
    var input_dir := Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
    if input_dir != Vector2.ZERO:
        anim_player.play("walk")
    else:
        anim_player.play("idle")

一个重要的细节：对正在播放的同一动画重复调用 play() 不会重新开始，也不会报错。因此可以在 _physics_process 中放心地每帧调用 play()，根据状态切换动画。

常用控制方法速查

1
2
3
4
5
6
7
8

anim_player.play("attack")                # 正向播放
anim_player.play_backwards("attack")      # 反向播放
anim_player.queue("idle")                 # 当前动画结束后自动播放下一个
anim_player.stop()                        # 立即停止
anim_player.pause()                       # 暂停在当前帧
anim_player.play()                        # 从暂停位置恢复
anim_player.speed_scale = 2.0             # 加速播放
anim_player.seek(0.5)                     # 跳转到 0.5 秒处

queue() 是串联动画的轻量方式：先播放 attack，attack 播完后自动进入 idle，不需要手动等待信号。

平滑过渡：利用混合时间

play() 的第二个参数控制混合时间，让两段动画之间交叉淡入淡出，而不是硬切换：

1
2

# 在 0.2 秒内从当前动画混合过渡到 run
anim_player.play("run", 0.2)

如果不传这个参数，Godot 会使用动画面板中“编辑过渡”（Edit Transitions）里为每对动画预设的混合时间。对于 idle ↔ walk 这类频繁切换的状态，设置 0.1–0.2 秒的混合时间能显著提升手感。

🎬 方法轨道：把逻辑事件焊在时间线上

属性轨道管“视觉”，方法轨道管“事件”。例如在攻击动画的第 0.3 秒生成伤害判定：

在编辑器中添加一条方法轨道，路径指向挂有目标脚本的节点，在第 0.3 秒插入关键帧并填入方法名 spawn_hitbox。然后在代码中确保调用模式为单次触发：

1
2
3
4
5
6
7

# 在 _ready() 或动画准备阶段，将方法轨道设为 DISCRETE
func _ready() -> void:
    var anim := anim_player.get_animation("attack")
    for i in anim.get_track_count():
        if anim.track_get_type(i) == Animation.TYPE_METHOD:
            anim.track_set_call_mode(i, Animation.CALL_MODE_DISCRETE)
            break

被调用的函数必须存在于目标节点上：

1
2
3
4

func spawn_hitbox() -> void:
    # 生成伤害区域、播放特效等，只会执行一次
    var hitbox := preload("res://hitbox.tscn").instantiate()
    add_child(hitbox)

如果需要在播放中途动态改变调用的方法或参数，方法轨道的关键帧值本身是一个字典 { "method": "函数名", "args": [...] }，可以在运行时通过 track_insert_key 替换。

📚 动画库：组织多个动画

一个 AnimationPlayer 可以保存多条动画。出于复用性考虑，动画被注册在 AnimationLibrary 资源中。如果你直接新建动画而不指定库，它会进入默认的 [Global] 库，直接 play("idle") 即可。

当动画数量增多时，按用途分库会更清晰：

1
2
3
4
5
6

# 运行时加载额外的动画库
var combat_lib: AnimationLibrary = load("res://animations/combat_lib.tres")
anim_player.add_animation_library("combat", combat_lib)

# 播放指定库中的动画
anim_player.play("combat/slash")

分库的好处是按需加载：基础移动动画可以常驻，战斗动画库只在进入战斗时加载，减少内存占用。

⚠️ 两个必须避开的坑

① 不要给根节点直接添加动画

动画中的 position 是相对于父节点的坐标。如果直接给场景根节点打位置关键帧，当这个场景被实例化到另一个场景中时，动画会以新的父节点位置作为原点，导致节点“跳”到错误的位置。解决办法是给场景加一个空白根节点，把原来的内容包进去，动画只作用于内部的子节点。

② 移动或重命名节点后，轨道可能失效

AnimationPlayer 的轨道路径是节点路径字符串。如果你在创建动画后移动或重命名了被动画的节点，轨道路径不会自动更新，播放时会出现“Node not found”错误，属性不再被驱动。双击轨道可以手动编辑路径，或者在调整场景结构后重新绑定轨道。

🧩 完整可运行示例：带过渡的移动状态机

将以下脚本挂在一个 CharacterBody2D 上，确保场景中有一个 AnimationPlayer 包含 idle 和 walk 两条动画：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

extends CharacterBody2D

@onready var anim_player: AnimationPlayer = $AnimationPlayer

const SPEED := 200.0
const BLEND_TIME := 0.15

func _physics_process(_delta: float) -> void:
    var input_dir := Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")

    if input_dir != Vector2.ZERO:
        velocity = input_dir * SPEED
        # 如果当前不在 walk，用 0.15 秒混合进入
        if anim_player.current_animation != "walk":
            anim_player.play("walk", BLEND_TIME)
    else:
        velocity = Vector2.ZERO
        if anim_player.current_animation != "idle":
            anim_player.play("idle", BLEND_TIME)

    move_and_slide()

这个示例的关键在于用 current_animation 判断是否需要切换，避免每帧重复调用 play() 导致混合反复重置。BLEND_TIME 让 idle 和 walk 之间平滑交叉淡化，而不是生硬跳变。

AnimationPlayer 的强项是时间轴编排——一旦你把关键帧、方法轨道和混合时间配置好，代码端只需要关心“何时切换到哪条动画”，决策逻辑可以保持得非常薄。当你需要状态机或方向混合空间时，AnimationTree 才是下一步的升级，而 AnimationPlayer 始终是它背后的数据底座。

🧱 先建立正确的心智模型

使用 Tween 时，有几个前置规则需要先刻在脑子里：

① 必须用 create_tween() 创建

Tween.new() 是无效的，不能用来做补间。正确的入口只有两个：

1
2
3
4
5

# 方式一：从节点创建，Tween 会绑定到该节点的生命周期
var tween = create_tween()

# 方式二：从场景树创建，不绑定特定节点
var tween = get_tree().create_tween()

② Tween 本质上是一条“时间线”

你往这条时间线上添加的每一个 tween_property()、tween_callback()、tween_interval()，都是一个 Tweener。默认情况下，这些 Tweener 会按添加顺序一个接一个地串行执行。

③ 默认是串行，set_parallel(true) 可以改为并行

这是控制 Tween 行为最关键的一个开关，后面会用具体示例展开。

✂️ 核心 API：你只需要先掌握这几个

🍳 常用可运行示例

以下示例均假设脚本挂在某个节点上，可以直接复制到 _ready() 或按钮回调中运行。

示例 1：基础位移 —— 让节点滑到指定位置

1
2
3
4
5

func _ready() -> void:
    var tween = create_tween()
    tween.tween_property(self, "position", Vector2(400, 300), 1.0)
        .set_trans(Tween.TRANS_CUBIC)
        .set_ease(Tween.EASE_OUT)

set_trans(Tween.TRANS_CUBIC) 让运动带有“起步快、收尾缓”的节奏感，.set_ease(Tween.EASE_OUT) 表示缓出。常用的组合是 TRANS_CUBIC + EASE_OUT，对大多数 UI 动效都很自然。

示例 2：淡入 / 淡出（UI 最常用）

1
2
3
4
5
6

func fade_in(node: CanvasItem, duration := 0.3) -> void:
    node.modulate.a = 0.0
    create_tween().tween_property(node, "modulate:a", 1.0, duration)

func fade_out(node: CanvasItem, duration := 0.3) -> void:
    create_tween().tween_property(node, "modulate:a", 0.0, duration)

属性路径用 "modulate:a" 直接绑定到透明度分量，比操作整个 Color 更清晰。

示例 3：串行序列 —— 变红 → 缩小 → 释放

这是官方文档中的标准示例，展示了 Tween 的“时间线”本质：

1
2
3
4
5

func _ready() -> void:
    var tween = create_tween()
    tween.tween_property($Sprite, "modulate", Color.RED, 1.0)
    tween.tween_property($Sprite, "scale", Vector2.ZERO, 1.0)
    tween.tween_callback($Sprite.queue_free)

三个步骤严格按顺序执行：先变红，再缩小到零，最后调用 queue_free() 释放节点。

示例 4：延迟回调 —— 两秒后执行某个函数

1
2
3
4
5
6

func _ready() -> void:
    var tween = create_tween()
    tween.tween_callback(_on_delayed).set_delay(2.0)

func _on_delayed() -> void:
    print("2 秒后执行")

.set_delay(2.0) 让回调在加入时间线后等待 2 秒再执行，很适合替代手动的计时器来做简单的延迟逻辑。

示例 5：并行动画 —— 面板滑入的同时淡入

1
2
3
4
5
6
7
8

func show_panel(panel: Control) -> void:
    panel.modulate.a = 0.0
    panel.position.x = -200

    var tween = create_tween().set_parallel(true)
    tween.tween_property(panel, "position:x", 100.0, 0.4)
        .set_trans(Tween.TRANS_CUBIC).set_ease(Tween.EASE_OUT)
    tween.tween_property(panel, "modulate:a", 1.0, 0.4)

调用 set_parallel(true) 之后，后续添加的所有 Tweener 会同时开始，而不是排队执行。这是 UI 弹出动画最常用的模式：位移、透明度、缩放同时进行，整体感觉会更利落。

示例 6：并行结束后接回调 —— chain() 的用法

如果并行块结束后还需要执行一段串行逻辑，必须用 chain() 切回串行：

1
2
3
4
5

func popup_animation(node: Control) -> void:
    var tween = create_tween().set_parallel(true)
    tween.tween_property(node, "scale", Vector2(1.1, 1.1), 0.2)
    tween.tween_property(node, "modulate:a", 1.0, 0.2)
    tween.chain().tween_callback(_on_popup_ready)

chain() 的作用就是把“并行模式”关掉，恢复为串行，从而让后面的 tween_callback 等到前面的并行动画全部完成后才触发。

示例 7：无限循环的往返移动

1
2
3
4
5
6
7

func start_bobbing() -> void:
    var start_x := position.x
    var end_x := position.x + 100.0

    var tween = create_tween().set_loops() # 无限循环
    tween.tween_property(self, "position:x", end_x, 1.0).from(start_x)
    tween.tween_property(self, "position:x", start_x, 1.0).from(end_x)

set_loops() 不传参数表示无限循环。.from() 明确指定每段的起点，避免依赖属性当前值，让往返逻辑更可控。

示例 8：相对位移 —— as_relative() 的用法

1
2
3
4
5

func shake() -> void:
    var tween = create_tween()
    tween.tween_property(self, "position:x", 10.0, 0.05).as_relative()
    tween.tween_property(self, "position:x", -20.0, 0.05).as_relative()
    tween.tween_property(self, "position:x", 10.0, 0.05).as_relative()

.as_relative() 让目标值变成相对当前值的偏移量，非常适合做不需要关心绝对坐标的震动、抖动效果。

示例 9：弹性缩放 —— 按钮按压反馈

1
2
3
4
5
6

func press_feedback(button: Control) -> void:
    var tween = create_tween()
    tween.tween_property(button, "scale", Vector2(0.9, 0.9), 0.1)
    tween.tween_property(button, "scale", Vector2.ONE, 0.3)
        .set_trans(Tween.TRANS_ELASTIC)
        .set_ease(Tween.EASE_OUT)

先用很短的时间缩小，再用弹性缓动弹回原始大小，是按钮点击反馈中很常见的“Q 弹”手感。

示例 10：控制生命周期 —— 保存引用，随时终止

Tween 创建后会自动运行，但如果你需要中途取消（比如玩家在动画途中离开了状态），应当保存引用并调用 kill()：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

var _move_tween: Tween

func move_to(target: Vector2) -> void:
    if _move_tween and _move_tween.is_valid():
        _move_tween.kill()  # 先终止旧 Tween，避免多 Tween 争抢同一属性
    _move_tween = create_tween()
    _move_tween.tween_property(self, "position", target, 0.5)

func cancel_movement() -> void:
    if _move_tween and _move_tween.is_valid():
        _move_tween.kill()

一个重要的实践规则：不要用多个 Tween 同时驱动同一个属性，否则行为会变得不可预测。在启动新 Tween 之前，先 kill() 旧的引用。

🎚️ 缓动速查：set_trans 与 set_ease 怎么选

set_ease 和 set_trans 可以链式调用在单个 tween_property 上，也可以设置在 create_tween() 后作为整个 Tween 的默认值。

💎 总结

Tween 的学习曲线很短，关键是把三个概念分清楚：时间线是串行的（用 set_parallel 切换并行）、Tweener 是可链式配置的（.from()、.set_trans()、.set_delay() 都作用在单个步骤上）、Tween 对象本身是可终止的（保存引用，必要时 kill()）。把上面十个示例跑一遍，再组合出“并行位移+淡入，结束后回调”这类复合动效，你就能覆盖大多数日常需求了。

🗺️ 先看全景：你该在什么时候用什么？

社区里一条非常实用的“黄金法则”是：从 AnimationPlayer 开始；当你需要动画之间的混合、过渡或分层时，再引入 AnimationTree。

你的学习路径可以按照 Tween → AnimationPlayer → AnimationTree 的顺序推进，下面逐层展开。

🌱 第一层：Tween —— 代码里的“一次性动效”

Tween 是三者中最轻量的。它不活在场景树里，而是由代码通过 create_tween() 创建，专注于将某个属性从当前值平滑插值到目标值。

1
2
3
4
5

# 让节点在 1 秒内移动到 (500, 300)
var tween = create_tween()
tween.tween_property(self, "position", Vector2(500, 300), 1.0)
    .set_ease(Tween.EASE_OUT)
    .set_trans(Tween.TRANS_CUBIC)

核心心智模型：Tween 是“即用即走”的。如果只是一个按钮弹一下、一个面板滑进来，用它最直接，不需要在场景里挂节点，也不需要打开动画面板。

✂️ 第二层：AnimationPlayer —— 你的万能动画剪辑台

AnimationPlayer 是整个动画系统的数据基础。它本身是一个 Node，内部可以存放多条动画片段，每条动画由若干轨道组成，轨道上放置关键帧。

关键概念：轨道与关键帧

一条轨道绑定到“某个节点的某个属性”（例如 Sprite2D:position）。关键帧记录该属性在某一时刻的值；两个关键帧之间，引擎会自动插值，让属性平滑变化。

AnimationPlayer 远不止能做位移。它可以驱动检查器里几乎任何可插值的属性：颜色、透明度、碰撞形状的启用状态、着色器参数等等。

不止是属性：轨道类型全览

除了最常用的属性轨道，AnimationPlayer 还支持多种专用轨道，这是它成为“剪辑台”的关键：

方法轨道的一个重要细节：它默认的调用模式是 CONTINUOUS，在关键帧前后拖拽播放头时可能会反复触发。对于“伤害判定只该发生一次”的逻辑，应当在代码中将调用模式设为 CALL_MODE_DISCRETE，确保函数在越过关键帧时只执行一次。

⚠️ 一个必须避开的坑

不要将带有 2D/3D 变换的节点设为 AnimationPlayer 的直接子节点。因为 AnimationPlayer 继承自裸 Node，不传递变换，这会导致子节点的视觉表现异常。正确的结构是让 AnimationPlayer 与 Sprite2D 等节点平级，而不是成为它的父节点。

🧠 第三层：AnimationTree —— 状态机与混合的大脑

当你的动画需求从“播放一条片段”升级为“在多个片段之间智能切换和混合”时，AnimationTree 就该登场了。

它的基本结构是：AnimationTree 通过 anim_player 属性指向一个 AnimationPlayer，自身在运行时以参数的形式对外暴露控制接口。

两种核心组织方式：状态机 vs 混合空间

① 状态机 (AnimationNodeStateMachine) —— 管理“离散状态”的切换

适合 idle、walk、jump、attack 这类互斥状态。你在编辑器中画出状态节点和过渡连线，通过代码驱动状态迁移。

最常用的两种驱动方式：

• travel()：命令式切换。在 _physics_process 中根据游戏逻辑判断目标状态并调用。

  1 2	var playback = anim_tree.get("parameters/StateMachine/playback") playback.travel("Run")

• Advance Condition（推进条件）：声明式切换。在过渡线上设置一个布尔条件名，代码中设置该参数，条件满足时自动过渡。适合受击、死亡等事件驱动的切换。

此外，Auto Advance 可以用于连招链：Attack1 → Attack2 无需条件，前一段播完自动进入下一段。

② 混合空间 (BlendSpace1D / BlendSpace2D) —— 管理“连续变化”

适合方向和速度这类连续量。

• BlendSpace1D：单一参数驱动。例如用速度值在 walk 和 run 之间连续混合。

  1	anim_tree["parameters/BlendSpace1D/blend_position"] = inverse_lerp(walk_speed, run_speed, velocity.length())

• BlendSpace2D：二维向量驱动。将 8 个方向的动画放置在平面上的对应坐标，用输入方向向量直接驱动，实现8 方向移动的自然混合。

实际项目中，两者是配合使用的：状态机负责“当前该处于什么大状态”（比如 Locomotion 状态），而该状态内部的 walk/run 切换或方向混合则交给混合空间处理。

🦴 专项：骨骼动画（2D 与 3D）

2D 骨骼通过 Skeleton2D + Bone2D 层级实现。AnimationPlayer 对 Bone2D 的旋转属性打关键帧，即可驱动骨骼摆动。

如果需要程序化的肢体定位（比如让脚精确踩在斜坡上），可以使用 SkeletonModification2DTwoBoneIK。将 IK 目标点交给 Marker2D 或射线检测结果，骨骼链会自动解算姿态。

3D 动画的导入非常直接：从 Blender 等 DCC 工具导出 FBX/glTF 时勾选动画，导入 Godot 后，动画会自动收纳在生成场景的 AnimationPlayer 节点中。之后 AnimationTree 指向这个 AnimationPlayer 即可照常使用。

💎 总结：你的学习节奏

1. 先只用 Tween：所有“代码里顺手做一下”的动效，都用它完成，熟悉插值、缓动和链式调用。
2. 再掌握 AnimationPlayer：学会在动画面板里创建片段、添加属性轨道，并尝试方法轨道来把游戏逻辑事件绑定到时间线上。
3. 最后引入 AnimationTree：从一个简单的 idle/walk 状态机开始，逐步加入 BlendSpace2D 处理方向移动。记住那条法则——能用 AnimationPlayer 直接 play() 解决的，就不要用状态机。

Godot 动画系统的设计哲学是用可视化编辑器承载“编排”，用代码控制“决策”。当你把 AnimationPlayer 当作素材库、AnimationTree 当作决策层时，两者的分工就会变得非常清晰。