Godot 动画
选择工具
| 需求 | 使用 |
|---|---|
| 从代码触发的“发射后不管”动效(UI 弹出、击退、淡入淡出) | Tween (create_tween()) |
| 创作好的动画剪辑(行走循环、门、过场动画) | AnimationPlayer |
| 逐帧 2D 精灵 | AnimatedSprite2D + SpriteFrames,或 AnimationPlayer 关键化 Sprite2D.frame |
| 混合与状态逻辑(待机↔跑↔跳、八方向移动) | AnimationTree,配合状态机或混合空间 |
| 程序化骨骼瞄准、脚部放置、抓取 | SkeletonModifier3D 系列(IK、LookAt、约束) |
godot-mcp 动画工具
| 任务 | 工具 |
|---|---|
| 向场景添加 AnimationPlayer/AnimationTree 脚手架 | godot_animation_setup_scene |
| 创建、列出或读取动画剪辑 | godot_animation_create_clip、godot_animation_list_clips、godot_animation_read_clip |
| 添加或移除关键帧 | godot_animation_add_keyframe、godot_animation_remove_keyframe |
| 规划 AnimationTree 状态机或混合空间 | godot_animation_build_state_machine_plan、godot_animation_build_blend_space_plan |
使用 godot_help tool="<name>" 获取参数模板。用 godot_validate_scene 验证,然后运行场景查看动效。仅凭场景树证据不足以证明动画看起来正确;请使用运行时截图或手动检查(参见 godot-interactive)。
AnimationPlayer
- 动画剪辑存放在 AnimationLibraries 中。默认库名称为空字符串
"",因此play("walk")是play("/walk")的简写,其他库则使用play("combat/slash")。 - 轨道路径相对于
root_node(默认为..,即播放器的父节点):NodePath("Sprite2D:frame")、NodePath(".:position")。 - 每个动画属性都应在
RESET动画中保留其静止值。编辑器使用它来恢复状态并避免场景差异混乱。 - 从 Call Method 轨道调用方法(脚步声、生成碰撞盒),而不是在代码中轮询时间。
- 按章节或标记播放(4.4+):
play_section_with_markers("attack", &"windup_end", &"recover_start")可循环或跳过剪辑部分。 animation_finished(anim_name)对非循环剪辑触发。4.7 将current_animation_changed的参数重命名为anim_name;通过 Callable 连接则无需担心此更改。- 4.6:
get_queue()返回Array[StringName],并新增了is_animation_active()。
@onready var anim: AnimationPlayer = $AnimationPlayer
func attack() -> void:
anim.play("attack")
await anim.animation_finished
anim.play("idle")
AnimationTree
AnimationTree (anim_player = ../AnimationPlayer, active = true)
└── tree_root: AnimationNodeStateMachine
├── Locomotion: AnimationNodeBlendSpace2D (按速度切换待机/走/跑)
├── Jump, Fall, Land
└── Attack (通过 AnimationNodeBlendTree 实现 OneShot)
@onready var tree: AnimationTree = $AnimationTree
@onready var playback: AnimationNodeStateMachinePlayback = tree.get("parameters/playback")
func _physics_process(_delta: float) -> void:
tree.set("parameters/Locomotion/blend_position", velocity / max_speed)
if not is_on_floor() and velocity.y > 0.0:
playback.travel("Fall")
- 参数路径来自动画树。在检视面板中悬停参数可复制其精确路径。
- 使用过渡前进条件或表达式(
advance_expression)进行数据驱动过渡,使用travel()进行代码驱动过渡。 - 对于一次性动画(攻击、受击),设置
parameters/<OneShot>/request为AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE。 AnimationNodeExtension(4.4,实验性)允许用 GDScript 编写自定义混合节点。
Tween
var t := create_tween().set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
t.tween_property(self, "scale", Vector2.ONE * 1.2, 0.12)
t.tween_property(self, "scale", Vector2.ONE, 0.12)
# 并行步骤
t = create_tween().set_parallel()
t.tween_property(sprite, "modulate:a", 0.0, 0.3)
t.tween_property(sprite, "position:y", sprite.position.y - 20.0, 0.3)
t.chain().tween_callback(queue_free)
# 4.4+:嵌套可复用的 Tween
var shake := create_tween()
for i in 4:
shake.tween_property(camera, "offset", Vector2(randf_range(-6, 6), randf_range(-6, 6)), 0.03)
var seq := create_tween()
seq.tween_subtween(shake)
seq.tween_property(camera, "offset", Vector2.ZERO, 0.05)
# 4.4+:在 Engine.time_scale 减慢时继续动画(打击暂停、慢动作期间的 UI)
create_tween().set_ignore_time_scale().tween_property(ui, "modulate:a", 1.0, 0.2)
# 4.7+:暂停序列直到信号触发
var intro := create_tween()
intro.tween_property(title, "modulate:a", 1.0, 0.5)
intro.tween_await(dialogue_box.closed)
intro.tween_property(title, "modulate:a", 0.0, 0.5)
规则:
- 通过
create_tween()绑定到节点的 Tween 会随节点销毁而消失。在启动冲突的 Tween 前,先销毁之前的 Tween:if _t and _t.is_valid(): _t.kill()。 - 暂停的树会暂停 Tween,除非使用
set_pause_mode(Tween.TWEEN_PAUSE_PROCESS)。 - 对于移动物理体的 Tween,使用
set_process_mode(Tween.TWEEN_PROCESS_PHYSICS)。
3D 骨骼动画
- 从 glTF(
.glb)导入动画。在“高级导入”对话框中设置循环模式和分割剪辑,不要在导入后操作。 - 重定向: 在导入时使用
SkeletonProfileHumanoid骨骼映射,在人体模型之间共享动画。RetargetModifier3D(4.4+)可在运行时在骨骼之间复制姿势。 - SkeletonModifier3D 堆栈(
Skeleton3D的子节点,按顺序处理):LookAtModifier3D(4.4+):头部和眼睛追踪,带角度限制。SpringBoneSimulator3D(4.4+):头发、尾巴、类似布料的抖动效果,配合SpringBoneCollision*3D。AimModifier3D、CopyTransformModifier3D、ConvertTransformModifier3D(4.5+):骨骼约束。- IK(4.6+):
TwoBoneIK3D(手臂和腿,确定性)、FABRIK3D/CCDIK3D/JacobianIK3D(迭代链)、SplineIK3D(沿着Path3D的脊柱和触手),配合JointLimitationCone3D限制、BoneTwistDisperser3D和LimitAngularVelocityModifier3D实现自然效果。旧的SkeletonIK3D已弃用,请使用这些新模块。 ModifierBoneTarget3D(4.5+):一个跟随骨骼的 Node3D,可用作 IK 目标或附着点。
- 脚部 IK 方案:从每只脚向下投射射线,将目标 Marker3D 移动到击中点,为每条腿驱动
TwoBoneIK3D,并根据最低脚的偏移量调整臀部。
调试
- 剪辑已播放但无任何移动:轨道路径相对于
root_node不正确,或者 AnimationTree 处于活动状态并覆盖了播放器。 - 属性回弹:另一条轨道或 RESET 关键化了同一属性,或者 Tween 和动画发生了冲突。
- 状态机卡住:检查过渡条件和
switch_mode,观察playback.get_current_node()。 - 3D 抖动:启用物理插值,或在与移动相同的进程模式下运行动画。