> 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/avatar-animations.md).

# Animações de Avatar

Faça o avatar do jogador reproduzir animações padrão ou personalizadas, e detecte quando um emote termina

Pode fazer o jogador executar uma animação como parte do código da cena. Isso pode ajudar a aumentar a imersão e também comunicar aos outros jogadores o que cada um está fazendo. As animações do Avatar são vistas tanto pelo próprio jogador (na visão em terceira pessoa) quanto pelos jogadores ao redor.

As animações controladas pelo jogador que envolvem o corpo inteiro são substituídas pelas animações de locomoção padrão, como andar e pular. Portanto, as animações de corpo inteiro reproduzidas pela cena só são executadas enquanto o jogador está parado. Se o jogador andar ou pular, qualquer animação de corpo inteiro será interrompida. As animações da parte superior do corpo não são interrompidas pelo movimento.

{% hint style="warning" %}
**📔 Nota**: os jogadores só podem ser animados se já estiverem dentro dos limites da cena, e não se estiverem em uma cena vizinha. Wearables inteligentes podem reproduzir animações em qualquer lugar.

Enquanto um jogador executa uma animação, ele não é afetado por colisões, e seus movimentos não são limitados pela física da cena. Observe também que, se uma animação deslocar o jogador de sua posição original (por exemplo, se a animação incluir um salto), esse deslocamento não afetará o componente Transform do jogador.
{% endhint %}

### Usar o Scene Editor

A maneira mais fácil de fazer um jogador executar uma animação é usar o Scene Editor. Use a ação sem código **Play Emote** para reproduzir uma animação padrão, ou a ação **Play Custom Emote** para reproduzir uma animação de um arquivo. Consulte [Tornar qualquer item inteligente](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md).

### Animações padrão

Use a função `triggerEmote()` para executar uma das animações padrão que os jogadores podem reproduzir em qualquer lugar de Decentraland. Essa função recebe como argumento um objeto com as seguintes propriedades:

* `predefinedEmote`: nome em string de um emote existente.
* `mask`: (opcional) reproduz a animação somente em uma parte do corpo do Avatar, usando um valor do enum `AvatarMask` . Por exemplo, `AvatarMask.AM_UPPER_BODY` anima somente a parte superior do corpo do Avatar. Consulte [Animar somente a parte superior do corpo](#animate-only-the-upper-body).

```ts
import { triggerEmote } from '~system/RestrictedActions'

const emoter = engine.addEntity()
Transform.create(emoter, { position: Vector3.create(8, 0, 8) })
MeshRenderer.setBox(emoter)
MeshCollider.setBox(emoter)
pointerEventsSystem.onPointerDown(
	{
		entity: emoter,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Dance' },
	},
	() => {
		triggerEmote({ predefinedEmote: 'robot' })
	}
)
```

Os emotes a seguir dão feedback sobre as ações dos jogadores na sua cena. Todos eles são valores válidos para o campo `predefinedEmote` :

* `buttonDown`
* `buttonFront`
* `getHit`
* `knockOut`
* `lever`
* `openChest`
* `openDoor`
* `punch`
* `push`
* `swingWeaponOneHand`
* `swingWeaponTwoHands`
* `throw`
* `sittingChair1`
* `sittingChair2`
* `sittingGround1`
* `sittingGround2`

Os quatro `sitting` emotes repetem-se em ciclo: o avatar mantém a pose até o jogador se mover ou a sua cena chamar `stopEmote({})`. `stopEmote` é resolvida com `{ success: boolean }`, que é `false` quando o Explorer recusa a chamada, por exemplo, porque o jogador já não está na sua cena. Todas as outras são reproduzidas uma vez e o avatar volta ao estado inativo.

Estes emotes estão disponíveis para todos os jogadores na roda de emotes predefinida e também podem ser usados em qualquer cena.

* `wave`
* `fistpump`
* `robot`
* `raiseHand`
* `clap`
* `money`
* `kiss`
* `tik`
* `hammer`
* `tektonik`
* `dontsee`
* `handsair`
* `shrug`
* `disco`
* `dab`
* `headexplode`
* `crafting`
* `handsintheair`
* `Victory`
* `Waving`
* `fistpump_short`

`cry` e `dance` também são valores válidos para `predefinedEmote`, embora o pacote **Animações do avatar** do Creator Hub não os inclua.

{% hint style="warning" %}
**📔 Nota**: Use estes nomes exatamente como estão listados. Um nome incorreto falha silenciosamente na sua cena: nada é reproduzido e nada aparece na consola da cena. Tenha atenção a `handsintheair` sem separadores, e a `fistpump_short` com o sufixo.
{% endhint %}

{% hint style="info" %}
**💡 Sugestão**: Se um jogador andar ou saltar enquanto a animação está a ser reproduzida, irá interrompê-la. Se não quiser que isso seja possível, pode imobilizar o avatar com [Modificadores de entrada](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/locomotion.md#freeze-the-player) durante a animação do avatar.
{% endhint %}

### Animações personalizadas

Utilize `triggerSceneEmote()` para fazer o jogador executar uma animação personalizada, armazenada num ficheiro .glb como parte dos recursos da cena.

{% hint style="info" %}
**💡 Dica**: Não precisa de criar estas animações. O pacote **Avatar Animations** no Scene Editor inclui 45 animações prontas a usar, como poses sentadas, pesca, carregar uma caixa e dançar. Arraste uma para a vista 3D e o editor copia o ficheiro para a sua cena. Em seguida, passe o caminho desse ficheiro a `triggerSceneEmote()`. Os ficheiros ficam em `assets/asset-packs/<animation-folder>/`, por exemplo `assets/asset-packs/whack/Whack_Avatar_emote.glb`. Consulte o caminho exato em **Local Assets**. Consulte [Adicionar itens](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md#avatar-animations).
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: O nome do ficheiro **tem de** terminar em `_emote.glb` para funcionar como uma animação de avatar.
{% endhint %}

Esta função recebe um objeto com as seguintes propriedades:

* `src`: O caminho completo para o ficheiro de emote, relativo à pasta raiz do projeto. Para um ficheiro localizado em `assets/animations/sit_emote.glb` é necessário usar `'assets/animations/sit_emote.glb'`.
* `loop`: Se for true, a animação é repetida continuamente até o jogador se mover ou a animação ser parada. O valor predefinido é false.
* `mask`: (opcional) reproduz a animação somente em uma parte do corpo do Avatar, usando um valor do enum `AvatarMask` . Por exemplo, `AvatarMask.AM_UPPER_BODY` anima somente a parte superior do corpo do Avatar. Consulte [Animar somente a parte superior do corpo](#animate-only-the-upper-body).

{% hint style="warning" %}
**📔 Nota**: `src` tem de ser o caminho completo para o ficheiro. Não é feita uma pesquisa pelo nome do ficheiro e o sufixo `_emote` não é acrescentado automaticamente. Se o caminho estiver incorreto, `triggerSceneEmote()` retorna `{ success: false }` e a animação não é reproduzida. Copie o caminho da pasta do projeto e inclua todas as pastas.
{% endhint %}

```ts
import { triggerSceneEmote } from '~system/RestrictedActions'
import { AvatarMask } from '@dcl/sdk/ecs'

const emoter = engine.addEntity()
Transform.create(emoter, { position: Vector3.create(8, 0, 8) })
MeshRenderer.setBox(emoter)
MeshCollider.setBox(emoter)
pointerEventsSystem.onPointerDown(
	{
		entity: emoter,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Make snowball' },
	},
	() => {
		triggerSceneEmote({ src: 'assets/animations/Snowball_Throw_emote.glb', loop: false, mask: AvatarMask.AM_UPPER_BODY })
	}
)
```

{% hint style="info" %}
**💡 Sugestão**: Se um jogador andar ou saltar enquanto a animação está a ser reproduzida, irá interrompê-la. Se não quiser que isso seja possível, pode imobilizar o avatar com [Modificadores de entrada](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/locomotion.md#freeze-the-player) durante a animação do avatar.
{% endhint %}

#### Adereços, partículas e som

Um ficheiro de emote reproduzido com `triggerSceneEmote()` pode incluir adereços, como uma raquete de ténis ou um jato de chamas, animados em conjunto com o avatar. Crie-o da mesma forma que um emote Emotes 2.0, seguindo as regras de nomenclatura em [Adereços e sons](https://docs.decentraland.org/creator/content-creator-pt/wearables-e-emotes/emotes/props-and-sounds.md):

* O ficheiro contém dois clips de animação: um cujo nome inclui `_Avatar` para o avatar, e outro cujo nome inclui `_Prop` para a armature do adereço.
* Ambos os clips têm a mesma duração.
* Os efeitos de partículas funcionam se os converter em ossos animados. Consulte [Partículas em Emotes](https://docs.decentraland.org/creator/content-creator-pt/wearables-e-emotes/emotes/particles-in-emotes.md).

Os outros jogadores nas proximidades veem os adereços, tal como veem a animação do avatar.

{% hint style="warning" %}
**📔 Nota**: `triggerSceneEmote()` não reproduz som. O áudio só é reproduzido nos Emotes carregados como Emotes autónomos no Builder. Para associar um som a um Emote de cena, reproduza-o com um [AudioSource](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/sounds.md) ao mesmo tempo.
{% endhint %}

### Animar apenas a parte superior do corpo

Tanto `triggerEmote()` como `triggerSceneEmote()` aceitam uma propriedade opcional `mask` que limita a animação a apenas uma parte do corpo do avatar.

Normalmente, uma animação para assim que o jogador começa a andar ou a saltar, porque as animações de locomoção predefinidas assumem o controlo de todo o corpo. Quando define `mask` como `AvatarMask.AM_UPPER_BODY`, a animação controla apenas o avatar da cintura para cima, e as pernas continuam a ser controladas pelas animações de locomoção predefinidas. Isto significa que o jogador pode continuar a andar ou a correr pela cena enquanto a parte superior do corpo executa a sua animação. Use esta opção para ações que não devem interromper o movimento, como transportar uma caixa, segurar uma tocha ou fazer malabarismo.

```ts
import { triggerSceneEmote } from '~system/RestrictedActions'
import {
	engine,
	AvatarMask,
	InputAction,
	MeshCollider,
	MeshRenderer,
	pointerEventsSystem,
	Transform,
} from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const cheerButton = engine.addEntity()
Transform.create(cheerButton, { position: Vector3.create(8, 0, 8) })
MeshRenderer.setBox(cheerButton)
MeshCollider.setBox(cheerButton)
pointerEventsSystem.onPointerDown(
	{
		entity: cheerButton,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Cheer' },
	},
	() => {
		triggerSceneEmote({
			src: 'assets/animations/Cheer_emote.glb',
			loop: true,
			mask: AvatarMask.AM_UPPER_BODY,
		})
	}
)
```

Neste exemplo, o jogador clica num botão e começa a festejar com os braços no ar, numa animação em loop. Como apenas a parte superior do corpo é animada, o jogador pode continuar a correr pela cena enquanto festeja, por exemplo, para acompanhar a ação numa corrida ou num jogo de futebol.

Tenha em conta o seguinte:

* `AvatarMask.AM_UPPER_BODY` é atualmente o único valor da enumeração `AvatarMask` . Para reproduzir uma animação no corpo inteiro, basta não definir a propriedade `mask` .
* A propriedade `loop` funciona da mesma forma que nas animações do corpo inteiro: com `loop: false` a animação mascarada é reproduzida uma vez e, em seguida, a parte superior do corpo volta à locomoção normal, com `loop: true` ela é repetida até ser interrompida.
* Para interromper por código uma animação mascarada em loop, chame `stopEmote({})`, também importado de `~system/RestrictedActions`. A chamada resolve com `{ success: boolean }`.

### Detetar quando uma emote termina

Cada evento do ciclo de vida de uma emote é comunicado através do componente `AvatarEmoteCommand` na entidade do jogador. Cada nova entrada contém um campo `state` com um valor do enum `EmoteState` :

* `EmoteState.ES_STARTED`: A emote começou a ser reproduzida. Este também é o valor comunicado quando o campo `state` está ausente.
* `EmoteState.ES_FINISHED`: Uma emote sem loop chegou ao fim naturalmente.
* `EmoteState.ES_INTERRUPTED`: A emote foi interrompida antes do fim: o jogador moveu-se ou saltou, teletransportou-se, começou outra emote, a emote foi explicitamente interrompida ou o jogador saiu da cena.

Isto funciona tanto para as emotes acionadas pela cena (`triggerEmote()` e `triggerSceneEmote()`) como para as emotes que o jogador reproduz através da roda de emotes, bem como para as emotes reproduzidas por outros jogadores na cena.

Use a função `onChange` no componente `AvatarEmoteCommand` para reagir a cada nova entrada:

```ts
import { AvatarEmoteCommand, EmoteState } from '@dcl/sdk/ecs'

export function main() {
	AvatarEmoteCommand.onChange(engine.PlayerEntity, (emote) => {
		if (!emote) return

		switch (emote.state ?? EmoteState.ES_STARTED) {
			case EmoteState.ES_STARTED:
				console.log('emote started: ', emote.emoteUrn)
				break
			case EmoteState.ES_FINISHED:
				console.log('emote finished naturally: ', emote.emoteUrn)
				break
			case EmoteState.ES_INTERRUPTED:
				console.log('emote was interrupted: ', emote.emoteUrn)
				break
		}
	})
}
```

{% hint style="warning" %}
**📔 Nota**: Esta funcionalidade só é suportada no cliente para computador. As emotes reproduzidas com uma `mask` (emotes de corpo parcial) no jogador local não comunicam atualmente eventos do ciclo de vida.
{% endhint %}

{% hint style="info" %}
**💡 Dica**: Para reproduzir animações em avatares que não são jogadores, consulte  [Avatares NPC](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/npc-avatars.md#animations).
{% 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/avatar-animations.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.
