godot-animation

Godot 动画（4.x）

选择并驱动合适的动画工具：AnimationPlayer（片段）、AnimationTree （混合／状态机）或 Tween（短时程序化动作）。目标版本为 Godot 4.7。

适用场景

• 用于播放关键帧动画、混合行走／奔跑／待机状态、制作精灵表动画，或在代码中为 UI／对象添加补间动画。

**不适用场景：**决定播放哪个状态的移动 逻辑 → godot-2d-movement；UI 布局（而非 UI 补间动画）→ godot-ui-control；着色器驱动的效果 → godot-shaders。

核心工作流

1. 选择工具：
   • AnimationPlayer — 制作关键帧动画片段（变换、属性、方法调用、音频，甚至其他动画）。它是片段数据的唯一事实来源。
   • AnimationTree — 在运行时通过状态机和／或混合空间混合这些片段并在片段间切换。需要从 AnimationPlayer 获取片段。
   • Tween — 在代码中创建即发即弃的程序化插值（create_tween()）；适合 UI 弹出、淡入淡出和一次性动作。
2. **对于 2D 精灵表：**使用 AnimatedSprite2D + SpriteFrames，或在 AnimationPlayer 中为 frame 属性设置关键帧。
3. **对于角色：**在 AnimationPlayer 中制作片段，然后添加 AnimationTree（active = true），设置其 anim_player，并将 AnimationNodeStateMachine 或 AnimationNodeBlendSpace2D 设计为树根节点。
4. 从代码驱动状态切换：通过播放对象（travel）或设置混合参数。
5. 响应片段事件：使用 animation_finished 信号以及调用／方法轨道。

模式

1. AnimationPlayer：播放片段并等待其结束

@onready var anim: AnimationPlayer = $AnimationPlayer

func attack() -> void:
    anim.play("attack")
    await anim.animation_finished     # resume after the clip ends
    anim.play("idle")

2. AnimationTree 状态机：在状态间切换

@onready var tree: AnimationTree = $AnimationTree

func _ready() -> void:
    tree.active = true                # the tree drives animation; AnimationPlayer is the source

func set_state(state: StringName) -> void:
    # The playback object controls an AnimationNodeStateMachine root.
    var sm: AnimationNodeStateMachinePlayback = tree.get("parameters/playback")
    sm.travel(state)                  # transitions using the graph's connections

func _physics_process(_d: float) -> void:
    set_state(&"run" if velocity.length() > 5.0 else &"idle")

3. 混合空间：通过 2D 参数混合奔跑方向

# Root is an AnimationNodeBlendSpace2D named "Move" with idle/run points placed in it.
func update_locomotion(input_dir: Vector2) -> void:
    # Parameter path = "parameters/<node name>/blend_position".
    tree.set("parameters/Move/blend_position", input_dir)

4. Tween：淡出并缩放 UI 元素（由代码驱动）

func pop_in(node: Control) -> void:
    node.scale = Vector2.ZERO
    node.modulate.a = 0.0
    var tw := create_tween()                          # bound to this node's tree
    tw.set_parallel(true)                             # run the two tweens together
    tw.tween_property(node, "scale", Vector2.ONE, 0.2) \
      .set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
    tw.tween_property(node, "modulate:a", 1.0, 0.2)   # sub-property via ":"

易错点

• AnimationTree.active 保持为 false → 不会播放任何动画，travel() 看起来也毫无效果。设置 active = true 并指定 anim_player 路径。
• 参数路径错误。 混合／条件路径的格式为 "parameters/<NodeName>/..."，必须与树中的节点名称完全一致（例如 "parameters/playback"、"parameters/Move/blend_position"）。拼写错误会被静默忽略。
• AnimationPlayer 和 AnimationTree 相互争用。 当 AnimationTree 处于激活状态时，不要同时对相同轨道调用 AnimationPlayer.play() — 让树负责播放。
• 3.x 的 Tween 节点已移除。 4.x 中不再有可添加的 Tween 节点；请在代码中使用 create_tween() 创建补间动画（它会返回一个 Tween）。补间动画会自动开始，并在结束后自动释放。
• 重复使用已结束的补间动画。 补间动画只能使用一次；要播放新动画，请再次调用 create_tween()。需要重复播放时请使用 set_loops()。
• yield／yield(anim, "...") 已移除。 请使用 await anim.animation_finished。
• 子属性补间动画使用冒号："modulate:a"、"position:x"。若对整个属性添加补间动画，则会覆盖其他子属性。

参考资料

• 有关状态机转换／条件、根运动、单次播放／混合节点、方法和调用轨道、SpriteFrames／AnimatedSprite2D，以及 Tween 缓动／串联／回调的内容，请阅读 references/animation-tree-and-tween.md。

相关技能

• godot-2d-movement — 提供用于选择动画的速度／状态。
• godot-ui-control — 提供由 Tween 添加动画的 UI。
• godot-3d-essentials — 使用 AnimationTree 驱动的 3D 角色场景。
• game-ai — 与动画状态相对应的状态机。