> 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/npc-avatars.md).

# NPC 아바타

NPC 아바타 표시 및 제어

아바타를 씬의 엔티티로 표시합니다.

{% hint style="info" %}
**💡 팁**: NPC를 더 쉽게 다루려면 [NPC Toolkit 라이브러리](https://github.com/decentraland-scenes/dcl-npc-toolkit) 를 사용해 보세요. 특히 대화 트리를 통해 상호작용해야 하는 경우 유용합니다.
{% endhint %}

## 아바타 만들기

다음 코드 조각은 웨어러블과 체형을 무작위로 설정하고 이름을 "NPC"로 지정한 아바타를 만듭니다.

```ts
const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar)

Transform.create(myAvatar, {
	position: Vector3.create(4, 0.25, 5),
})
```

데이터를 전달해 `AvatarShape`을 생성할 때는 다음 필드가 필수입니다.

* `id`: (필수) 아바타의 내부 식별자입니다. 마지막 4개 문자는 `id` NPC 이름 뒤에 플레이어 지갑 주소의 접미사처럼 흐리게 표시됩니다. 4자보다 `id` 짧으면 `0000`이 표시됩니다. 각 NPC에 `id` 이름 옆에 표시했을 때 자연스럽게 읽히는 끝부분이 포함된 `'guide-0001'`.

다음과 같은 선택 필드도 사용할 수 있습니다.

* `name`: 아바타 머리 위에 표시할 이름입니다. 기본값은 "NPC"입니다. 이름을 표시하지 않으려면 빈 문자열로 설정하세요. NPC 위에 [아바타 이름표](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/avatar-nametags.md) 판만 표시하려는 경우에 유용합니다.
* `bodyShape`: 사용할 체형을 지정하는 문자열입니다. 유효한 옵션은 'urn:decentraland:off-chain:base-avatars:BaseMale' 및 'urn:decentraland:off-chain:base-avatars:BaseFemale'입니다.
* `wearables`: 아바타가 현재 착용 중인 웨어러블의 URN 목록입니다. 웨어러블이 충돌하는 경우(예: 모자가 두 개 있는 경우) 목록의 마지막 항목이 다른 항목을 대체합니다.
* `emotes`: 아바타가 재생할 수 있는 NFT 이모트의 URN 목록입니다.
* `eyeColor`: *Color3* 눈 색상입니다(모든 색상 사용 가능).
* `skinColor`: *Color3* 피부 색상입니다(모든 색상 사용 가능).
* `hairColor`: *Color3* 머리카락 색상입니다(모든 색상 사용 가능).
* `talking`: *true*로 설정하면 월드에서 플레이어가 음성 채팅을 사용할 때처럼 이름 옆에 녹색 막대가 표시됩니다.
* <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>💡 팁</strong>: 색상 설정 방법에 대한 자세한 내용은 <a href="https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/color-types.md">색상 유형</a> 을 참조하세요.</p></div>

{% hint style="warning" %}
**📔 참고**:  `AvatarShape` 컴포넌트는 다음을 통해 가져와야 합니다.

> `import { AvatarShape } from "@dcl/sdk/ecs"`

자세한 내용은 [가져오기](https://docs.decentraland.org/creator/content-creator-ko/sdk7/getting-started/coding-scenes.md#imports) 에서 쉽게 처리하는 방법을 확인하세요.
{% endhint %}

{% hint style="warning" %}
**📔 참고**: URN 필드는 다음과 동일한 형식을 따라야 합니다. [NFTShapes](https://docs.decentraland.org/creator/content-creator-ko/sdk7/media/display-a-certified-nft.md): `urn:decentraland:<CHAIN>:<CONTRACT_STANDARD>:<CONTRACT_ADDRESS>:<TOKEN_ID>`
{% endhint %}

## NPC 이동

NPC를 이동하려면 다음을 변경합니다. `position` 의 `Transform`. 아바타는 새 위치로 순간 이동하지 않습니다. 현재 위치에서 초당 약 4미터의 속도로 걸어가며, 목표 지점이 1.5미터 이상 떨어져 있으면 더 빠르게 이동합니다. 이동하는 동안 걷는 방향을 바라보도록 몸을 돌립니다. 설정한 `rotation` 은 `Transform` 아바타가 도착한 후에만 적용됩니다.

```ts
// NPC가 현재 위치에서 새 위치까지 걸어갑니다
Transform.getMutable(myAvatar).position = Vector3.create(10, 0.25, 5)
```

이동을 직접 제어하려면 다음을 사용하세요. [트윈](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/move-entities.md). 위치에 트윈을 적용하면 자동 이동이 대체되고, 회전에 트윈을 적용하면 NPC가 이동 방향을 바라보도록 회전하지 않습니다. 엔티티에는 한 번에 하나의 트윈만 적용할 수 있으므로, 같은 엔티티의 위치와 회전을 동시에 트윈할 수 없습니다.

## 애니메이션

아바타는 정지해 있을 때 기본 대기 애니메이션을 재생합니다.

아바타에서 애니메이션을 재생하려면 `expressionTriggerId` 문자열을 재생하려는 애니메이션 이름으로 설정합니다.

```ts
const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar, {
	id: 'dancer-0001',
	emotes: [],
	wearables: [],
	expressionTriggerId: 'robot',
})

Transform.create(myAvatar, {
	position: Vector3.create(4, 0.25, 5),
})
```

&#x20;`expressionTriggerId`  필드는 모든 [기본 애니메이션](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/avatar-animations.md#default-animations)과 사용자 지정 애니메이션 [을 장면 파일에서](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/avatar-animations.md#custom-animations)가져올 수 있으며, 마켓플레이스에 게시된 이모트의 URN도 사용할 수 있습니다.

사용자 지정 애니메이션을 사용하려면 다음 파일의 경로를 지정하세요: `_emote.glb` 프로젝트 루트 폴더의 파일입니다. 예를 들면 `'assets/animations/Cheer_emote.glb'`. [`triggerSceneEmote()`](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/avatar-animations.md#custom-animations)와 마찬가지로 경로가 잘못되면 아무것도 재생되지 않습니다.

{% hint style="warning" %}
**📔 참고**: `AvatarShape` 에는 `mask` 필드가 없으므로, `expressionTriggerId` 애니메이션은 항상 전신에 재생됩니다. [상체만 애니메이션화하는 기능은](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/avatar-animations.md#animate-only-the-upper-body) NPC가 아니라 플레이어 자신의 아바타에서 사용할 수 있습니다.
{% endhint %}

### 이모트를 재생하는 동안 NPC 이동하기

아바타의 `Transform.position`를 변경하거나 [Tween](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/move-entities.md) 을 실행하면 재생 중인 이모트가 취소됩니다. 아바타는 걷기 애니메이션으로 돌아갑니다. Decentraland는 아바타가 마지막 프레임 이후 얼마나 이동했는지를 바탕으로 어떤 이동 애니메이션을 혼합할지 결정하기 때문입니다.

이모트를 재생하는 동안 NPC를 이동하려는 경우, 이동 범위가 좁다면 다음 파일의 루트 또는 엉덩이 움직임처럼 애니메이션 자체에 움직임을 포함하는 방법을 고려해 볼 수 있습니다. `_emote.glb`  파일입니다.

### 애니메이션 반복 재생

AvatarShape의 `AvatarShape`  애니메이션은 한 번만 재생됩니다. 아바타가 애니메이션을 계속 반복 재생하게 하려면 몇 초마다 애니메이션을 다시 재생하도록 지시하는 시스템을 만들어야 합니다.

예외는 반복 재생되는 기본 이모트인 `sittingChair1`, `sittingChair2`, `sittingGround1` 및 `sittingGround2`입니다. 이 이모트는 `AvatarShape` 에서 다시 재생하지 않아도 자세를 유지합니다. 파일에서 가져온 사용자 지정 애니메이션은 클립 자체가 반복 재생으로 표시되어 있더라도 `AvatarShape`에서 반복 재생되지 않으므로, 사용자 지정 자세를 유지하려면 아래의 다시 재생 패턴을 사용해야 합니다.

같은 이모트를 다시 재생하려면 `expressionTriggerTimestamp` 를 사용합니다. 이 필드의 값은 [램포트 타임스탬프](https://en.wikipedia.org/wiki/Lamport_timestamp)입니다. 즉, 시간 값이 아니라 이모트가 반복될 때마다 1씩 증가하는 인덱스입니다.

따라서 이모트를 처음 재생할 때는 `expressionTriggerTimestamp` 를 *0*로 설정합니다. 이모트를 다시 재생하려면 이 값을 1로 업데이트해야 합니다. 이렇게 해야 엔진이 이를 이미 처리한 명령이 아니라 새로운 명령으로 인식합니다.

다음 코드 조각은 같은 이모트를 2초마다 실행하는 시스템을 만듭니다.

```ts
const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar, {
	id: 'fan-0001',
	emotes: [],
	wearables: [],
	expressionTriggerId: 'clap',
    expressionTriggerTimestamp: 0
})

Transform.create(myAvatar, {
	position: Vector3.create(4, 0.25, 5),
})

let clapTimer = 0
let emoteDuration = 2  // 2 seconds

// system
engine.addSystem((dt: number) => {
    clapTimer += dt
      
    if (clapTimer >= emoteDuration) {
        // Trigger the clap emote
        AvatarShape.getMutable(myAvatar).expressionTriggerTimestamp += 1
        
        clapTimer = 0 // Reset timer
    }
})
```

{% hint style="info" %}
**💡 팁**: 이모트의 재생 시간을 파악하고 시스템의 지속 시간으로 설정해야 합니다. 아바타가 같은 자세를 유지하는 이모트를 만들었다면, 이모트의 재생 시간을 시스템보다 길게 설정하는 것이 좋습니다. 그러면 애니메이션이 끝나고 초기화될 때 아티팩트가 발생하지 않도록 할 수 있습니다.
{% endhint %}

## 이름 위에 라벨 추가

다음 `AvatarNametag` 컴포넌트를 사용하면 NPC의 이름 위에 "상점 주인"이나 "보스"와 같은 역할 등 원하는 텍스트가 담긴 표찰을 표시할 수 있습니다. 이 컴포넌트는 다음 컴포넌트가 있는 동일한 엔티티에 부착하세요. `AvatarShape`:

```ts
AvatarNametag.create(myAvatar, { label: 'Shopkeeper' })
```

만약 `AvatarShape` 의 `name`이 비어 있으면 표찰만 표시되고 그 아래에 빈 이름표 상자는 나타나지 않습니다. NPC에 칭호만 표시할 때 유용합니다.

{% hint style="info" %}
**💡 팁**: 텍스트 없이 색상으로 구분된 표찰을 표시하려면 `label` 을 공백으로 이루어진 문자열로 설정하고 `backgroundColor`를 선택하세요. 공백은 그대로 유지되므로 공백이 많을수록 표찰이 넓어집니다.

```ts
AvatarNametag.create(myAvatar, {
	label: '      ',
	backgroundColor: Color3.Red(),
})
```

{% endhint %}

색상을 포함한 전체 필드 목록은 [아바타 이름표](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/avatar-nametags.md) 를 참고하세요.

## 플레이어의 웨어러블 복사

다음 코드는 NPC 아바타의 웨어러블과 기타 특성을 플레이어가 현재 착용하고 있는 것과 일치하도록 변경합니다. 이를 씬에서 마네킹으로 활용해 플레이어의 현재 의상과 함께 특정 웨어러블이나 이모트를 선보일 수 있습니다.

```ts
import { getPlayer } from '@dcl/sdk/src/players'


export function swapAvatar(avatar: Entity) {

  let userData = getPlayer()
  console.log(userData)

  if (!userData || !userData.wearables) return

  const mutableAvatar = AvatarShape.getMutable(avatar)

  mutableAvatar.wearables = userData.wearables
  mutableAvatar.bodyShape = userData.avatar?.bodyShapeUrn
  mutableAvatar.eyeColor = userData.avatar?.eyesColor
  mutableAvatar.skinColor = userData.avatar?.skinColor
  mutableAvatar.hairColor = userData.avatar?.hairColor
  
}
```

## 웨어러블만 표시

다음 `showOnlyWearables` 필드를 사용하면 아바타에서 목록에 지정된 웨어러블만 표시할 수 있습니다. 아바타의 나머지 신체는 보이지 않습니다.

```ts
const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar, {
	id: 'mannequin-0001',
	emotes: [],
	wearables: [
    'urn:decentraland:matic:collections-v2:0x90e5cb2d673699be8f28d339c818a0b60144c494:0'
  ],
	showOnlyWearables: true,
})

Transform.create(myAvatar, {
	position: Vector3.create(4, 0.25, 5),
})
```

이 기능은 상점 등에서 웨어러블을 전시할 때 유용합니다.

{% hint style="info" %}
**💡 팁**: 웨어러블이 너무 작다면 `scale` 필드를 가진 `Transform` 에서 해당 필드를 더 큰 값으로 설정해 보세요.
{% endhint %}

## NPC에 엔티티 부착

다음을 사용할 수 있습니다. `AvatarAttach` NPC 아바타의 뼈대 중 하나에 엔터티를 고정하는 기능입니다. 예를 들어 NPC가 손에 물체를 들고 있게 할 수 있습니다. 아바타가 애니메이션을 재생하면 엔터티도 함께 움직입니다.

이 기능을 사용하려면 `id` 속성을 `AvatarShape` 에 사용해 이 아바타에 임의의 ID를 지정한 다음, 그 ID를 `AvatarAttach`에서 참조합니다. ID는 원하는 문자열로 지정할 수 있습니다.

```ts
// ID를 지정해 NPC 생성
const myAvatar = engine.addEntity()
Transform.create(myAvatar, {
  position: Vector3.create(8, 0.25, 8),
})
AvatarShape.create(myAvatar, {
  id: "my-avatar-id", 
  wearables: [],
  emotes: []
})

// NPC에 부착할 객체 생성
const attachedEntity = engine.addEntity()
Transform.create(attachedEntity, {
    position: Vector3.create(4, 2, 4),
    scale: Vector3.create(0.15,0.15,0.15)
})
MeshRenderer.setBox(attachedEntity)
Material.setBasicMaterial(attachedEntity, { diffuseColor: Color4.Blue() })
AvatarAttach.create(attachedEntity, {
    avatarId: "my-avatar-id",
    anchorPointId: AvatarAnchorPointType.AAPT_LEFT_HAND
})
```

자세한 내용은 `AvatarAttach` 컴포넌트를 [여기에서](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/entity-positioning.md#attach-an-entity-to-an-avatar).

## 플레이어의 아바타 바꾸기

플레이어 아바타가 착용한 웨어러블 아이템은 바꿀 수 없지만, 대신 완전히 사용자 지정할 수 있는 NPC 아바타로 플레이어 아바타를 대체할 수 있습니다.

이렇게 하려면 [Avatar Modifier Area](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/modifier-areas.md#hide-avatars) 를 사용해 플레이어 자신의 아바타를 숨기세요. 이 영역은 `AMT_HIDE_AVATARS` 수정자를 사용하고, 대신 플레이어의 위치에 `AvatarShape` 엔터티를 표시합니다.

{% hint style="warning" %}
**📔 참고**: 플레이어가 해당 아바타를 완전히 제어하도록 하려면 버튼 이벤트를 감지해 플레이어가 버튼을 눌렀을 때 NPC 아바타에서 해당 애니메이션을 실행해야 합니다. 자세한 내용은 [버튼 이벤트](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/system-based-events.md) 를 참조하세요.

이 방법을 사용할 경우 조작이 매끄럽지 않을 수 있으므로, 매우 특별한 경우에만 사용하는 것이 좋습니다.
{% 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/npc-avatars.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.
