> 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

Apresentar um avatar como uma entidade numa cena.

{% hint style="info" %}
**💡 Dica**: Experimente a [biblioteca NPC Toolkit](https://github.com/decentraland-scenes/dcl-npc-toolkit) para facilitar o trabalho com NPCs, especialmente se precisar de interagir através de uma árvore de conversa.
{% endhint %}

## Criar um avatar

O seguinte excerto cria um avatar com wearables e uma forma corporal aleatórios, e com 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`, são obrigatórios os seguintes campos:

* `id`: (obrigatório) Identificador interno do Avatar. Os últimos 4 caracteres do `id` são apresentados após o nome do NPC, em texto esbatido, como o sufixo da carteira de um jogador. Um `id` com menos de 4 caracteres apresenta `0000`. Atribua a cada NPC um `id` cujo final fique bem junto ao nome, por exemplo `'guide-0001'`.

Também estão disponíveis os seguintes campos opcionais:

* `name`: Nome a apresentar por cima da cabeça do Avatar. Predefinição: "NPC". Defina uma string vazia para não apresentar qualquer nome, o que é útil quando pretende apenas um [identificador de Avatar](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-nametags.md) por cima do NPC.
* `bodyShape`: String que define a forma corporal a utilizar. 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á a usar. Se houver conflitos entre wearables (por exemplo, se dois forem chapéus), o último da lista substitui o outro.
* `emotes`: Array com a lista de URNs dos emotes NFT que o avatar pode 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*, apresenta um conjunto de barras verdes junto ao nome, como acontece quando os jogadores usam o chat de voz no mundo.
* <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>💡 Dica</strong>: Consulte <a href="https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/color-types.md">tipos de cor</a> para obter mais informações sobre como definir cores.</p></div>

{% hint style="warning" %}
**📔 Nota**: O `AvatarShape`componente deve ser importado através de

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

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Os campos URN devem seguir o mesmo formato usado para [NFTShapes](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/media/display-a-certified-nft.md): `urn:decentraland:<CHAIN>:<CONTRACT_STANDARD>:<CONTRACT_ADDRESS>:<TOKEN_ID>`
{% endhint %}

## Mover um NPC

Para mover um NPC, altere a `position` do seu `Transform`. O avatar não salta para a nova posição: caminha até lá a partir de onde está, a cerca de 4 metros por segundo, e move-se mais depressa quando o destino está a 1,5 metros ou mais. Enquanto se move, vira-se para a direção em que está a caminhar. A `rotation` que definir no `Transform` só é aplicada quando chega ao destino.

```ts
// O NPC caminha da posição atual até à nova
Transform.getMutable(myAvatar).position = Vector3.create(10, 0.25, 5)
```

Para controlar o movimento manualmente, use um [Tween](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/move-entities.md). Um Tween na posição substitui esta caminhada automática, e um Tween na rotação impede o NPC de se virar para a direção em que caminha. Uma entidade só pode ter um Tween de cada vez, por isso não é possível animar a posição e a rotação da mesma entidade simultaneamente com Tweens.

## Animações

Os avatares reproduzem animações de repouso predefinidas quando estão parados.

Para reproduzir animações no avatar, defina a string `expressionTriggerId` com o nome da animação que pretende reproduzir.

```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),
})
```

O campo `expressionTriggerId` é compatível com todas as [animações predefinidas](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-animations.md#default-animations), assim como com animações personalizadas [de um ficheiro de cena](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-animations.md#custom-animations)e até com URNs de emotes publicados no Marketplace.

Para usar uma animação personalizada, indique o caminho para o ficheiro `_emote.glb` a partir da pasta raiz do projeto, por exemplo `'assets/animations/Cheer_emote.glb'`. Tal como acontece com [`triggerSceneEmote()`](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-animations.md#custom-animations), um caminho incorreto não reproduz nada.

{% hint style="warning" %}
**📔 Nota**: `AvatarShape` não tem um campo `mask` , por isso um `expressionTriggerId` a animação é sempre reproduzida no corpo inteiro. [Animar apenas a parte superior do corpo](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-animations.md#animate-only-the-upper-body) está disponível no avatar do próprio jogador, não em NPCs.
{% endhint %}

### Mover um NPC enquanto ele executa um emote

Alterar o `Transform.position`, ou executar um [Tween](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/move-entities.md) nele cancela o emote em execução. O avatar volta ao ciclo de caminhada, porque Decentraland determina qual animação de locomoção deve ser mesclada com base na distância que o avatar percorreu desde o último frame.

Para mover um NPC durante um emote, se o movimento acontecer em uma área pequena, você pode incorporar o movimento à própria animação, como movimento da raiz ou dos quadris no arquivo `_emote.glb` .

### Animações em loop

As animações em um `AvatarShape` são reproduzidas uma vez. Se quiser que o avatar continue repetindo uma animação em loop, crie um sistema que instrua o avatar a reproduzi-la novamente a cada dois segundos.

A única exceção são os emotes padrão em loop, `sittingChair1`, `sittingChair2`, `sittingGround1` e `sittingGround2`, que mantêm a pose em um `AvatarShape` sem necessidade de reproduzi-los novamente. Uma animação personalizada de um arquivo nunca é repetida em loop em um `AvatarShape`, mesmo que o próprio clipe esteja marcado como repetição em loop; portanto, para manter uma pose personalizada, é necessário usar o padrão de repetição abaixo.

Use `expressionTriggerTimestamp` para reproduzir o mesmo emote novamente. O valor desse campo é um [timestamp Lamport](https://en.wikipedia.org/wiki/Lamport_timestamp), ou seja, não é um valor de tempo, mas sim um índice que aumenta em 1 a cada repetição do emote.

Assim, na primeira vez que você reproduz um emote, define `expressionTriggerTimestamp` como *0*. Para reproduzir o emote novamente, atualize esse valor para 1. É assim que o Engine sabe que se trata de uma nova instrução, e não de uma instrução que já foi executada.

O trecho a seguir cria um sistema que reproduz o mesmo emote a cada 2 segundos:

```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" %}
**💡 Dica**: você precisa saber a duração do emote e definir a duração do sistema com base nela. Se criar um emote que mantém o avatar imóvel na mesma pose, é recomendável que a duração do emote seja maior que a do sistema. Assim, você garante que não haverá artefatos ao concluir e reiniciar a animação.
{% endhint %}

## Adicionar um rótulo acima do nome

Use o `AvatarNametag` componente para exibir uma placa com texto personalizado acima do nome do NPC, por exemplo, uma função como "Vendedor" ou "Chefe". Anexe-o à mesma entidade que tem o `AvatarShape`:

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

Se o `AvatarShape` tiver um `name`, apenas a placa será exibida, sem uma caixa de etiqueta de nome vazia embaixo. Isso é útil para identificar um NPC apenas pelo título.

{% hint style="info" %}
**💡 Dica**: Para exibir uma placa colorida sem texto, defina `label` como uma string de espaços e escolha um `backgroundColor`. Os espaços são preservados, portanto, quanto mais espaços houver, mais larga será a placa.

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

{% endhint %}

Consulte [Etiquetas de nome do Avatar](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/avatar-nametags.md) para ver a lista completa de campos, incluindo cores.

## Copiar Wearables do jogador

O trecho a seguir altera os Wearables e outras características do Avatar de um NPC para que correspondam aos que o jogador está usando no momento. Isso pode ser usado em uma cena como manequim, para exibir um Wearable específico ou um Emote 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: 'mannequin-0001',
	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` com um valor maior.
{% endhint %}

## Anexar uma entidade a um NPC

Você pode usar o `AvatarAttach` para fixar uma entity a um dos bones do avatar de um NPC, por exemplo, para que o NPC segure um objeto na mão. A entity mover-se-á juntamente com o avatar quando este for animado.

Para utilizar esta funcionalidade, use a propriedade `id` do `AvatarShape` para atribuir um ID arbitrário a este avatar e, em seguida, faça referência a esse ID no `AvatarAttach`. O ID pode ser qualquer string à sua escolha.

```ts
// Criar 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: []
})

// Criar objeto para associar 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](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md#attach-an-entity-to-an-avatar).

## Substituir o avatar do jogador

Não é possível alterar os wearables que o avatar do jogador usa, mas pode substituí-lo pelo avatar de um NPC, que pode personalizar por completo.

Para isso, oculte o avatar do jogador com uma [Avatar Modifier Area](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/modifier-areas.md#hide-avatars) que utilize o modificador `AMT_HIDE_AVATARS` e apresente uma entity com `AvatarShape` na posição do jogador.

{% hint style="warning" %}
**📔 Nota**: Para permitir que o jogador controle totalmente esse avatar, deve monitorizar os events dos buttons para detetar quando prime um button e, em seguida, acionar a animation correspondente no avatar do NPC. Consulte [Button Events](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/eventos-de-botao/system-based-events.md) para mais detalhes.

A fluidez do controlo poderá não ser perfeita com esta abordagem, pelo que poderá querer utilizá-la 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=<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.
