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_CONTINUOUS` for one-shot logic** — Use `CALL_MODE_DISCRETE`.
- **NEVER animate embedded resource properties directly** — Prefer instance uniforms / owned materials.
- **NEVER use `animation_finished` for looping clips** — Use `animation_looped` or poll `current_animation`.
- **NEVER hardcode animation name strings at scale** — Constants / `StringName`.
- **NEVER `seek()` without `update=true` when 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_scale` for long sync** — Prefer `seek()` against a shared clock.

---

## Available Scripts (MANDATORY triggers)

> Open the matching script **before** implementing that pattern. Deep recipes: [track-authoring.md](references/track-authoring.md), [root-motion-and-sequences.md](references/root-motion-and-sequences.md), [edge-cases.md](references/edge-cases.md).

| Need | Script |
|---|---|
| Method-track hit/state keys | [method_track_logic.gd](scripts/method_track_logic.gd) |
| Stance/weapon library swap | [runtime_anim_lib_swapper.gd](scripts/runtime_anim_lib_swapper.gd) |
| Shader uniform timelines | [dynamic_shader_animation.gd](scripts/dynamic_shader_animation.gd) |
| Runtime track tweak | [procedural_track_modifier.gd](scripts/procedural_track_modifier.gd) |
| Forced RESET orchestration | [reset_track_orchestrator.gd](scripts/reset_track_orchestrator.gd) |
| Bezier → procedural drive | [bezier_curve_extraction.gd](scripts/bezier_curve_extraction.gd) |
| Off-screen `active` cull | [active_animation_culler.gd](scripts/active_animation_culler.gd) |
| Root motion ↔ physics | [root_motion_physics_sync.gd](scripts/root_motion_physics_sync.gd) |
| Part/equipment tracks | [character_part_swapper_tracks.gd](scripts/character_part_swapper_tracks.gd) |
| TYPE_AUDIO footstep sync | [precise_audio_sync.gd](scripts/precise_audio_sync.gd) |
| Queue/branch sequences | [animation_sequencer.gd](scripts/animation_sequencer.gd) |
| Code-built Animation resources | [programmatic_anim.gd](scripts/programmatic_anim.gd) |
| Alt audio-track setup notes | [audio_sync_tracks.gd](scripts/audio_sync_tracks.gd) |

## Critical WHY (keep in body)

- **`CALL_MODE_CONTINUOUS`** invokes the method **every frame** across the key span — one-shot hitboxes/VFX need **`CALL_MODE_DISCRETE`**.
- Animating embedded **sub-resource** properties (e.g. `material.albedo_color`) duplicates resources into the scene — use instanced materials / `shader_parameter/*` tracks.
- **`animation_finished`** does not fire on looping clips — use `animation_looped` or poll `current_animation`.
- Mutating a playing **`AnimationLibrary`** crashes or leaves bad transforms — stop or await finished before swap.
- **`speed_scale`** drifts for rhythm/multiplayer — shared-clock **`seek(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 `AudioStream