Unity Animator Controller API 활용

기본 파라미터 제어

Animator anim;

void Update() {
    // 해시 사용이 string보다 빠름 (매 프레임 호출 시 캐싱 권장)
    anim.SetFloat("Speed", rb.velocity.magnitude);
    anim.SetBool("IsGrounded", isGrounded);
    anim.SetTrigger("Jump");
    anim.ResetTrigger("Jump");  // 트리거 수동 해제
}

파라미터 이름을 매 프레임 문자열로 조회하면 오버헤드가 있습니다. 해시로 캐싱하세요.

static readonly int SpeedHash     = Animator.StringToHash("Speed");
static readonly int IsGroundedHash = Animator.StringToHash("IsGrounded");
static readonly int JumpHash      = Animator.StringToHash("Jump");

void Update() {
    anim.SetFloat(SpeedHash, rb.velocity.magnitude);
    anim.SetBool(IsGroundedHash, isGrounded);
}

현재 상태 정보 조회

void Update() {
    // 레이어 0의 현재 상태 정보
    AnimatorStateInfo state = anim.GetCurrentAnimatorStateInfo(0);

    if (state.IsName("Run"))
        Debug.Log("달리는 중");

    // 정규화된 재생 위치 (0~1)
    float progress = state.normalizedTime % 1f;

    // 전환 중인지 확인
    if (anim.IsInTransition(0)) {
        AnimatorTransitionInfo trans = anim.GetAnimatorTransitionInfo(0);
        Debug.Log($"전환 진행: {trans.normalizedTime:P0}");
    }
}

다음 상태 예측

AnimatorStateInfo next = anim.GetNextAnimatorStateInfo(0);
if (next.IsName("Death")) {
    // 죽음 애니메이션으로 전환 예정 → 선제 처리
    DisableCollider();
}

Animator Override Controller

같은 State Machine 구조에서 클립만 교체하는 방법입니다.

AnimatorOverrideController overrideCtrl;

void Start() {
    overrideCtrl = new AnimatorOverrideController(anim.runtimeAnimatorController);
    anim.runtimeAnimatorController = overrideCtrl;
}

void EquipWeapon(AnimationClip attackClip) {
    // "Attack" 상태의 클립만 교체
    overrideCtrl["Attack"] = attackClip;
}

// 여러 클립 일괄 교체 (GC 절약)
void ApplySkin(List<KeyValuePair<AnimationClip, AnimationClip>> overrides) {
    overrideCtrl.ApplyOverrides(overrides);
}

레이어 블렌딩

// 레이어 1(상체 레이어) 가중치를 부드럽게 전환
float upperBodyWeight = 0f;

IEnumerator AimRoutine() {
    while (upperBodyWeight < 1f) {
        upperBodyWeight = Mathf.MoveTowards(upperBodyWeight, 1f, Time.deltaTime * 3f);
        anim.SetLayerWeight(1, upperBodyWeight);
        yield return null;
    }
}

IK 패스 활용

Avatar에서 IK Pass를 활성화하면 OnAnimatorIK가 호출됩니다.

void OnAnimatorIK(int layerIndex) {
    if (aimTarget == null) return;

    // 오른손을 목표 위치로
    anim.SetIKPositionWeight(AvatarIKGoal.RightHand, 1f);
    anim.SetIKPosition(AvatarIKGoal.RightHand, aimTarget.position);

    // 시선 방향
    anim.SetLookAtWeight(0.7f);
    anim.SetLookAtPosition(aimTarget.position);
}

StateMachineBehaviour

상태 진입/이탈 시 로직을 Animator 내에서 직접 처리합니다.

public class AttackStateBehaviour : StateMachineBehaviour {
    public override void OnStateEnter(Animator animator, AnimatorStateInfo info, int layerIndex) {
        animator.GetComponent<Weapon>().EnableHitbox();
    }

    public override void OnStateExit(Animator animator, AnimatorStateInfo info, int layerIndex) {
        animator.GetComponent<Weapon>().DisableHitbox();
    }
}

정리

• 파라미터 접근은 Animator.StringToHash로 캐싱해 매 프레임 오버헤드 제거
• GetCurrentAnimatorStateInfo / GetNextAnimatorStateInfo로 상태 조회 및 예측
• AnimatorOverrideController로 State Machine 재사용하면서 클립만 교체
• SetLayerWeight로 런타임에 상체/하체 레이어 블렌딩 제어
• StateMachineBehaviour로 상태 진입/이탈 이벤트를 Animator에 직접 연결