애니메이션 이벤트 사용하기

14min
애니메이션 이벤트는 애니메이션 클립의 특정 시간에 사용자 정의 함수를 호출하거나 작업을 수행하는 방법을 제공합니다.
이는 애니메이션과 스크립트 간의 상호작용을 가능하게 하며, 애니메이션의 정확한 타이밍에 작업을 수행할 때 유용합니다.
﻿
객체 애니메이션에 이벤트 추가하기
다음 예제는 애니메이션 객체에 애니메이션 이벤트를 추가합니다.
이 구조는 위로 및 아래로 반복되는 애니메이션에 Up 이벤트와 Down 이벤트를 추가하여 이벤트가 실행될 때마다 정보를 콘솔 로그에 출력합니다.
﻿
﻿
1) 게임 오브젝트 > 3D 오브젝트 > 큐브를 선택하여 장면에 큐브를 생성합니다.
생성된 큐브를 선택하고 검사기 패널의 구성 요소 추가 버튼을 클릭하여 애니메이터 구성 요소를 추가합니다.
추가된 애니메이터에 큐브 애니메이터 컨트롤러를 적용합니다.
큐브 애니메이터 컨트롤러의 항목에 큐브 애니메이션 클립을 적용하여 장면이 재생될 때 큐브 애니메이션이 재생되도록 합니다.
﻿
﻿
애니메이터 등록 및 애니메이션 클립 편집에 대한 다음 가이드를 참조하십시오.
📘 유니티 애니메이션 이벤트 가이드
https://docs.unity3d.com/kr/current/Manual/script-AnimationWindowEvent.html﻿
📘 유니티 학습 애니메이션 튜토리얼
https://learn.unity.com/tutorial/may-18-animation?language=en#﻿
﻿
2) 다음 속성을 큐브 애니메이션 클립에 추가하십시오.
큐브 애니메이션 클립의 0초, 2초 구간에 위치 (x: 0, y:0, z:0)의 키프레임이 있습니다.
큐브 애니메이션 클립의 1초 구간에 위치 (x: 0, y:1, z:0)의 키프레임이 있습니다.
(1) 큐브 애니메이션 클립의 1초 구간에 애니메이션 이벤트를 등록하십시오.
기능 : 호출
문자열 : 위
(2) 큐브 애니메이션 클립의 2초 구간에 애니메이션 이벤트를 등록하십시오.
기능 : 호출
문자열 : 아래
﻿
﻿
Unity에서 C#을 통해 애니메이션 이벤트를 작성할 때, 함수 이름을 Function에 작성하십시오.
그러나 TypeScript에서 애니메이션 이벤트를 호출하려면, Invoke는 Funtion에 작성해야 하며 함수 이름은 String, 인수 값으로 작성해야 합니다.
﻿
3) 프로젝트 생성 > 생성 > ZEPETO > TypeScript로 이름을 ObjectAnimationController로 변경합니다.
아래와 같이 샘플 스크립트를 작성하십시오.
ObjectAnimationController.ts
import { ZepetoScriptBehaviour } from 'ZEPETO.Script'

export default class ObjectAnimationController extends ZepetoScriptBehaviour {

    public Up() {
        console.log(`Cube is Up`);
    }

    public Down(){
        console.log(`Cube is Down`);
    }
}
import { ZepetoScriptBehaviour } from 'ZEPETO.Script'

export default class ObjectAnimationController extends ZepetoScriptBehaviour {

    public Up() {
        console.log(`Cube is Up`);
    }

    public Down(){
        console.log(`Cube is Down`);
    }
}
﻿
4) 재생 버튼을 눌러 실행하면, 큐브의 애니메이션이 재생되는 동안 콘솔 로그 출력이 표시됩니다.
﻿
﻿
로컬 캐릭터의 애니메이션 이벤트를 사용하여 발자국 소리를 재생합니다.
ZEPETO 캐릭터의 애니메이터에 애니메이션 이벤트를 추가하려면, 캐릭터가 생성될 때 런타임에서 이벤트를 추가해야 합니다.
다음 예제는 런타임에서 로컬 플레이어 애니메이터의 특정 애니메이션 클립에 이벤트를 적용하고, 이벤트가 발생할 때 발자국 소리를 재생합니다.
1) 로컬 플레이어의 애니메이터 객체에 적용될 FootStepController 스크립트를 생성합니다. FootStepController는 애니메이터에 애니메이션 이벤트를 추가하는 역할을 합니다.
프로젝트 생성 > 생성 > ZEPETO > TypeScript로 이름을 FootStepController로 변경합니다.
아래와 같이 스크립트를 작성합니다.
FootStepController.ts
import { AnimationEvent, Animator, AudioClip, AudioSource } from 'UnityEngine';
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';

export default class FootStepController extends ZepetoScriptBehaviour {

    // 발자국 효과에 사용되는 소리
    public footStepSound: AudioClip;

    // 발자국 소리를 재생하기 위한 오디오 소스
    private _zepetoAudio: AudioSource;

    // 발자국 소리를 트리거하기 위해 애니메이션 이벤트를 추가합니다
    public AddAnimationEvent() {
        
        // 이 GameObject에 연결된 Animator 컴포넌트를 가져옵니다
        const anim = this.GetComponent<Animator>();

        // Animator 컴포넌트가 존재하는지 확인합니다
        if (anim != null) {
            // 발자국 소리를 위한 AudioSource를 생성합니다
            this.SetAudio();

            // 애니메이션 클립에서 발자국 소리가 재생되어야 하는 시간을 지정합니다
            const runSoundEventTimes = [0.1, 0.6];

            // 지정된 애니메이션 클립에 애니메이션 이벤트를 추가합니다
            this.AddAnimationClipEvent(anim, "move_walk", runSoundEventTimes);
        }
    }

    // 발자국 소리를 재생하기 위한 AudioSource를 설정합니다
    private SetAudio() {

        // AudioSource 컴포넌트를 생성하고 구성합니다
        this._zepetoAudio = this.gameObject.AddComponent<AudioSource>();
        this._zepetoAudio.clip = this.footStepSound;
    }

    // 발자국 소리를 활성화합니다
    public ActivateFootSteps() {

        // 발자국 소리가 재생되고 있음을 나타내는 로그 메시지를 출력합니다
        console.log("FootSteps!");

        // 구성된 AudioSource를 사용하여 발자국 소리를 재생합니다
        this._zepetoAudio.Play();
    }

    // 지정된 애니메이션 클립에 애니메이션 이벤트를 추가합니다
    private AddAnimationClipEvent(anim: Animator, clipName: string, eventTimes: number[]) {

        // 애니메이션 클립의 인덱스를 초기화합니다
        let animationClipIndex: number;

        // runtimeAnimatorController에서 모든 애니메이션 클립을 가져옵니다
        const clips = anim.runtimeAnimatorController.animationClips;

        // 지정된 애니메이션 클립의 인덱스를 찾습니다
        for (let i = 0; i < clips.length; i++) {
            if (clips[i].name == clipName) {
                animationClipIndex = i;
            }
        }

        // 지정된 이벤트 시간을 반복합니다
        eventTimes.forEach(eventTime => {

            // 발자국 소리 트리거를 위한 새로운 AnimationEvent를 생성합니다
            const newEvent: AnimationEvent = new AnimationEvent();
            newEvent.time = eventTime;
            newEvent.functionName = "Invoke";
            newEvent.stringParameter = "ActivateFootSteps";

            // 애니메이션 클립에 새로운 AnimationEvent를 추가합니다
            clips[animationClipIndex].AddEvent(newEvent);
        });
    }
}
import { AnimationEvent, Animator, AudioClip, AudioSource } from 'UnityEngine';
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';

export default class FootStepController extends ZepetoScriptBehaviour {

    // 발자국 효과에 사용되는 소리
    public footStepSound: AudioClip;

    // 발자국 소리를 재생하기 위한 오디오 소스
    private _zepetoAudio: AudioSource;

    // 발자국 소리를 트리거하기 위해 애니메이션 이벤트를 추가합니다
    public AddAnimationEvent() {
        
        // 이 GameObject에 연결된 Animator 컴포넌트를 가져옵니다
        const anim = this.GetComponent<Animator>();

        // Animator 컴포넌트가 존재하는지 확인합니다
        if (anim != null) {
            // 발자국 소리를 위한 AudioSource를 생성합니다
            this.SetAudio();

            // 애니메이션 클립에서 발자국 소리가 재생되어야 하는 시간을 지정합니다
            const runSoundEventTimes = [0.1, 0.6];

            // 지정된 애니메이션 클립에 애니메이션 이벤트를 추가합니다
            this.AddAnimationClipEvent(anim, "move_walk", runSoundEventTimes);
        }
    }

    // 발자국 소리를 재생하기 위한 AudioSource를 설정합니다
    private SetAudio() {

        // AudioSource 컴포넌트를 생성하고 구성합니다
        this._zepetoAudio = this.gameObject.AddComponent<AudioSource>();
        this._zepetoAudio.clip = this.footStepSound;
    }

    // 발자국 소리를 활성화합니다
    public ActivateFootSteps() {

        // 발자국 소리가 재생되고 있음을 나타내는 로그 메시지를 출력합니다
        console.log("FootSteps!");

        // 구성된 AudioSource를 사용하여 발자국 소리를 재생합니다
        this._zepetoAudio.Play();
    }

    // 지정된 애니메이션 클립에 애니메이션 이벤트를 추가합니다
    private AddAnimationClipEvent(anim: Animator, clipName: string, eventTimes: number[]) {

        // 애니메이션 클립의 인덱스를 초기화합니다
        let animationClipIndex: number;

        // runtimeAnimatorController에서 모든 애니메이션 클립을 가져옵니다
        const clips = anim.runtimeAnimatorController.animationClips;

        // 지정된 애니메이션 클립의 인덱스를 찾습니다
        for (let i = 0; i < clips.length; i++) {
            if (clips[i].name == clipName) {
                animationClipIndex = i;
            }
        }

        // 지정된 이벤트 시간을 반복합니다
        eventTimes.forEach(eventTime => {

            // 발자국 소리 트리거를 위한 새로운 AnimationEvent를 생성합니다
            const newEvent: AnimationEvent = new AnimationEvent();
            newEvent.time = eventTime;
            newEvent.functionName = "Invoke";
            newEvent.stringParameter = "ActivateFootSteps";

            // 애니메이션 클립에 새로운 AnimationEvent를 추가합니다
            clips[animationClipIndex].AddEvent(newEvent);
        });
    }
}
﻿
스크립트 설명
FootStepController는 애니메이션 이벤트를 추가하고 해당 이벤트가 발생할 때 발자국 사운드 효과를 재생합니다.
SetAudio()는 오디오 소스 컴포넌트를 추가하여 발자국 소리를 객체에 적용합니다.
AddAnimationClipEvent()는 지정된 애니메이션 클립에 애니메이션 이벤트를 추가합니다. 다음 요소들을 인수 값으로 넣어야 합니다.
로컬 플레이어용 애니메이터
이벤트가 적용되는 애니메이션 클립 이름
이벤트를 적용할 애니메이션 시간의 배열
AddAnimationClipEvent()로 등록된 newEvent에서 다음 항목이 설정됩니다.
(1) newEvent.time : 이벤트가 발생할 때의 애니메이션 시간. 값이 0이면 전체 길이의 시작이고, 값이 1이면 전체 길이의 끝입니다.
(2) newEvent.functionName : 이벤트가 발생할 때 호출되는 함수의 이름. TypeScript에서는 "Invoke"로 타입을 지정해야 합니다.
(3) newEvent.stringParameter : 이벤트가 함수를 실행할 때 함수에 설정되는 매개변수 값. TypeScript는 실행될 함수의 이름을 나열합니다.
이벤트가 발생하면 ActivateFootSteps()가 실행되고 발자국 소리가 재생됩니다.
﻿
﻿
2) 이제 로컬 플레이어가 런타임에 생성될 때 로컬 플레이어의 Animator 객체에 FootStepController 구성 요소를 추가하는 FootStepManager를 생성합니다.
프로젝트 > 생성 > ZEPETO > TypeScript로 이름을 FootStepManager로 변경합니다.
스크립트를 아래와 같이 작성합니다.
FootStepManager.ts
import { SpawnInfo, ZepetoPlayers } from 'ZEPETO.Character.Controller'
import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
import FootStepController from './FootStepController'
import { WorldService } from 'ZEPETO.World'
import { AudioClip } from 'UnityEngine';

export default class FootStepManager extends ZepetoScriptBehaviour {

    // 발소리를 재생할 사운드
    public footStepSound: AudioClip;

    Start() {

        // 로컬 플레이어가 추가될 때의 이벤트 리스너
        ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {

            // 로컬 플레이어의 Zepeto 캐릭터에 접근
            const zepetoCharacter = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character;

            // ZepetoAnimator의 GameObject에 FootStepController 스크립트를 추가
            const footStepController = zepetoCharacter.ZepetoAnimator.gameObject.AddComponent<FootStepController>();

            // FootStepController에 footStepSound 설정
            footStepController.footStepSound = this.footStepSound;

            // 발소리를 재생하기 위한 애니메이션 이벤트 추가
            footStepController.AddAnimationEvent();

        });
    }

}
import { SpawnInfo, ZepetoPlayers } from 'ZEPETO.Character.Controller'
import { ZepetoScriptBehaviour } from 'ZEPETO.Script'
import FootStepController from './FootStepController'
import { WorldService } from 'ZEPETO.World'
import { AudioClip } from 'UnityEngine';

export default class FootStepManager extends ZepetoScriptBehaviour {

    // 발소리를 재생할 사운드
    public footStepSound: AudioClip;

    Start() {

        // 로컬 플레이어가 추가될 때의 이벤트 리스너
        ZepetoPlayers.instance.OnAddedLocalPlayer.AddListener(() => {

            // 로컬 플레이어의 Zepeto 캐릭터에 접근
            const zepetoCharacter = ZepetoPlayers.instance.LocalPlayer.zepetoPlayer.character;

            // ZepetoAnimator의 GameObject에 FootStepController 스크립트를 추가
            const footStepController = zepetoCharacter.ZepetoAnimator.gameObject.AddComponent<FootStepController>();

            // FootStepController에 footStepSound 설정
            footStepController.footStepSound = this.footStepSound;

            // 발소리를 재생하기 위한 애니메이션 이벤트 추가
            footStepController.AddAnimationEvent();

        });
    }

}
﻿
스크립트 설명
FootStepManager가 로컬 플레이어가 추가되고 있음을 감지하면, 플레이어의 ZepetoAnimator의 GameObject에 FootStepController 스크립트를 부착합니다.
FootStepController는 발소리를 재생하는 애니메이션 이벤트를 추가하는 역할을 합니다.
애니메이션 이벤트에 의해 실행되는 함수의 스크립트는 해당 Animator 컴포넌트가 적용된 객체에 동일하게 적용되어야 합니다.
따라서 ZepetoAnimator.gameObject를 찾아 FootStepController 스크립트를 AddComponent로 적용해야 합니다.
﻿
3) FootStepManager의 footStepSound에 발소리를 적용합니다.
﻿
﻿
4) 재생 버튼을 눌러 실행하면, 로컬 플레이어가 걸을 때마다 그에 따라 소리가 재생되는 것을 볼 수 있습니다.
﻿
﻿
👍 팁
ZEPETO 기본 애니메이터의 걷기 상태는 여러 애니메이션 블렌드와 상태로 구성됩니다.
예제는 move_walk 상태에만 소리를 적용하므로 AddAnimationClipEvent()를 사용자 정의하고 빠른 걷기 및 달리기와 같은 상태에 직접 입력할 수 있습니다.
여러 애니메이션 상태에 소리가 적용될 때 애니메이션 블렌드로 인해 발소리가 겹칠 수 있습니다. 이를 해결하기 위해 AnimationEvent.animatorClipInfo.weight가 0.5일 때 해당 소리가 재생되도록 추가 조건문을 작성하세요.
❗️ 알려진 문제
개발 가이드 스타일에 따라 구현할 경우 다음과 같은 오류 메시지가 나타날 수 있지만 실행에는 문제가 없어야 합니다.
﻿
﻿
업데이트됨 11 Oct 2024
이 페이지가 도움이 되었습니까?
Quarter View Example
캐릭터의 키 측정하기