Communitygithub.com

Godot动画

为 Godot 4.x 游戏制作动画 — AnimationPlayer 剪辑和库、AnimationTree 状态机和混合空间、精灵动画、Tween(包括 4.4 子 Tween 和 4.7 tween_await)、动画章节和标记、3D 骨骼动画、重定向以及 4.6 IK 框架(TwoBoneIK3D、FABRIK3D、CCDIK3D、SplineIK3D)。用于角色动画、UI 动效、过场动画、程序化动效或动画与游戏状态绑定。配合 godot-mcp 的 godot_animation_* 工具使用。

Godot动画 是什么?

该技能专为 AI 代理(如 Claude Code、Cursor、Codex)设计,帮助在 Godot 4.x 中创建和管理动画。它支持 AnimationPlayer(剪辑和库)、AnimationTree(状态机和混合空间)、精灵动画、Tween(包括 4.4 子 Tween 和 4.7 tween_await)、动画章节和标记、3D 骨骼动画、重定向以及 4.6 引入的 IK 框架(TwoBoneIK3D、FABRIK3D、CCDIK3D、SplineIK3D)。这份全面的指南涵盖了角色动画、UI 动效、过场动画和程序化动效。它与 godot-mcp 工具集成,提供如godot_animation_setup_scene、godot_animation_create_clip等实用函数,用于设置场景、创建/读取剪辑、添加/移除关键帧以及规划动画树。该技能还提供了常见问题的调试技巧,例如属性回弹、状态机卡住或3D抖动。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Yuki-az-23/noit-godot-skills/tree/HEAD/skills/godot-animation

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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,并根据最低脚的偏移量调整臀部。

调试

  1. 剪辑已播放但无任何移动:轨道路径相对于 root_node 不正确,或者 AnimationTree 处于活动状态并覆盖了播放器。
  2. 属性回弹:另一条轨道或 RESET 关键化了同一属性,或者 Tween 和动画发生了冲突。
  3. 状态机卡住:检查过渡条件和 switch_mode,观察 playback.get_current_node()。
  4. 3D 抖动:启用物理插值,或在与移动相同的进程模式下运行动画。

相关技能