Communitygithub.com

godot-animation

動畫製作 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-animation 是什麼?

此技能專注於 Godot 4.x 遊戲引擎的完整動畫系統,涵蓋 AnimationPlayer、AnimationTree、Tween、2D 精靈動畫與 3D 骨架動畫等核心功能。它提供從簡單的「發射後不理」運動(如 UI 彈跳、擊退、淡出)到複雜的角色動畫、過場動畫及程序化動畫的解決方案。技能文件詳細說明了如何選擇合適的工具(例如使用 Tween 處理短暫運動、AnimationPlayer 處理編制片段、AnimationTree 處理狀態混合),並附有豐富的 GDScript 範例與實戰建議。此外,文件還介紹了 godot-mcp 提供的動畫輔助工具,可用於自動化場景設定、片段管理、關鍵幀操作及 AnimationTree 計畫。對於 3D 動畫,特別強調了重定目標(Retargeting)與 IK 框架(SkeletonModifier3D 家族)的應用,包括腳部 IK、頭部追蹤、彈簧骨骼模擬等進階技術。最後提供除錯指南,幫助開發者解決常見的動畫問題。

相容平台~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="<名稱>" 取得參數模板。使用 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 編寫自訂混合節點。

Tweens

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 BoneMap,可在人體模型之間共享動畫。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 中的抖動:啟用物理插值,或在與移動相同的處理模式下設定動畫。

相關技能