godot-animation-tree-mastery
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.
thedivergentai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add thedivergentai/GD-Agentic-Skills --skill godot-animation-tree-mastery技能说明
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 callingplay()causes conflicts and jitter. Useset("parameters/transition_request")ortravel()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_advanceenabled for interactive states — It causes immediate transitions. Use it only for automated sequences like combo chains or death-to-respawn. - NEVER use
BlendSpace2Dfor 1D blending — Blending only speed? UseBlendSpace1D. Blending only two states? UseBlend2.BlendSpace2Dis specifically for X+Y directional inputs (strafe). - NEVER update
AnimationTreeparameters every frame without a guard — Setting parameters viaset()every frame regardless of change causes cache invalidation and potential stutter. Check equality first. - NEVER use deep, nested
BlendTreesfor simple logic — Every layer adds CPU overhead. If logic can be handled in aStateMachineor a simple script-drivenBlend2, do it there. - NEVER forget to handle
await get_tree().process_framewhen updating parameters synchronously — Sometimes the tree needs one frame to reconcile state before the next parameter change takes effect. - NEVER rely on
auto_advancefor long cutscenes — If an animation is interrupted,auto_advancecan put the character in a broken state. UseMethod Tracksto signal state completion instead. - NEVER use
Syncgroups for animations with wildly different lengths — It forces one animation to play at an extreme speed. UseTimeScaleor 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 unless nested combat graphs, IK look-at, or deep BlendTree layering are in scope.
sync_parameter_manager.gd
Guarded AnimationTree parameter writes — prevent redundant set() churn every physics frame.
statemachine_travel_code.gd
Programmatic AnimationNodeStateMachinePlayback via travel() / start().
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
Trigger: locomotion + combat (or air) sub-machines. Nested StateMachine parameter paths and playback handoff.
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
AnimationNodeOneShot for recoil, blinks, and hit reactions.
dynamic_timescale_control.gd
Runtime playback speed for bullet-time or haste multipliers.
advanced_transition_masking.gd
Bone filter masks on Add2/Blend2 for upper/lower body separation.
blendtree_logic_mixing.gd
Interactive combat layer mixing inside BlendTree graphs.
root_motion_animtree_sync.gd
CharacterBody motion extraction from AnimationTree root motion.
sync_group_layering.gd
Sync groups for multi-layer clips that share length (e.g. walk + reload).
nested_tree_architecture.gd
Hierarchical StateMachine / nested parameter path architecture.
runtime_tree_debugging.gd
Visualize current states, travel paths, and blend values at runtime.
animation_event_dispatcher.gd
Method-track → dispatch_event(name, metadata) signal bridge; decouple VFX/audio from graph code.
animation_complexity_manager.gd
Swap tree_root hero vs crowd graph when VisibleOnScreenNotifier3D culls off-screen actors.
Decision Tree (replace inline tutorials)
| Need | Prefer | Script |
|---|---|---|
| Simple clip swap / UI / prop | AnimationPlayer only | Peer godot-animation-player |
| 5+ gameplay states, travel | StateMachine root | statemachine_travel_code.gd, tree_travel_manager.gd |
| Speed only blend | BlendSpace1D | Guarded writes via sync_parameter_manager.gd |
| Strafe / aim X+Y | BlendSpace2D | Same + blend_position |
| Upper-body overlay / combat layer | BlendTree Add2/Blend2/OneShot | blendtree_logic_mixing.gd, reactive_oneshot_vfx.gd |
| Nested combat/air under locomotion |