> 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/npc-avatars.md). # NPC 아바타 NPC 아바타 표시 및 제어 아바타를 씬의 엔터티로 표시합니다. {% hint style="info" %} **💡 팁**: 다음을 사용해 보세요 [NPC Toolkit 라이브러리](https://github.com/decentraland-scenes/dcl-npc-toolkit) NPC를 다루는 것을 더 쉽게 경험할 수 있습니다. 특히 대화 트리를 통해 상호작용해야 하는 경우에 유용합니다. {% endhint %} ## 아바타 만들기 다음 스니펫은 랜덤한 착용 아이템과 바디 형태, 그리고 "NPC"라는 이름을 가진 아바타를 만듭니다. ```ts const myAvatar = engine.addEntity() AvatarShape.create(myAvatar) Transform.create(myAvatar, { position: Vector3.create(4, 0.25, 5), }) ``` 아바타를 생성하기 위해 데이터를 전달할 때 `AvatarShape`에 대해 다음 필드가 필요합니다: * `id`: (필수) 아바타의 내부 식별자 다음의 선택적 필드도 사용할 수 있습니다: * `name`: 아바타 머리 위에 표시할 이름. 기본값: "NPC". * `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*를 사용하면, 플레이어가 월드 내에서 음성 채팅을 사용할 때처럼 이름 옆에 녹색 막대 세트가 표시됩니다. *

💡 팁: 참고 색상 유형 색상 설정 방법에 대한 자세한 내용은

{% hint style="warning" %} **📔 참고**: `AvatarShape`컴포넌트는 다음을 통해 가져와야 합니다: > `import { AvatarShape } from "@dcl/sdk/ecs"` 참고 [가져오기](/creator/content-creator-ko/sdk7/getting-started/coding-scenes.md#imports) 를 사용하면 이를 쉽게 처리할 수 있습니다. {% endhint %} {% hint style="warning" %} **📔 참고**: URN 필드는 다음과 같은 형식을 따라야 합니다. [NFTShapes](/creator/content-creator-ko/sdk7/media/display-a-certified-nft.md): `urn:decentraland::::` {% endhint %} ## 애니메이션 아바타는 정지해 있을 때 기본 대기 애니메이션을 재생합니다. 아바타에서 애니메이션을 재생하려면 `expressionTriggerId` 문자열을 재생하려는 애니메이션의 이름으로 설정하세요. ```ts const myAvatar = engine.addEntity() AvatarShape.create(myAvatar, { id: '', emotes: [], wearables: [], expressionTriggerId: 'robot', }) Transform.create(myAvatar, { position: Vector3.create(4, 0.25, 5), }) ``` 그 `expressionTriggerId` 필드는 모든 [기본 애니메이션](/creator/content-creator-ko/sdk7/interactivity/player-avatar.md#default-animations)뿐만 아니라 사용자 지정 애니메이션도 [씬 파일에서](/creator/content-creator-ko/sdk7/interactivity/player-avatar.md#custom-animations)를 지원하며, 마켓플레이스에 게시된 이모트의 URN도 지원합니다. ### 루프 애니메이션 아바타의 애니메이션은 `AvatarShape` 한 번만 재생됩니다. 아바타가 애니메이션을 계속 반복하도록 하려면, 몇 초마다 다시 애니메이션을 재생하도록 지시하는 시스템을 만들어야 합니다. 사용하세요 `expressionTriggerTimestamp` 를 사용해 같은 이모트를 다시 재생합니다. 이 필드의 값은 [람포트 타임스탬프](https://en.wikipedia.org/wiki/Lamport_timestamp)이며, 시간 값이 아니라 이모트가 반복될 때마다 1씩 증가하는 인덱스입니다. 따라서 이모트를 처음 재생할 때는 `expressionTriggerTimestamp` 를 *0*로 설정합니다. 이모트를 다시 재생하려면 이 값을 1로 업데이트해야 합니다. 그러면 엔진은 이것이 이미 처리한 명령이 아니라 새 명령임을 알 수 있습니다. 다음 스니펫은 같은 이모트를 2초마다 실행하는 시스템을 만듭니다: ```ts const myAvatar = engine.addEntity() AvatarShape.create(myAvatar, { id: '', emotes: [], wearables: [], expressionTriggerId: 'clap', expressionTriggerTimestamp: 0 }) Transform.create(myAvatar, { position: Vector3.create(4, 0.25, 5), }) let clapTimer = 0 let emoteDuration = 2 // 2초 // 시스템 engine.addSystem((dt: number) => { clapTimer += dt if (clapTimer >= emoteDuration) { // 박수 이모트 트리거 AvatarShape.getMutable(myAvatar).expressionTriggerTimestamp += 1 clapTimer = 0 // 타이머 초기화 } }) ``` {% hint style="info" %} **💡 팁**: 이모트의 지속 시간을 알아야 하며, 그 시간을 시스템의 지속 시간으로 설정해야 합니다. 아바타를 같은 자세로 고정하는 이모트를 만든다면, 이모트의 지속 시간을 시스템보다 더 길게 설정하는 것이 좋습니다. 이렇게 하면 애니메이션을 종료하고 재설정할 때 아티팩트가 생기지 않도록 할 수 있습니다. {% endhint %} ## 플레이어의 착용 아이템 복사 다음 스니펫은 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: '', emotes: [], wearables: [ 'urn:decentraland:matic:collections-v2:0x90e5cb2d673699be8f28d339c818a0b60144c494:0' ], showOnlyWearables: true, }) Transform.create(myAvatar, { position: Vector3.create(4, 0.25, 5), }) ``` 예를 들어 상점에서 착용 아이템을 보여줄 때 유용합니다. {% hint style="info" %} **💡 팁**착용 아이템이 다소 작다면 `크기` 의 `Transform` 값을 더 크게 설정해 보세요. {% endhint %} ## NPC에 엔터티 연결 다음을 사용할 수 있습니다. `AvatarAttach` 기능을 사용해 엔터티를 NPC 아바타의 뼈대 중 하나에 고정할 수 있습니다. 예를 들어 NPC가 손에 물건을 들고 있게 할 수 있습니다. 엔터티는 애니메이션이 재생될 때 아바타와 함께 움직입니다. 이 기능을 사용하려면 `id` 의 `AvatarShape` 를 사용해 이 아바타에 임의의 id를 할당한 다음, `AvatarAttach`에서 그 id를 참조하세요. id는 원하는 어떤 문자열이든 될 수 있습니다. ```ts // NPC 생성, ID 포함 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` 컴포넌트 [여기](/creator/content-creator-ko/sdk7/3d/entity-positioning.md#attach-an-entity-to-an-avatar). --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/npc-avatars.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.