Unity-Animator深入系列---API详解

回到 Animator深入系列总目录

测试Unity版本为5.2.1

• 人形动画的接口都有标注
• 本列表不包含所有标注为过时的方法
• 目前该详解还有不少缺漏，有时间持续更新

2016/8/16更新CrossFadeInFixedTime接口描述

---

1.Vector3 angularVelocity { get; }

[人形动画]获得Avatar相对于最后一帧的角速率

2.bool applyRootMotion { get; set; }

是否打开根运动

3.Avatar avatar { get; set; }

[人形动画]人形动画Avatar，但是avatar结构里的字段非常少，应该是用于自定义类型转换。

官方说在运行时切换Avatar并不完全支持，需要保险起见LINK

4.Vector3 bodyPosition { get; set; }

[人形动画]获得身体坐标，根据测试应该是平均值，比spine还低一些

5.Quaternion bodyRotation { get; set; }

[人形动画]获得身体旋转

6.AnimatorCullingMode cullingMode { get; set; }

默认是CullUpdateTransforms，会剔除一部分内容，包括一些消息还会触发

CullCompletely是不可见时完全禁用，AlwaysAnimate是完全不剔除

具体参考官方文档LINK

7.Vector3 deltaPosition { get; }

对于有根位移的动画，相对于上一帧的位移本地空间坐标差。

具体参考这篇:LINK

8.Quaternion deltaRotation { get; }

对于有根位移的动画，相对于上一帧的位移本地空间旋转坐标差。

具体参考这篇:LINK

9.float feetPivotActive { get; set; }

资料很少，修改该值并没有影响到pivotPosition。

Blends pivot point between body center of mass and feet pivot. At 0%, the blending point is body center of mass. At 100%, the blending point is feet pivot.

混合身体质量中心与脚质量中心的轴心点。0%表示混合轴心点在身体的质量中心；100%表示混合轴心点在脚的轴心点；

10.bool fireEvents { get; set; }

官方新增的不明接口，包括官方文档也没有描述。

11.float gravityWeight { get; }

使用Animator的时候经常会发现动画没有重力，而gravityWeight就是这个问题的关键

默认重力权重设置为1，即可应用刚体的重力。如果刚体不打开重力，则没有重力

使用时在FBX动画片段的曲线中设置即可

重力权重越大即重力越大，重力权重范围对应时间轴上包含位移的范围

12.bool hasRootMotion { get; }

剪辑本身是否有根运动

13.bool hasTransformHierarchy { get; }

[人形动画]只对人形动画有效，当勾选优化游戏对象之后。返回值为Flase，否则为True

优化游戏对象具体参阅文档LINK

大意就是把层级信息存到内置的数据结构里，不需要在运行时进行匹配了。从而提升性能

14.float humanScale { get; }

返回当前人形绑定Avatar的缩放，（如果绑定是generic，默认为1）

测了下似乎和FBX设置的缩放因子有关，缩放比例是根据Unity默认的Avatar

15.bool isHuman { get; }

是否是人形动画

16.bool isInitialized { get; }

检测动画是否初始化成功

当没有控制器时会提示Not initialized，此时调用isInitialized返回False，反之返回True

17.bool isMatchingTarget { get; }

[人形动画]当前是否正在匹配目标

关于匹配具体请看这篇LINK

18.bool isOptimizable { get; }

始终返回为True，暂时没搞明白。官方文档链接LINK

AnimatorUtility.OptimizeTransformHierarchy(gameObject, new string[0]);

将其优化后，并且Animator也出现优化后的提示，依旧打印True。。。实在无解

19.int layerCount { get; }

动画层数

20.bool layersAffectMassCenter { get; set; }

资料很少，暂时不清楚这个接口，官方的描述：

Additional layers affects the center of mass.

官方的链接：LINK

21.float leftFeetBottomHeight { get; } 和 float rightFeetBottomHeight { get; }

[人形动画]获得左脚脚底高度和右脚脚底高度

测试代码：

左边的图是获得脚部IK坐标，并赋予给绿色Cube和红色Cube

右边的图是加上脚底距离高度，并设置坐标

22.bool linearVelocityBlending { get; set; }

没有太多资料，尝试设置为True，测试了一下变化不是很大

官方描述

When linearVelocityBlending is set to true, the root motion velocity and angular velocity will be blended linearly.

当linearVelocityBlending 设置为true，根运动速度和角速度将线性混合

23.bool logWarnings { get; set; }

新加入的接口，文档没有相关信息，应该是是否打印警告日志

24.int parameterCount { get; }

拥有的参数数量，用于参数遍历

25.AnimatorControllerParameter[] parameters { get; }

所有的参数数组

26.Vector3 pivotPosition { get; }

[人形动画]相对于两脚之间的中间点，非人形动画返回Vector3.zero

27.float pivotWeight { get; }

[人形动画]该轴心点是avatar的左右脚之间最稳定的轴心点。值为0时，左脚是最稳定的轴心点；值为1时，右脚是最稳定的轴心点

28.float playbackTime { get; set; }

动画回放时间，录制与回放具体请看这篇LINK

29.AnimatorRecorderMode recorderMode { get; }

当前的录制模式，Offline,Playback,Record

回放或者录制，或者两种状态都不在。

录制与回放具体请看这篇LINK

30.float recorderStartTime { get; set; }

录制开始时间，录制与回放具体请看这篇LINK

31.float recorderStopTime { get; set; }

录制结束时间，录制与回放具体请看这篇LINK

32.Vector3 rootPosition { get; set; }

返回根骨骼的世界坐标

33.Quaternion rootRotation { get; set; }

返回根骨骼的世界旋转

34.RuntimeAnimatorController runtimeAnimatorController { get; set; }

可以进行强类型转换，也可以直接取到原始动画剪辑，映像中还有一个Editor状态下可以转换的Controller，能改一些底层信息

35.float speed { get; set; }

动画的整体速度，影响其中的每一个动画剪辑

36.bool stabilizeFeet { get; set; }

过渡和混合时，脚自动稳定。

37.Vector3 targetPosition { get; }

返回由SetTarget(AvatarTarget targetIndex, float targetNormalizedTime))指定的目标的位置

关于SetTarget具体请看这篇LINK

38.Quaternion targetRotation { get; }

返回由SetTarget(AvatarTarget targetIndex, float targetNormalizedTime))指定的目标的旋转角度。

关于SetTarget具体请看这篇LINK

39.AnimatorUpdateMode updateMode { get; set; }

Normal Normal update of the animator. 
标准更新。
AnimatePhysics Updates the animator during the physic loop in order to have the animation system synchronized with the physics engine.
在物理循环期间更新Animator为了使动画系统与物理引擎同步。
UnscaledTime Animator updates independently of Time.timeScale.
Time.timeScale外的Animator独立更新。

默认值是Normal 

40.Vector3 velocity { get; }

返回根骨骼相对上一帧结果计算的速率，对于没有根骨骼的动画无效

41.static int StringToHash(string name)

注意这个是静态方法，通过字符串取得参数的hash值

42.void ApplyBuiltinRootMotion()

该方法顾名思义，会调用内建的根骨骼移动

也可以用在StateMachineBehaviour的OnStateMove里

比如下面这样，运行游戏后角色直接飞掉了

public class Test1 : MonoBehaviour
{
    public Animator animator;

    void OnAnimatorMove()
    {
        for (int i = 0; i < 100; i++)
        {
            animator.ApplyBuiltinRootMotion();
        }
    }
}

43.CrossFade(...)系列接口

和Animation的CrossFade差不多，混合过渡并且播放

第四个参数normalizedTime要说一下，是0-1的范围，表示目标动画剪辑从哪里开始播放

animator.CrossFade("Jump", 0.2f, 0, 0.5f);

可以看见，调用后从0.5开始播放

关于混合的细节，时长可以参考这篇文章：LINK

44.CrossFadeInFixedTime(...)系列接口

混合并且按照实际时间进行。这里的实际时间是指Time.time的时间

具体细节可以参考这篇文章：LINK

45.AnimatorTransitionInfo GetAnimatorTransitionInfo(int layerIndex)

获得当前动画的过渡信息，关于过渡可以看这篇LINK

46.GetBehaviour<T>() 和 GetBehaviours<T>()

返回挂载在AnimatorController上的行为脚本StateMachineBehaviour

通常StateMachineBehaviour之间的交互会经常用到。

47.Transform GetBoneTransform(HumanBodyBones humanBoneId)

[人形动画]获取骨骼的Transform对象，参数是枚举形。

如果被临时删除了或者没有绑定这个关节，会返回空

Debug.Log("GetBoneTransform: " + animator.GetBoneTransform(HumanBodyBones.LeftFoot));
//print GetBoneTransform: joint_FootLT (UnityEngine.Transform)

48.AnimatorClipInfo[] GetCurrentAnimatorClipInfo(int layerIndex);

获得当前层正在播放的剪辑数组,并且获取到的时间长度(clip.length)不受Animator速度影响。

如果想获取全部原始剪辑，可以用runtimeAnimatorController.animationClip

49.AnimatorStateInfo GetCurrentAnimatorStateInfo(int layerIndex);

获得当前所处的动画状态

返回的结构中.length是动画总长度,normalizedTime是归一化的动画当前时间

注意取到的length属性会受到Animator速度缩放影响

另外，取到的归一化时间normalizedTime在播放循环动画时，会无限增长

(如果要获取不受缩放影响的原始剪辑，可以用runtimeAnimatorController.animationClip或者GetCurrentAnimatorClipInfo，区别在于一个能取到全部，一个只能取到当前播放的)

50.bool HasState(int layerIndex, int stateID);

配合Animator.StringToHash可以直接转换成stateID

Debug.Log(animator.HasState(0, Animator.StringToHash("Idle")));
//print True

51.bool IsInTransition(int layerIndex);

是否正处于过渡，很常用的一个接口

如果忽视了过渡的判断，就会有意想不到的bug

if(!animator.IsInTransition(0) && animator.GetCurrentAnimatorStateInfo(0).IsName("Idle"))
{
    //Do something.
}

52.bool IsParameterControlledByCurve(...);

参数是否被曲线控制

Debug.Log("IsParameterControlledByCurve: " + animator.IsParameterControlledByCurve("Speed"));
//print True

注意，参数一旦被曲线控制，就不要在代码里修改它，否则会有警告

53.MatchTarget(Vector3 matchPosition, Quaternion matchRotation, AvatarTarget targetBodyPart, MatchTargetWeightMask weightMask, float startNormalizedTime, float targetNormalizedTime)

[人形动画]匹配目标，关于匹配具体请看这篇LINK

54.Play(...)系列接口

没什么好说的，需要注意normalizedTime参数，区间在0-1之间，直接影响到目标动画剪辑从哪个时间点开始播放

55.void Rebind();

重新绑定动画器的所有动画的属性和网格数据。

有时根骨骼坐标会被锁定，重置坐标后，调用该方法即可解决。

56.void ResetTrigger(...);

重设该触发参数为False

如果是当前状态播放结束再跳转的话，会用到这个方法，在结束之前可以重置回False

57.void SetBoneLocalRotation(...);

[人形动画]设置某个骨骼的本地旋转

58.void Vector3 GetIKHintPosition(AvatarIKHint hint)  &   SetIKHintPosition(AvatarIKHint hint, Vector3 hintPosition)

[人形动画]获取/设置IK Hint位置，IK相关操作请参考这篇:LINK

59.float GetIKHintPositionWeight(AvatarIKHint hint)   &   void SetIKHintPositionWeight(AvatarIKHint hint, float value)

[人形动画]获取/设置IK Hint位置权重，IK相关操作请参考这篇:LINK

60.Vector3 GetIKPosition(AvatarIKGoal goal)   &    void SetIKPosition(AvatarIKGoal goal, Vector3 goalPosition)

[人形动画]获取/设置IK位置，IK相关操作请参考这篇:LINK

61.float GetIKPositionWeight(AvatarIKGoal goal)     &    void SetIKPositionWeight(AvatarIKGoal goal, float value)

[人形动画]获取/设置和获取IK位置权重，IK相关操作请参考这篇:LINK

62.Quaternion GetIKRotation(AvatarIKGoal goal)    &   void SetIKRotation(AvatarIKGoal goal, Quaternion goalRotation)

[人形动画]获取/设置IK旋转，IK相关操作请参考这篇:LINK

63.float GetIKRotationWeight(AvatarIKGoal goal)  &  void SetIKRotationWeight(AvatarIKGoal goal, float value)

[人形动画]获取/设置IK旋转权重，IK相关操作请参考这篇:LINK

64.void SetLayerWeight(int layerIndex, float weight)

设置层权重

65.void SetLookAtPosition(Vector3 lookAtPosition) 和 void SetLookAtWeight(...)

[人形动画]测试脚本：

animator.SetLookAtPosition(reference.position);
animator.SetLookAtWeight(1f);

使用后玩家会看向reference的对象

IK相关操作请参考这篇:LINK

66.void SetTarget(AvatarTarget targetIndex, float targetNormalizedTime)

[人形动画]在动画播放前得到播放后的坐标和旋转。

关于SetTarget具体请看这篇LINK

67.void StartPlayback()

开始回放，录制与回放具体请看这篇LINK

68.void StartRecording(int frameCount)

开始录制

注意参数中的frameCount是需要录制长度的帧数

如果参数小于1，则不会限制录制时间

录制与回放具体请看这篇LINK

69.void StopPlayback()

停止回放，录制与回放具体请看这篇LINK

70.void StopRecording()

停止录制，录制与回放具体请看这篇LINK

71.void Update(float deltaTime)

Animator直接开放出了Update接口，如果你只是想更新动画信息而不前进播放动画，deltaTime参数可以设为0

在做下一个状态指向判断时，非常有效

72.GetSet各类型参数系列(SetFloat,SetBool等等)

最常用的接口

但需要注意下float类型数据，可以单独设置阻尼，具体看这篇LINK

73.AnimatorClipInfo[] GetNextAnimatorClipInfo(int layerIndex)

返回下一个状态的剪辑信息，如果没有下一个状态返回该结构体的默认值

经过测试，修改过播放信息并不会立即执行，会在Animator刷新时更新该值，或者手动调用Animator的Update更新该值

74.AnimatorStateInfo GetNextAnimatorStateInfo(int layerIndex)

返回下一个状态的信息，如果没有下一个状态返回该结构体的默认值

经过测试，修改过播放信息并不会立即执行，会在Animator刷新时更新该值，或者手动调用Animator的Update更新该值