For the complete documentation index, see llms.txt. This page is also available as Markdown.

Avatares NPC

Exiba e controle o avatar do NPC

Apresentar um avatar como uma entidade numa cena.

💡 Dica: Experimente a biblioteca NPC Toolkit para facilitar o trabalho com NPCs, especialmente se precisar de interagir através de uma árvore de conversa.

Criar um avatar

O seguinte excerto cria um avatar com wearables e uma forma corporal aleatórios, e com o nome "NPC".

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 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.

  • 💡 Dica: Consulte tipos de cor para obter mais informações sobre como definir cores.

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.

Para controlar o movimento manualmente, use um Tween. 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.

O campo expressionTriggerId é compatível com todas as animações predefinidas, assim como com animações personalizadas de um ficheiro de cenae 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(), um caminho incorreto não reproduz nada.

Mover um NPC enquanto ele executa um emote

Alterar o Transform.position, ou executar um Tween 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, 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:

💡 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.

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:

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.

💡 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.

Consulte Etiquetas de nome do Avatar 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.

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.

Isso é útil para exibir Wearables, por exemplo, em uma loja.

💡 Dica: Se um Wearable for muito pequeno, tente definir o scale do Transform com um valor maior.

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.

Saiba mais sobre o AvatarAttach component aqui.

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 que utilize o modificador AMT_HIDE_AVATARS e apresente uma entity com AvatarShape na posição do jogador.

Atualizado