godot-animation-tree-mastery

Este extracto es una copia guardada durante la revisión. La fuente externa contiene la versión completa y actual.

---
name: godot-animation-tree-mastery
description: "Expert patterns for AnimationTree including StateMachine transitions, BlendSpace2D for directional movement, BlendTree for layered animations, root motion, transition conditions, advance expressions, and state machine sub-states. Use for complex character animation systems with movement blending and state management. Trigger keywords: AnimationTree, AnimationNodeStateMachine, BlendSpace2D, BlendSpace1D, BlendTree, transition_request, blend_position, advance_expression, AnimationNodeAdd2, AnimationNodeBlend2, root_motion."
---

# AnimationTree Mastery

Expert guidance for Godot's advanced animation blending and state machines.

## NEVER Do

- **NEVER call `play()` on AnimationPlayer when using AnimationTree** — AnimationTree controls the player. Directly calling `play()` causes conflicts and jitter. Use `set("parameters/transition_request")` or `travel()` instead.
- **NEVER forget to set `active = true`** — AnimationTree is inactive by default. Animations won't play until `$AnimationTree.active = true`.
- **NEVER use absolute paths for parameter access** — Use relative paths like `"parameters/StateMachine/transition_request"`. This ensures compatibility when nodes move in the hierarchy.
- **NEVER leave `auto_advance` enabled for interactive states** — It causes immediate transitions. Use it only for automated sequences like combo chains or death-to-respawn.
- **NEVER use `BlendSpace2D` for 1D blending** — Blending only speed? Use `BlendSpace1D`. Blending only two states? Use `Blend2`. `BlendSpace2D` is specifically for X+Y directional inputs (strafe).
- **NEVER update `AnimationTree` parameters every frame without a guard** — Setting parameters via `set()` every frame regardless of change causes cache invalidation and potential stutter. Check equality first.
- **NEVER use deep, nested `BlendTrees` for simple logic** — Every layer adds CPU overhead. If logic can be handled in a `StateMachine` or a simple script-driven `Blend2`, do it there.
- **NEVER forget to handle `await get_tree().process_frame` when updating parameters synchronously** — Sometimes the tree needs one frame to reconcile state before the next parameter change takes effect.
- **NEVER rely on `auto_advance` for long cutscenes** — If an animation is interrupted, `auto_advance` can put the character in a broken state. Use `Method Tracks` to signal state completion instead.
- **NEVER use `Sync` groups for animations with wildly different lengths** — It forces one animation to play at an extreme speed. Use `TimeScale` or separate layers for mismatching cycles.

---

## Available Scripts

> **MANDATORY**: Read the appropriate script before implementing the corresponding pattern.
> **Do NOT Load** [references/advanced-graph-recipes.md](references/advanced-graph-recipes.md) unless nested combat graphs, IK look-at, or deep BlendTree layering are in scope.

### [sync_parameter_manager.gd](scripts/sync_parameter_manager.gd)
Guarded `AnimationTree` parameter writes — prevent redundant `set()` churn every physics frame.

### [statemachine_travel_code.gd](scripts/statemachine_travel_code.gd)
Programmatic `AnimationNodeStateMachinePlayback` via `travel()` / `start()`.

### [tree_travel_manager.gd](scripts/tree_travel_manager.gd)
**Trigger: multi-machine travel / request queue.** Centralizes travel requests across nested playback paths without calling AnimationPlayer.`play()`.

### [nested_state_machine.gd](scripts/nested_state_machine.gd)
**Trigger: locomotion + combat (or air) sub-machines.** Nested StateMachine parameter paths and playback handoff.

### [skeleton_ik_lookat.gd](scripts/skeleton_ik_lookat.gd)
**Trigger: aim/look-at beside the tree.** LookAtModifier3D / IK that must not fight bone tracks the tree owns.

### [reactive_oneshot_vfx.gd](scripts/reactive_oneshot_vfx.gd)
`AnimationNodeOneShot` for recoil, blinks, and hit reactions.

### [dynamic_timescale_control.gd](scripts/dynamic_timescale_control.gd)
Runtime pl