> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/avatar-animations.md).

# 아바타 애니메이션

플레이어의 아바타가 기본 또는 사용자 지정 애니메이션을 재생하도록 하고, 이모트가 끝나는 시점을 감지합니다

씬 코드의 일부로 플레이어가 애니메이션을 수행하게 할 수 있습니다. 이렇게 하면 몰입감을 높일 수 있으며, 플레이어들이 서로 무엇을 하고 있는지 전달하는 데도 도움이 됩니다. 아바타 애니메이션은 플레이어(3인칭 시점)와 주변의 다른 플레이어 모두에게 보입니다.

플레이어가 제어하는 전신 애니메이션은 걷기나 점프 같은 기본 이동 애니메이션으로 덮어써집니다. 따라서 씬에서 재생하는 전신 애니메이션은 플레이어가 가만히 서 있을 때만 재생됩니다. 플레이어가 걷거나 점프하면 전신 애니메이션이 중단됩니다. 상체 애니메이션은 움직임으로 인해 중단되지 않습니다.

{% hint style="warning" %}
**📔 참고**: 플레이어가 씬 경계 안에 이미 서 있는 경우에만 애니메이션을 재생할 수 있으며, 인접한 씬에 있는 플레이어에게는 재생할 수 없습니다. 스마트 웨어러블은 어디서나 애니메이션을 재생할 수 있습니다.

플레이어가 애니메이션을 수행하는 동안에는 충돌의 영향을 받지 않으며, 움직임도 씬의 물리 법칙에 제약되지 않습니다. 또한 애니메이션으로 인해 플레이어가 원래 위치에서 벗어나더라도(예: 점프 동작이 포함된 경우) 이 이동은 플레이어의 Transform 컴포넌트에 반영되지 않습니다.
{% endhint %}

### 씬 편집기 사용

플레이어가 애니메이션을 수행하게 하는 가장 쉬운 방법은 씬 편집기를 사용하는 것입니다. 코드 없이 사용할 수 있는 **감정 표현 재생** 액션으로 기본 애니메이션을 재생하거나, **사용자 지정 감정 표현 재생** 액션으로 파일에 있는 애니메이션을 재생하세요. 자세한 내용은 다음을 참조하세요. [모든 아이템을 스마트 웨어러블로 만들기](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/interactivity/make-any-item-smart.md).

### 기본 애니메이션

다음 `triggerEmote()` 함수를 사용하면 Decentraland 어디서나 플레이어가 재생할 수 있는 기본 애니메이션 중 하나를 실행할 수 있습니다. 이 함수에는 다음 속성을 가진 객체를 인수로 전달합니다.

* `predefinedEmote`: 기존 감정 표현의 문자열 이름입니다.
* `mask`: (선택 사항) 아바타 신체의 일부에만 애니메이션을 재생합니다. 이때 `AvatarMask` 열거형의 값을 사용합니다. 예를 들어, `AvatarMask.AM_UPPER_BODY` 는 아바타의 상체에만 애니메이션을 적용합니다. 자세한 내용은 다음을 참조하세요. [상체에만 애니메이션 적용](#animate-only-the-upper-body).

```ts
import { triggerEmote } from '~system/RestrictedActions'

const emoter = engine.addEntity()
Transform.create(emoter, { position: Vector3.create(8, 0, 8) })
MeshRenderer.setBox(emoter)
MeshCollider.setBox(emoter)
pointerEventsSystem.onPointerDown(
	{
		entity: emoter,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Dance' },
	},
	() => {
		triggerEmote({ predefinedEmote: 'robot' })
	}
)
```

다음 감정 표현은 씬에서 플레이어의 행동에 대한 피드백을 보여 줍니다. 모두 `predefinedEmote` 필드에 사용할 수 있는 값입니다.

* `buttonDown`
* `buttonFront`
* `getHit`
* `knockOut`
* `lever`
* `openChest`
* `openDoor`
* `punch`
* `push`
* `swingWeaponOneHand`
* `swingWeaponTwoHands`
* `throw`
* `sittingChair1`
* `sittingChair2`
* `sittingGround1`
* `sittingGround2`

네 가지 `sitting`  이모트는 반복 재생됩니다. 플레이어가 움직이거나 씬에서 다음을 호출할 때까지 아바타가 해당 자세를 유지합니다. `stopEmote({})`. `stopEmote` 는 다음 값을 반환합니다: `{ success: boolean }`. 여기서 `false` 는 Explorer가 호출을 거부했음을 의미합니다. 예를 들어 플레이어가 더 이상 씬에 서 있지 않은 경우가 이에 해당합니다. 나머지 이모트는 한 번 재생된 다음 아바타가 대기 상태로 돌아갑니다.

이 이모트는 모든 플레이어의 기본 이모트 휠에서 사용할 수 있으며, 모든 씬에서도 사용할 수 있습니다.

* `wave`
* `fistpump`
* `robot`
* `raiseHand`
* `clap`
* `money`
* `kiss`
* `tik`
* `hammer`
* `tektonik`
* `dontsee`
* `handsair`
* `shrug`
* `disco`
* `dab`
* `headexplode`
* `crafting`
* `handsintheair`
* `Victory`
* `Waving`
* `fistpump_short`

`cry` 및 `dance` 도 `predefinedEmote`에 사용할 수 있는 유효한 값입니다. Creator Hub의 **Avatar Animations** 팩에는 나와 있지 않지만 사용할 수 있습니다.

{% hint style="warning" %}
**📔 참고**: 여기에 나열된 이름을 정확히 사용하세요. 이름이 잘못되면 씬에서 아무런 오류 표시 없이 실패합니다. 아무것도 재생되지 않고 씬 콘솔에도 아무것도 표시되지 않습니다. 구분 기호 없이 입력하는 `handsintheair` 와 접미사가 붙는 `fistpump_short` 에 주의하세요.
{% endhint %}

{% hint style="info" %}
**💡 팁**: 애니메이션이 재생되는 동안 플레이어가 걷거나 점프하면 애니메이션이 중단됩니다. 이를 방지하려면 다음을 사용해 아바타를 고정할 수 있습니다. [입력 수정자](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/locomotion.md#freeze-the-player) 아바타 애니메이션이 재생되는 동안.
{% endhint %}

### 사용자 지정 애니메이션

사용 `triggerSceneEmote()` 함수를 사용해 플레이어가 사용자 지정 애니메이션을 수행하게 할 수 있습니다. 사용자 지정 애니메이션은 장면 에셋의 일부로 .glb 파일에 저장됩니다.

{% hint style="info" %}
**💡 팁**: 직접 만들 필요는 없습니다. **Avatar Animations** Scene Editor의 팩에는 앉은 자세, 낚시, 상자 들기, 춤추기 등을 포함한 45개의 애니메이션이 준비되어 있습니다. 3D 뷰에 하나를 끌어다 놓으면 편집기가 해당 파일을 장면에 복사합니다. 그런 다음 파일 경로를 `triggerSceneEmote()`에 전달하세요. 파일은 `assets/asset-packs/<animation-folder>/`아래에 저장됩니다. 예를 들면 `assets/asset-packs/whack/Whack_Avatar_emote.glb`입니다. 정확한 경로는 **로컬 에셋**에서 확인하세요. [아이템 추가](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/get-started/about-editor.md#avatar-animations).
{% endhint %}

{% hint style="warning" %}
**📔 참고**: 파일 이름은 **반드시** 다음으로 끝나야 합니다: `_emote.glb` 아바타 애니메이션으로 작동하려면 이 규칙을 따라야 합니다.
{% endhint %}

이 함수는 다음 속성이 포함된 객체를 받습니다:

* `src`: 이모트 파일의 전체 경로입니다. 프로젝트의 루트 폴더를 기준으로 지정합니다. 다음 위치의 파일에는 `assets/animations/sit_emote.glb` 다음 값을 지정해야 합니다: `'assets/animations/sit_emote.glb'`.
* `loop`: true이면 플레이어가 움직이거나 애니메이션이 중지될 때까지 애니메이션이 계속 반복됩니다. 기본값은 false입니다.
* `mask`: (선택 사항) 아바타 신체의 일부에만 애니메이션을 재생합니다. 이때 `AvatarMask` 열거형의 값을 사용합니다. 예를 들어, `AvatarMask.AM_UPPER_BODY` 는 아바타의 상체에만 애니메이션을 적용합니다. 자세한 내용은 다음을 참조하세요. [상체에만 애니메이션 적용](#animate-only-the-upper-body).

{% hint style="warning" %}
**📔 참고**: `src` 에는 파일의 전체 경로를 지정해야 합니다. 파일 이름으로 검색하지 않으며, `_emote` 접미사가 자동으로 추가되지 않습니다. 경로가 잘못되면 `triggerSceneEmote()` 는 `{ success: false }` 를 반환하고 애니메이션이 재생되지 않습니다. 프로젝트 폴더에서 경로를 복사하고 모든 폴더를 포함하세요.
{% endhint %}

```ts
import { triggerSceneEmote } from '~system/RestrictedActions'
import { AvatarMask } from '@dcl/sdk/ecs'

const emoter = engine.addEntity()
Transform.create(emoter, { position: Vector3.create(8, 0, 8) })
MeshRenderer.setBox(emoter)
MeshCollider.setBox(emoter)
pointerEventsSystem.onPointerDown(
	{
		entity: emoter,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Make snowball' },
	},
	() => {
		triggerSceneEmote({ src: 'assets/animations/Snowball_Throw_emote.glb', loop: false, mask: AvatarMask.AM_UPPER_BODY })
	}
)
```

{% hint style="info" %}
**💡 팁**: 애니메이션이 재생되는 동안 플레이어가 걷거나 점프하면 애니메이션이 중단됩니다. 이를 방지하려면 다음을 사용해 아바타를 고정할 수 있습니다. [입력 수정자](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/locomotion.md#freeze-the-player) 아바타 애니메이션이 재생되는 동안.
{% endhint %}

#### 소품, 파티클 및 사운드

함수를 사용해 재생하는 이모트 파일에는 `triggerSceneEmote()` 아바타와 함께 애니메이션되는 테니스 라켓이나 불꽃 분사 같은 소품을 포함할 수 있습니다. Emotes 2.0 이모트와 같은 방식으로 만들고, 다음에 설명된 이름 지정 규칙을 따르세요: [소품 및 사운드](https://docs.decentraland.org/creator/content-creator-ko/wearables-and-emotes/emotes/props-and-sounds.md):

* 파일에는 애니메이션 클립이 두 개 있습니다. 이름에 다음이 포함된 클립 하나는 `_Avatar` 아바타용이며, 이름에 다음이 포함된 클립 하나는 `_Prop` 소품 아마추어용입니다.
* 두 클립의 길이는 같습니다.
* 파티클 효과는 애니메이션 본으로 변환하면 작동합니다. 자세한 내용은 다음을 참조하세요. [이모트의 파티클](https://docs.decentraland.org/creator/content-creator-ko/wearables-and-emotes/emotes/particles-in-emotes.md).

주변의 다른 플레이어도 아바타 애니메이션을 보는 것처럼 소품을 볼 수 있습니다.

{% hint style="warning" %}
**📔 참고**: `triggerSceneEmote()` 는 사운드를 재생하지 않습니다. 오디오는 Builder에서 독립형 이모트로 업로드한 이모트에서만 재생됩니다. 장면 이모트에 사운드를 연결하려면 다음과 동시에 재생하세요: [AudioSource](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/sounds.md) 입니다.
{% endhint %}

### 상체만 애니메이션

둘 다 `triggerEmote()` 및 `triggerSceneEmote()` 선택적 `mask` 속성을 받아 애니메이션을 아바타 신체의 일부에만 적용할 수 있습니다.

일반적으로 플레이어가 걷거나 점프하면 애니메이션이 즉시 멈춥니다. 기본 이동 애니메이션이 몸 전체를 제어하기 때문입니다. 다음과 같이 설정하면 `mask` 을 `AvatarMask.AM_UPPER_BODY`, 애니메이션은 허리 위쪽만 제어하고 다리는 기본 이동 애니메이션이 계속 제어합니다. 따라서 상체에서 애니메이션이 재생되는 동안에도 플레이어는 장면 안을 계속 걷거나 달릴 수 있습니다. 상자를 들거나 횃불을 들고 있거나 저글링하는 것처럼 이동을 중단시키지 않아야 하는 동작에 사용하세요.

```ts
import { triggerSceneEmote } from '~system/RestrictedActions'
import {
	engine,
	AvatarMask,
	InputAction,
	MeshCollider,
	MeshRenderer,
	pointerEventsSystem,
	Transform,
} from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const cheerButton = engine.addEntity()
Transform.create(cheerButton, { position: Vector3.create(8, 0, 8) })
MeshRenderer.setBox(cheerButton)
MeshCollider.setBox(cheerButton)
pointerEventsSystem.onPointerDown(
	{
		entity: cheerButton,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Cheer' },
	},
	() => {
		triggerSceneEmote({
			src: 'assets/animations/Cheer_emote.glb',
			loop: true,
			mask: AvatarMask.AM_UPPER_BODY,
		})
	}
)
```

이 예제에서는 플레이어가 버튼을 클릭하면 팔을 들고 응원하는 동작을 반복 애니메이션으로 시작합니다. 상체만 애니메이션으로 움직이므로, 응원하면서도 장면 속을 계속 달릴 수 있습니다. 예를 들어 경주나 축구 경기에서 상황을 따라갈 수 있습니다.

다음 사항에 유의하세요:

* `AvatarMask.AM_UPPER_BODY` 는 현재  `AvatarMask`  열거형의 유일한 값입니다. 전신에 애니메이션을 재생하려면  `mask`  속성을 설정하지 않으면 됩니다.
* 이  `loop`  속성은 전신 애니메이션에서와 동일하게 동작합니다. 다음과 같이 설정하면  `loop: false` 마스킹된 애니메이션은 한 번 재생된 후 상체가 일반적인 이동 애니메이션으로 돌아가며, `loop: true` 로 설정하면 중지할 때까지 반복됩니다.
* 코드에서 반복 재생 중인 마스킹된 애니메이션을 중지하려면 `stopEmote({})`를 호출하세요. 이 함수도 `~system/RestrictedActions`에서 가져옵니다. 이 함수는 `{ success: boolean }`.

### 이모트 종료 감지

모든 이모트 수명 주기 이벤트는 플레이어 엔티티의 `AvatarEmoteCommand` 컴포넌트를 통해 보고됩니다. 새 항목마다 `state` 필드가 포함되며, 그 값은 다음 `EmoteState` 열거형에서 가져옵니다.

* `EmoteState.ES_STARTED`: 이모트 재생이 시작되었습니다. 또한 `state` 필드가 없는 경우에도 이 값이 보고됩니다.
* `EmoteState.ES_FINISHED`: 반복 재생이 아닌 이모트가 자연스럽게 끝까지 재생되었습니다.
* `EmoteState.ES_INTERRUPTED`: 이모트가 중간에 중단되었습니다. 플레이어가 이동하거나 점프한 경우, 순간 이동한 경우, 다른 이모트가 시작된 경우, 이모트를 명시적으로 중지한 경우, 또는 플레이어가 장면을 떠난 경우입니다.

이 기능은 장면에서 트리거한 이모트(`triggerEmote()` 및 `triggerSceneEmote()`)뿐 아니라 플레이어가 이모트 휠을 통해 직접 재생하는 이모트, 장면의 다른 플레이어가 재생하는 이모트에도 적용됩니다.

각 새 항목에 반응하려면 `onChange` 함수를 `AvatarEmoteCommand` 컴포넌트에서 사용하세요.

```ts
import { AvatarEmoteCommand, EmoteState } from '@dcl/sdk/ecs'

export function main() {
	AvatarEmoteCommand.onChange(engine.PlayerEntity, (emote) => {
		if (!emote) return

		switch (emote.state ?? EmoteState.ES_STARTED) {
			case EmoteState.ES_STARTED:
				console.log('emote started: ', emote.emoteUrn)
				break
			case EmoteState.ES_FINISHED:
				console.log('emote finished naturally: ', emote.emoteUrn)
				break
			case EmoteState.ES_INTERRUPTED:
				console.log('emote was interrupted: ', emote.emoteUrn)
				break
		}
	})
}
```

{% hint style="warning" %}
**📔 참고**: 이 기능은 데스크톱 클라이언트에서만 지원됩니다. 로컬 플레이어에게서 `mask` (부분 신체 이모트)를 사용해 재생한 이모트는 현재 수명 주기 이벤트를 보고하지 않습니다.
{% endhint %}

{% hint style="info" %}
**💡 팁**: 플레이어가 아닌 아바타에서 애니메이션을 재생하는 방법은 다음을 참조하세요. [NPC 아바타](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/npc-avatars.md#animations).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/avatar-animations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
