godot-animation-player
Expert patterns for AnimationPlayer including track types (Value, Method, Audio, Bezier), root motion extraction, animation callbacks, procedural animation generation, call mode optimization, and RESET tracks. Use for timeline-based animations, cutscenes, or UI transitions. Trigger keywords: AnimationPlayer, Animation, track_insert_key, root_motion, animation_finished, RESET_track, call_mode, animation_set_next, queue, blend_times.
thedivergentai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add thedivergentai/GD-Agentic-Skills --skill godot-animation-player技能说明
name: godot-animation-player description: "Expert patterns for AnimationPlayer including track types (Value, Method, Audio, Bezier), root motion extraction, animation callbacks, procedural animation generation, call mode optimization, and RESET tracks. Use for timeline-based animations, cutscenes, or UI transitions. Trigger keywords: AnimationPlayer, Animation, track_insert_key, root_motion, animation_finished, RESET_track, call_mode, animation_set_next, queue, blend_times."
AnimationPlayer
Timeline-based keyframe animation: track choice, RESET, root motion, libraries — scripts own recipes.
NEVER Do
- NEVER forget RESET tracks — Animated properties otherwise stick across scene changes.
- NEVER use
Animation.CALL_MODE_CONTINUOUSfor one-shot logic — UseCALL_MODE_DISCRETE. - NEVER animate embedded resource properties directly — Prefer instance uniforms / owned materials.
- NEVER use
animation_finishedfor looping clips — Useanimation_loopedor pollcurrent_animation. - NEVER hardcode animation name strings at scale — Constants /
StringName. - NEVER
seek()withoutupdate=truewhen same-frame reads matter. - NEVER leave off-screen visual-only players
active— Cull with notifiers. - NEVER mutate a playing
AnimationLibrary— Stop / wait for finished first. - NEVER rely on
speed_scalefor long sync — Preferseek()against a shared clock.
Available Scripts (MANDATORY triggers)
Open the matching script before implementing that pattern. Deep recipes: track-authoring.md, root-motion-and-sequences.md, edge-cases.md.
| Need | Script |
|---|---|
| Method-track hit/state keys | method_track_logic.gd |
| Stance/weapon library swap | runtime_anim_lib_swapper.gd |
| Shader uniform timelines | dynamic_shader_animation.gd |
| Runtime track tweak | procedural_track_modifier.gd |
| Forced RESET orchestration | reset_track_orchestrator.gd |
| Bezier → procedural drive | bezier_curve_extraction.gd |
Off-screen active cull | active_animation_culler.gd |
| Root motion ↔ physics | root_motion_physics_sync.gd |
| Part/equipment tracks | character_part_swapper_tracks.gd |
| TYPE_AUDIO footstep sync | precise_audio_sync.gd |
| Queue/branch sequences | animation_sequencer.gd |
| Code-built Animation resources | programmatic_anim.gd |
| Alt audio-track setup notes | audio_sync_tracks.gd |
Critical WHY (keep in body)
CALL_MODE_CONTINUOUSinvokes the method every frame across the key span — one-shot hitboxes/VFX needCALL_MODE_DISCRETE.- Animating embedded sub-resource properties (e.g.
material.albedo_color) duplicates resources into the scene — use instanced materials /shader_parameter/*tracks. animation_finisheddoes not fire on looping clips — useanimation_loopedor pollcurrent_animation.- Mutating a playing
AnimationLibrarycrashes or leaves bad transforms — stop or await finished before swap. speed_scaledrifts for rhythm/multiplayer — shared-clockseek(t, true)for long sync.
Track decision matrix
| Track | Use when | Avoid when |
|---|---|---|
| Value | Animate properties (pos, modulate, uniforms) | One-off runtime juice → Tween |
| Method | Hitboxes, SFX hooks, state flips at timestamps | CONTINUOUS call mode / missing method on path |
| Audio | Footsteps / VO locked to frames | Loose AudioStreamPlayer.play() drift |
| Bezier | Custom easing curves sampled at runtime | Simple linear fades |
Track authoring samples → track-authoring.md.
Root motion (physics)
CharacterBody3D + Skeleton3D + AnimationPlayer: extract with get_root_motion_position() / rotation on the physics tick — root_motion_physics_sync.gd. Walk cycles that only move bones leave the body collider behind.
Sequences, blends, RESET
- Chain:
animation_set_next/queue/ animation_sequencer.gd. - Blend times for walk↔run polish;
play("run", -1, 1.0, 0.5)orset_default_blend_time. - Always author a RESET clip with defaults; enable Reset on Save when editing.
- Reverse playback:
play("clip", -1, -1.0)for doors/cinematic rewind.
Full recipes → root-motion-and-sequences.md.
AnimationPlayer vs Tween
| Need | Prefer |
|---|---|
| Timeline / many properties / reusable | AnimationPlayer |
| One-shot runtime / interruptible | Tween (godot-tweening) |
Expert architecture (scripts)
| Pattern | Script | WHY |
|---|---|---|
| Shared humanoid libraries | runtime_anim_lib_swapper.gd | One library, many models — play lib/clip |
| Decoupled timeline events | method_track_logic.gd | Method track → signaler → gameplay listeners |
| Off-screen CPU budget | active_animation_culler.gd | active = false or manual advance() |
| Code-built clips | programmatic_anim.gd | Dynamic targets not in FBX |
Reference
阅读完整来源 ↗Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing work to a peer domain — do not pr