godot-animation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Godot Animation (4.x)

Godot 动画（4.x）

Choose and drive the right animation tool:

AnimationPlayer

(clips),

AnimationTree

(blending/state machines), or

Tween

(short procedural moves). Targets Godot 4.3+.

选择并使用合适的动画工具：

AnimationPlayer

（片段动画）、

AnimationTree

（混合/状态机）或

Tween

（短流程移动动画）。适配**Godot 4.3+**版本。

When to use

使用场景

Use when playing keyframed animations, blending walk/run/idle states, animating a sprite sheet, or tweening UI/objects in code.

When not to use: the movement logic that decides which state to play →

godot-2d-movement

; UI layout (vs. UI tweening) →

godot-ui-control

; shader-driven effects →

godot-shaders

适用于播放关键帧动画、混合行走/奔跑/idle状态、制作精灵表动画，或通过代码为UI/对象添加补间动画的场景。

不适用于：决定播放哪个状态的移动逻辑 → 参考

godot-2d-movement

；UI布局（而非UI补间动画）→ 参考

godot-ui-control

；着色器驱动的特效 → 参考

godot-shaders

。

Core workflow

核心工作流程

Pick the tool:
- ```
AnimationPlayer
```
  — author keyframed clips (transforms, properties, method calls, audio, even other animations). The source of truth for clip data.
- ```
AnimationTree
```
  — blend and transition between those clips at runtime with a state machine and/or blend spaces. Needs an
```
AnimationPlayer
```
  to pull clips from.
- ```
Tween
```
  — fire-and-forget procedural interpolation in code (
```
create_tween()
```
  ); ideal for UI pops, fades, and one-off moves.
For 2D sprite sheets: use
```
AnimatedSprite2D
```
+
```
SpriteFrames
```
, or keyframe the
```
frame
```
property in an
```
AnimationPlayer
```
.

For characters: build clips in

AnimationPlayer

, then add an

AnimationTree

(

active = true

), set its

anim_player

, and design an

AnimationNodeStateMachine

AnimationNodeBlendSpace2D

as the tree root.

Drive transitions from code via the playback object (
```
travel
```
) or by setting blend parameters.
React to clip events with the
```
animation_finished
```
signal and call/method tracks.

选择工具：
- ```
AnimationPlayer
```
  — 制作关键帧片段动画（变换、属性、方法调用、音频，甚至其他动画），是片段动画数据的权威来源。
- ```
AnimationTree
```
  — 在运行时通过状态机和/或混合空间混合并切换这些片段动画，需要从
```
AnimationPlayer
```
  获取片段动画数据。
- ```
Tween
```
  — 通过代码中的
```
create_tween()
```
  实现一次性流程插值动画；非常适合UI弹出、淡入淡出和一次性移动效果。
2D精灵表动画：使用
```
AnimatedSprite2D
```
+
```
SpriteFrames
```
，或在
```
AnimationPlayer
```
中为
```
frame
```
属性设置关键帧。
角色动画：在
```
AnimationPlayer
```
中制作片段动画，然后添加
```
AnimationTree
```
（设置
```
active = true
```
），指定其
```
anim_player
```
，并将
```
AnimationNodeStateMachine
```
或
```
AnimationNodeBlendSpace2D
```
设为树的根节点。
通过代码驱动切换：通过播放对象（
```
travel
```
方法）或设置混合参数实现。
响应片段动画事件：使用
```
animation_finished
```
信号和调用/方法轨道。

Patterns

实践模式

1. AnimationPlayer: play a clip and await it

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

gdscript

@onready var anim: AnimationPlayer = $AnimationPlayer

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

gdscript

@onready var anim: AnimationPlayer = $AnimationPlayer

func attack() -> void:
    anim.play("attack")
    await anim.animation_finished     # 片段动画结束后继续执行
    anim.play("idle")

2. AnimationTree state machine: travel between states

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

gdscript

@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")

gdscript

@onready var tree: AnimationTree = $AnimationTree

func _ready() -> void:
    tree.active = true                # 由树驱动动画；AnimationPlayer是数据源

func set_state(state: StringName) -> void:
    # 播放对象控制AnimationNodeStateMachine根节点
    var sm: AnimationNodeStateMachinePlayback = tree.get("parameters/playback")
    sm.travel(state)                  # 通过图中的连接进行状态切换

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

3. Blend space: blend run direction by a 2D parameter

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

gdscript

undefined

gdscript

undefined

Root is an AnimationNodeBlendSpace2D named "Move" with idle/run points placed in it.

根节点是名为"Move"的AnimationNodeBlendSpace2D，其中包含idle/run动画点

func update_locomotion(input_dir: Vector2) -> void: # Parameter path = "parameters/<node name>/blend_position". tree.set("parameters/Move/blend_position", input_dir)

undefined

func update_locomotion(input_dir: Vector2) -> void: # 参数路径 = "parameters/<节点名称>/blend_position" tree.set("parameters/Move/blend_position", input_dir)

undefined

4. Tween: fade and scale a UI element (code-driven)

4. Tween：为UI元素添加淡入和缩放效果（代码驱动）

gdscript

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 ":"

gdscript

func pop_in(node: Control) -> void:
    node.scale = Vector2.ZERO
    node.modulate.a = 0.0
    var tw := create_tween()                          # 绑定到当前节点的树
    tw.set_parallel(true)                             # 同时运行两个补间动画
    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)   # 通过":"指定子属性

Pitfalls

常见陷阱

AnimationTree.active
left false → nothing animates and
```
travel()
```
appears to do nothing. Set
```
active = true
```
and assign the
```
anim_player
```
path.
Wrong parameter path. Blend/condition paths are
```
"parameters/<NodeName>/..."
```
and must match the node names in the tree exactly (e.g.
```
"parameters/playback"
```
,
```
"parameters/Move/blend_position"
```
). A typo silently no-ops.
AnimationPlayer and AnimationTree fighting. When an
```
AnimationTree
```
is active, don't also call
```
AnimationPlayer.play()
```
for the same tracks — let the tree own playback.
3.x Tween node is gone. There is no
```
Tween
```
node to add in 4.x; create tweens in code with
```
create_tween()
```
(which returns a
```
Tween
```
). They auto-start and free themselves.
Reusing a finished tween. A tween is one-shot; call
```
create_tween()
```
again for a new animation. Use
```
set_loops()
```
for repetition.

yield
/
yield(anim, "...")
is gone. Use

await anim.animation_finished

Sub-property tweens use a colon:
```
"modulate:a"
```
,
```
"position:x"
```
. Tweening the whole property instead overwrites siblings.

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"
```
。如果补间整个属性，会覆盖其他子属性。

References

参考资料

For state machine transitions/conditions, root motion, one-shot/blend nodes, method & call tracks,
```
SpriteFrames
```
/
```
AnimatedSprite2D
```
, and Tween easing/chaining/callbacks, read
```
references/animation-tree-and-tween.md
```
.

关于状态机切换/条件、根运动、一次性/混合节点、方法与调用轨道、
```
SpriteFrames
```
/
```
AnimatedSprite2D
```
以及Tween的缓动/链式调用/回调，请阅读
```
references/animation-tree-and-tween.md
```
。

godot-animation

Original

Translation

Godot Animation (4.x)

Godot 动画（4.x）

When to use

使用场景

Core workflow

核心工作流程

Patterns

实践模式

1. AnimationPlayer: play a clip and await it

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

2. AnimationTree state machine: travel between states

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

3. Blend space: blend run direction by a 2D parameter

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

Root is an AnimationNodeBlendSpace2D named "Move" with idle/run points placed in it.

根节点是名为"Move"的AnimationNodeBlendSpace2D，其中包含idle/run动画点

4. Tween: fade and scale a UI element (code-driven)

4. Tween：为UI元素添加淡入和缩放效果（代码驱动）

Pitfalls

常见陷阱

References

参考资料

Related skills

相关技能