> 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-pt/scenes-sdk7/interatividade/avatares/npc-avatars.md). # Avatares NPC Exiba e controle o avatar do NPC Exiba um avatar como uma entidade em uma Scene. {% hint style="info" %} **💡 Dica**: Experimente a [biblioteca NPC Toolkit](https://github.com/decentraland-scenes/dcl-npc-toolkit) para uma experiência mais fácil ao lidar com NPCs, especialmente se você precisar interagir por meio de uma árvore de conversa. {% endhint %} ## Criar um avatar O trecho a seguir cria um avatar com Wearables aleatórios e body shape, e o nome "NPC". ```ts const myAvatar = engine.addEntity() AvatarShape.create(myAvatar) Transform.create(myAvatar, { position: Vector3.create(4, 0.25, 5), }) ``` Ao passar dados para gerar um `AvatarShape`, os seguintes campos são obrigatórios: * `id`: (obrigatório) Identificador interno para o Avatar Os seguintes campos opcionais também estão disponíveis: * `name`: Nome a ser exibido acima da cabeça do Avatar. Padrão: "NPC". Defina-o como uma string vazia para não mostrar nome algum, o que é útil quando você quer apenas um [Avatar Nametag](/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-nametags.md) placa acima do NPC. * `bodyShape`: String para definir qual body shape usar. As opções válidas são 'urn:decentraland:off-chain:base-avatars:BaseMale' e 'urn:decentraland:off-chain:base-avatars:BaseFemale'. * `wearables`: Array com a lista de URNs dos Wearables que o avatar está usando no momento. Se os wearables entrarem em conflito (como quando dois deles são chapéus), o último da lista substitui o outro. * `emotes`: Array com a lista de URNs de NFT emotes que o avatar é capaz de reproduzir * `eyeColor`: *Color3* para a cor dos olhos (qualquer cor é válida) * `skinColor`: *Color3* para a cor da pele (qualquer cor é válida) * `hairColor`: *Color3* para a cor do cabelo (qualquer cor é válida) * `talking`: Se *true*, exibe um conjunto verde de barras ao lado do nome, como quando os jogadores usam chat de voz in-world. *

💡 Dica: Veja tipos de cor para mais detalhes sobre como definir cores.

{% hint style="warning" %} **📔 Observação**: A `AvatarShape`component deve ser importado via > `import { AvatarShape } from "@dcl/sdk/ecs"` Veja [Imports](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com isso facilmente. {% endhint %} {% hint style="warning" %} **📔 Observação**: Os campos URN devem seguir o mesmo formato usado para [NFTShapes](/creator/content-creator-pt/scenes-sdk7/media/display-a-certified-nft.md): `urn:decentraland::::` {% endhint %} ## Animações Avatars reproduzem animações padrão de idle quando estão parados. Para reproduzir animações no avatar, defina o `expressionTriggerId` string com o nome da animação que você quer reproduzir. ```ts const myAvatar = engine.addEntity() AvatarShape.create(myAvatar, { id: '', emotes: [], wearables: [], expressionTriggerId: 'robot', }) Transform.create(myAvatar, { position: Vector3.create(4, 0.25, 5), }) ``` O `expressionTriggerId` campo suporta todas as [animações padrão](/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-animations.md#default-animations), bem como animações personalizadas [de um arquivo de scene](/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-animations.md#custom-animations), e até mesmo URNs de emotes que são publicados no Marketplace. ### Animações em loop As animações em um `AvatarShape` são reproduzidas uma única vez; se você quiser que o avatar continue em loop com uma animação, você deve criar um system que o instrua a reproduzir a animação novamente a cada dois segundos. Use o `expressionTriggerTimestamp` para reproduzir o mesmo emote. O valor deste campo é um [timestamp de Lamport](https://en.wikipedia.org/wiki/Lamport_timestamp), o que significa que não é um valor de tempo, mas sim um índice que é incrementado em 1 a cada repetição do emote. Então, na primeira vez que você reproduz um emote, você define `expressionTriggerTimestamp` como *0*. Para reproduzir o emote novamente, você deve atualizar esse valor para 1. É assim que o engine sabe que esta é uma nova instrução, e não uma instrução sobre a qual já agiu. O trecho a seguir cria um system que executa o mesmo emote a cada 2 segundos: ```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 segundos // system engine.addSystem((dt: number) => { clapTimer += dt if (clapTimer >= emoteDuration) { // Aciona o emote de clap AvatarShape.getMutable(myAvatar).expressionTriggerTimestamp += 1 clapTimer = 0 // Reinicia o timer } }) ``` {% hint style="info" %} **💡 Dica**: Você deve saber a duração do emote e fazer disso a duração do system. Se você criar um emote que mantém o avatar imóvel na mesma pose, é recomendável fazer a duração do emote maior do que a do system. Dessa forma, você pode garantir que não haja artefatos ao finalizar e redefinir a animação. {% endhint %} ## Adicionar um rótulo acima do nome Use o `AvatarNametag` component para mostrar uma placa com texto personalizado acima do nome do NPC, por exemplo um cargo como "Shopkeeper" ou "Boss". Anexe-o à mesma entity que tem o `AvatarShape`: ```ts AvatarNametag.create(myAvatar, { label: 'Shopkeeper' }) ``` Se o `AvatarShape` tiver um `name`, apenas a placa é mostrada, sem uma caixa de nametag vazia abaixo dela. Isso é útil para rotular um NPC apenas com um título. {% hint style="info" %} **💡 Dica**: Para uma placa codificada por cor sem texto, defina `label` como uma string de espaços e escolha um `backgroundColor`. Os espaços são preservados, então mais espaços criam uma placa mais larga. ```ts AvatarNametag.create(myAvatar, { label: ' ', backgroundColor: Color3.Red(), }) ``` {% endhint %} Veja [Avatar Nametags](/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-nametags.md) para a lista completa de campos, incluindo cores. ## Copiar Wearables do jogador O trecho a seguir altera os Wearables e outras características de um avatar NPC para corresponder aos que o jogador está usando no momento. Isso poderia ser usado em uma Scene como um manequim, para exibir um Wearable ou emote específico combinado com o visual atual do jogador. ```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 } ``` ## Exibir apenas Wearables Use o `showOnlyWearables` campo para exibir apenas os Wearables listados de um avatar. O restante do corpo do avatar ficará invisível. ```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), }) ``` Isso é útil para exibir Wearables, por exemplo em uma loja. {% hint style="info" %} **💡 Dica**: Se um Wearable for muito pequeno, tente definir o `scale` do `Transform` para um valor maior. {% endhint %} ## Anexar uma entity a um NPC Você pode usar o `AvatarAttach` recurso para fixar uma entity a um dos bones de um avatar NPC, por exemplo para que o NPC esteja segurando um objeto na mão. A entity se moverá junto com o avatar quando ele se animar. Para usar este recurso, use o `id` propriedade no `AvatarShape` para atribuir um id arbitrário a este avatar e, em seguida, referenciar esse id no `AvatarAttach`. O id pode ser qualquer string que você quiser. ```ts // Crie NPC, com um ID const myAvatar = engine.addEntity() Transform.create(myAvatar, { position: Vector3.create(8, 0.25, 8), }) AvatarShape.create(myAvatar, { id: "my-avatar-id", wearables: [], emotes: [] }) // Crie um objeto para anexar ao 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 }) ``` Saiba mais sobre o `AvatarAttach` component [aqui](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md#attach-an-entity-to-an-avatar). ## Substituir o avatar do jogador Você não pode alterar quais Wearables o avatar do jogador está usando, mas pode, em vez disso, trocar o avatar do jogador por um avatar NPC que você pode personalizar completamente. Para fazer isso, oculte o próprio avatar do jogador com um [Avatar Modifier Area](/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/modifier-areas.md#hide-avatars) que use o `AMT_HIDE_AVATARS` modifier e exiba uma `AvatarShape` entity na posição do jogador em vez disso. {% hint style="warning" %} **📔 Observação**: Para permitir que o player tenha controle total sobre esse avatar, você deve escutar eventos de button para detectar quando eles pressionam um botão e, então, acionar a animação correspondente no avatar NPC. Veja [Eventos de botão](/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md) para mais detalhes. A fluidez do controle pode não ser perfeita ao fazer isso; talvez você queira usar isso apenas em casos muito específicos. {% 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-pt/scenes-sdk7/interatividade/avatares/npc-avatars.md?ask=&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.