Godot 动画

动画节点选型：用引擎的 Animation 资源和 Tween，不手写插值器和曲线播放器。

范围

先查内置

做法

选型

AnimationPlayer

extends CharacterBody2D

@onready var _anim: AnimationPlayer = $AnimationPlayer

func _ready() -> void:
	_anim.animation_finished.connect(_on_animation_finished)
	_anim.play(&"attack")

func _on_animation_finished(anim_name: StringName) -> void:
	if anim_name == &"attack":
		_anim.play(&"idle")

• 动画存在 AnimationLibrary 里，一个播放器可挂多个库
• 默认库名为空，直接写动画名；命名库写 play(&"enemy/attack")
• 对正在播的同名动画再 play() 不重头，要重播先 stop() 或 seek(0.0, true)
• play() 下一次处理才生效，同帧要看到用 advance(0)
• animation_finished 对循环动画不发
• 循环由 Animation 的 loop_mode 在编辑器里设，运行时不改共享资源
• 淡入淡出用 playback_default_blend_time 或 set_blend_time()
• 播一段用 play_section() 或 play_section_with_markers() 4.4+，改区间用 set_section()
• 运行时建 Animation 只用于程序生成，常规动画在编辑器里做

RESET

名为 RESET 的动画，区分大小写，保存默认姿态，每条轨道只有 0 秒一个关键帧，不用来播放。点关键帧图标时编辑器会提示创建。

处理模式

AnimationMixer 上，AnimationPlayer 和 AnimationTree 共用：

• AnimationPlayer.set_process_callback 与 set_method_call_mode 已弃用

AnimationTree

设 anim_player，建 tree_root，active = true。之后播放器不再自己 play()。

extends CharacterBody2D

@onready var _tree: AnimationTree = $AnimationTree
@onready var _state: AnimationNodeStateMachinePlayback = _tree["parameters/Locomotion/playback"]

func _physics_process(_delta: float) -> void:
	_tree["parameters/Locomotion/Move/blend_position"] = velocity / 200.0
	if Input.is_action_just_pressed(&"attack"):
		_tree["parameters/Attack/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE
	if is_on_floor():
		_state.travel(&"Ground")

• 参数路径格式 parameters/<节点名>/<参数>，Inspector 的 Parameters 里悬停可见
• 上例 tree_root 是 BlendTree，含状态机 Locomotion 和 OneShot 节点 Attack
• Move 是 Locomotion 里的 BlendSpace2D 状态
• OneShot 放进 BlendTree，连 in 与 shot 两个输入
• 状态机直接做 tree_root 时路径是 parameters/playback
• Advance Mode 为 Auto 时才按条件自动走转场
• Advance Condition 只判断变量为 true，不能取反
• 取反和比较用 Advance Expression，区分大小写
• 表达式的变量来源由 advance_expression_base_node 指定
• travel() 沿转场图寻路，无路径直接跳
• 状态机须已运行：连了 Start，或先调 start()
• 转场 Priority 数值小的优先
• 动画节点是共享资源，参数按 AnimationTree 实例分开
• 运行时只改参数，不改节点资源
• 参数路径、状态机操作、OneShot、BlendSpace 见 references/animation-tree.md

Tween

extends Control

var _tween: Tween

func pop() -> void:
	if _tween:
		_tween.kill()
	pivot_offset = size / 2.0
	_tween = create_tween()
	_tween.tween_property(self, "scale", Vector2.ONE * 1.2, 0.08).set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
	_tween.tween_property(self, "scale", Vector2.ONE, 0.12)

• tween_method(callable, from, to, duration) 驱动 setter、数字滚动、shader 参数
• tween_callback() 调函数，tween_interval() 延时
• 单独当计时器：await create_tween().tween_interval(2.0).finished
• tween_subtween() 4.4+ 把另一个 Tween 当一步嵌入
• tween_await() 4.7+ 等信号再走下一步，配 set_timeout() 兜底：

extends Node2D

signal dialogue_closed

func cutscene() -> void:
	var tween := create_tween()
	tween.tween_property(self, "position:x", 600.0, 1.5)
	tween.tween_callback(print.bind("Hello"))
	tween.tween_await(dialogue_closed).set_timeout(30.0)
	tween.tween_property(self, "position:x", 0.0, 1.5)

• 打断重播、飘字、数字滚动、转场、手动推进见 references/tween-recipes.md

AnimatedSprite2D 与 AnimatedSprite3D

• 帧在 SpriteFrames 资源里，每个动画单独设 FPS 与循环
• SpriteFrames 面板导入图片或切 sprite sheet
• play(&"run")，speed_scale 整体变速
• animation_finished 对循环动画不发，animation_looped 才发
• frame_changed 做脚步声和判定
• 判定要和精灵帧同一时间线时，用 Sprite2D 的 frame 属性轨道加 AnimationPlayer
• 对正在播的同名动画再 play() 不重启，stop() 把 frame 归零
• SpriteFrames 是共享资源，独立改动先 duplicate()
• 既换帧又动骨骼，用 Sprite2D 的 hframes vframes frame 加 AnimationPlayer

命中闪白

shader_type canvas_item;

instance uniform float flash : hint_range(0.0, 1.0) = 0.0;

void fragment() {
	COLOR.rgb = mix(COLOR.rgb, vec3(1.0), flash);
}

extends Sprite2D

var _tween: Tween

func hit_flash() -> void:
	if _tween != null:
		_tween.kill()
	set_instance_shader_parameter(&"flash", 1.0)
	_tween = create_tween()
	_tween.tween_property(self, "instance_shader_parameters/flash", 0.0, 0.12)

• instance uniform 每个实例独立，同一材质的敌人不会一起闪
• 普通 uniform 改的是共享材质

确定性回放

锁步联机、回放要逐帧复现表现时：

• seek 只调用目标时刻前最近的一个方法键，不逐个触发
• 要逐个触发方法键用 advance
• seek 的 update_only 为 true 时方法和音频轨道都不处理，到末尾不发 animation_finished
• custom_step 走完的那次仍返回 true，判断结束用 finished 信号
• 动画只影响表现，模拟状态不读 AnimationPlayer 或 Tween 的值

曲线

外部来源

陷阱

参考

• references/csharp.md：C# 项目先读，本文各节示例的 C# 写法
• references/animation-tree.md：搭建顺序、参数路径、状态机操作、OneShot、BlendSpace、根运动
• references/tween-recipes.md：打断重播、飘字、数字滚动、转场、循环、Subtween、等信号、手动推进
• https://docs.godotengine.org/en/stable/tutorials/animation/index.html
• https://docs.godotengine.org/en/stable/tutorials/animation/animation_tree.html
• https://docs.godotengine.org/en/stable/tutorials/2d/2d_sprite_animation.html