unity-animation

Unity Animation（Animator / Mecanim）

使用 Unity 6.3 LTS 的 Animator 和 Animator Controllers 控制动画状态：参数、过渡、混合树、层级和人形 IK。面向 Unity 6.3 LTS (6000.3)。

适用场景

• 适用于将动画片段连接到状态机、通过参数由脚本驱动动画、混合移动动画（待机→行走→奔跑）、在移动动画上叠加上半身动作，或为人形骨骼添加脚部／手部 IK。
• 适用于项目包含 *.controller（Animator Controller）和 *.anim 资源，或包含带骨骼的模型及其 Avatar 的情况。

不适用场景： 简单的非骨骼数值补间（UI 淡入淡出、位置插值）更适合使用补间工具／协程实现——请参阅 unity-csharp-scripting。Timeline 过场动画是单独的工具。2D 精灵逐帧动画也使用 Animator，但采用精灵关键帧。

核心工作流

1. 为模型添加 Animator 并指定 Animator Controller；对于人形模型，将其骨骼设为 Humanoid，使其拥有 Avatar（启用重定向和 IK）。
2. 在 Controller 上定义参数——Float（Speed）、Bool（IsGrounded）、Int、Trigger（Jump）——并创建状态和过渡，其条件读取这些参数。
3. 通过脚本设置参数，切勿直接操作状态：SetFloat、SetBool、SetInteger、SetTrigger。状态机将为你处理过渡。
4. 使用 Blend Tree 混合连续动作（由一个 Float 参数（如 Speed）驱动待机↔行走↔奔跑），而不是创建许多离散状态和过渡。
5. 叠加加法／覆盖动作（例如使用 Avatar Mask 的上半身“瞄准”层），并控制其 layerWeight。
6. 进行验证：在 Play 模式下打开 Animator 窗口——当前状态会高亮显示，参数值也会更新，你可以准确查看触发（或未触发）的过渡。

模式

1. 从脚本驱动移动动画和一次性动作

using UnityEngine;

[RequireComponent(typeof(Animator))]
public class CharacterAnim : MonoBehaviour
{
    private Animator _anim;
    // Cache parameter hashes — faster and typo-proof vs string lookups every frame.
    private static readonly int Speed     = Animator.StringToHash("Speed");
    private static readonly int IsGrounded= Animator.StringToHash("IsGrounded");
    private static readonly int Jump      = Animator.StringToHash("Jump");

    private void Awake() => _anim = GetComponent<Animator>();

    public void Tick(float planarSpeed, bool grounded)
    {
        _anim.SetFloat(Speed, planarSpeed);     // drives a 1D blend tree (idle/walk/run)
        _anim.SetBool(IsGrounded, grounded);    // gates a falling/landing transition
    }

    public void DoJump() => _anim.SetTrigger(Jump);  // fire-and-forget; auto-resets after use
}

2. 将嘈杂输入平滑为混合参数

// dampTime smooths Speed so the blend tree doesn't snap; great for analog sticks.
_anim.SetFloat(Speed, targetSpeed, 0.1f /* dampTime */, Time.deltaTime);

3. 直接播放／交叉淡化状态（绕过参数条件）

// Useful for hit reactions where you want an immediate, explicit transition.
_anim.CrossFade("Hit", 0.1f);                    // blend over 0.1s normalized
// Or jump instantly:  _anim.Play("Hit");

4. 等待当前状态播放完毕

private System.Collections.IEnumerator AfterAttack()
{
    var info = _anim.GetCurrentAnimatorStateInfo(0);   // layer 0
    yield return new WaitForSeconds(info.length);      // approximate clip length
    // ...follow-up logic
}

易踩坑

• SetTrigger 未触发或“卡住”——触发器会被下一个满足条件的过渡消耗并自动重置；如果没有过渡消耗它，之后可能会意外触发。使用 ResetTrigger 清除，或在条件代表持续状态时改用 Bool。
• 字符串参数名称拼写错误不会报错——名称拼错只会导致操作无效。使用 Animator.StringToHash 并缓存 int 哈希值。
• 过渡感觉迟缓——Has Exit Time 会让过渡等待片段播放到指定的归一化时间。对于需要快速响应的条件驱动过渡（跳跃、受击），请取消勾选。
• 角色滑动或无法移动——Apply Root Motion 已启用，但代码也在移动 transform（反之亦然）。请选择根运动或脚本控制移动，不要两者同时使用。
• 上半身层覆盖了整个身体——设置层的 Blend 模式（Override 或 Additive），指定 Avatar Mask，并调整 layerWeight（0–1）。
• IK 没有作用——IK 仅在 OnAnimatorIK 中生效，需要为该层启用“IK Pass”，并且需要 Humanoid Avatar。

参考资料

• 关于混合树（1D 与 2D Freeform／Directional）、动画层和 Avatar Masks以及人形 IK（OnAnimatorIK、SetIKPositionWeight、SetIKPosition、look-at），请阅读 references/blend-trees-and-ik.md。
• 主要文档：Unity Manual 的“Animation”部分和 ScriptReference/Animator。

相关技能

• unity-csharp-scripting——上文使用的 MonoBehaviour 和协程计时。
• unity-physics——移动动画所呈现的物体。
• game-ai——决定何时播放哪种动画状态。