unity-animation
Unity 6 animation system guide. Use when working with Animator Controllers, animation state machines, blend trees, animation clips, Avatar system, humanoid rigs, root motion, animation events, Timeline, or Cinemachine. Based on Unity 6.3 LTS documentation.
Nice-Wolf-Studio · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Nice-Wolf-Studio/unity-claude-skills --skill unity-animation技能说明
name: unity-animation description: > Unity 6 animation system guide. Use when working with Animator Controllers, animation state machines, blend trees, animation clips, Avatar system, humanoid rigs, root motion, animation events, Timeline, or Cinemachine. Based on Unity 6.3 LTS documentation.
Unity Animation System
Animation System Overview
Unity's Mecanim animation system is built on three interconnected components:
- Animation Clips -- Unit pieces of motion (Idle, Walk, Run)
- Animator Controller -- State machine organizing clips into a flowchart of states and transitions
- Avatar System -- Maps humanoid character skeletons to a common internal format for retargeting
The Animator component is attached to GameObjects and references both the Animator Controller and Avatar assets needed for playback.
Animation Types
- Humanoid -- Requires Avatar configuration; supports retargeting between different character rigs; 15-20% more CPU-intensive than Generic
- Generic -- Animates Transform or MonoBehaviour properties on specific hierarchies; not transferable between different hierarchies
- Legacy -- Older Animation component; use for simple single-shot or UI animations
Animator Controller
An Animator Controller asset arranges Animation Clips and Transitions for a character or animated GameObject.
Creating: Right-click in Project window > Create > Animator Controller
Key Components
- States -- Each state plays an associated Animation Clip or Blend Tree
- Transitions -- Define how and when the state machine switches between states
- Parameters -- Variables (Float, Int, Bool, Trigger) that scripts set to control transitions
- Layers -- Separate state machines for different body parts or animation concerns
- Sub-State Machines -- Nested state machines for hierarchical organization
Parameters
Four types are available:
| Type | Description | Script Method |
|---|---|---|
| Float | Decimal number | SetFloat() / GetFloat() |
| Int | Whole number | SetInteger() / GetInteger() |
| Bool | True/false | SetBool() / GetBool() |
| Trigger | Auto-resetting bool | SetTrigger() / ResetTrigger() |
using UnityEngine;
public class PlayerAnimController : MonoBehaviour
{
Animator animator;
void Start()
{
animator = GetComponent<Animator>();
}
void Update()
{
// Note: Uses legacy Input Manager for simplicity. See unity-input for the new Input System.
float h = Input.GetAxis("Horizontal");
float v = Input.GetAxis("Vertical");
bool fire = Input.GetButtonDown("Fire1");
animator.SetFloat("Forward", v);
animator.SetFloat("Strafe", h);
animator.SetBool("Fire", fire);
}
void OnCollisionEnter(Collision col)
{
if (col.gameObject.CompareTag("Enemy"))
{
animator.SetTrigger("Die");
}
}
}
Animator Override Controller
Replaces animation clips in an Animator Controller while keeping structure, parameters, and logic intact. Useful for multiple characters sharing the same state machine but using different clips.
Critical: Set transition exit times in normalized time (not seconds) when using Override Controllers, or exit times may be ignored if override clips have different durations.
Layers
- Override mode -- Replaces animation from previous layers
- Additive mode -- Adds animation on top of previous layers
- Avatar Mask -- Restricts a layer to specific body parts (e.g., upper body only)
- Synced Layers -- Reuse state machine structure with different clips
State Machines and Transitions
States
Each state in the Animator Controller represents a distinct action. Special states include:
- Entry -- Default entry point
- Any State -- Transitions from any current state
- Exit -- Exits the current state machine or sub-state machine
Transitions
Transitions define how states blend into each other.
| Setting | Description |
|---|---|
| Has Exit Time | Transition triggers at a normalized time (e.g., 0.75 = 75% complete) |
| Transition Duration | Blend period; in seconds (Fixed Duration) or fraction of source state |
| Transition Offset | Where destination state begins playback (0.5 = midpoint) |
| Conditions | Parameter-based rules; all must be satisfied simultaneously |
| Interruption Source | Which transitions can interrupt: None, Current State, Next State, or combinations |
| Ordered Interruption | Whether transition parsing stops at current transition or any valid one |
When both Has Exit Time and Conditions are set, Unity only checks conditions after the exit time.
State Machine Behaviours
Scripts inheriting StateMachineBehaviour attach to states. Callbacks: OnStateEnter, OnStateUpdate, OnStateExit, OnStateMove, OnStateIK. All receive (Animator animator, AnimatorStateInfo stateInfo, int layerIndex).
public class AttackState : StateMachineBehaviour
{
public AudioClip attackSound;
override public void OnStateEnter(Animator animator, AnimatorStateInfo stateInfo, int layerIndex)
{
AudioSource.PlayClipAtPoint(attackSound, animator.transform.position);
}
override public void OnStateExit(Animator animator, AnimatorStateInfo stateInfo, int layerIndex)
{
// Cleanup when leaving state
}
}
Blend Trees
Blend Trees smoothly blend between multiple similar animations based on parameter values, unlike transitions which switch between distinct states over time.
Critical requirement: Animations must be of similar nature and timing. Foot contact points should align in normalized time (e.g., left foot at 0.0, right foot at 0.5).
Blend Types
- 1D -- Single parameter controls blending (e.g., speed for walk/run)
- 2D Simple Directional -- Two parameters, one mot