> 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

Você pode fazer com que o jogador execute uma animação como parte do código da Scene. Isso pode ajudar a proporcionar mais imersão e também pode ajudar a comunicar aos outros jogadores o que cada um está fazendo. As animações do avatar são vistas tanto pelo jogador (em visão de 3ª pessoa) quanto por quaisquer outros jogadores ao redor.

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

{% hint style="warning" %}
**📔 Observação**: Os jogadores só podem receber animações se já estiverem dentro dos limites da Scene, e não se estiverem em uma Scene vizinha. Smart wearables podem reproduzir animações em qualquer lugar.

Enquanto um jogador estiver executando uma animação, ele não é afetado por colisões, e seus movimentos não são limitados pela física da Scene. Também observe que, se uma animação deslocar o jogador de sua posição original (por exemplo, se a animação envolver um salto), o componente Transform do jogador não será afetado por esse deslocamento.
{% endhint %}

### Use o Scene Editor

A maneira mais fácil de fazer um jogador executar uma animação é usar o Scene Editor. Use a opção sem código **Reproduzir Emote** para reproduzir uma animação padrão, ou a **Reproduzir Emote personalizado** opção para reproduzir uma animação a partir de um arquivo. Veja [Torne qualquer item num smart item](/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md).

### Animações padrão

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

* `predefinedEmote`: Um nome em string para um emote existente.
* `mask`: (opcional) Reproduz a animação apenas em parte do corpo do avatar, usando um valor do `AvatarMask` enum. Por exemplo, `AvatarMask.AM_UPPER_BODY` anima apenas a parte superior do corpo do avatar. Veja [Animar apenas 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: 'Dançar' },
	},
	() => {
		triggerEmote({ predefinedEmote: 'robot' })
	}
)
```

Os seguintes emotes exibem feedback sobre as ações do jogador em sua Scene; todos eles são valores válidos para o `predefinedEmote` campo:

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

Esses emotes estão disponíveis para todos os jogadores em sua roda de emotes padrão e também podem ser usados em qualquer Scene.

* `wave`
* `fistpump`
* `robot`
* `raiseHand`
* `clap`
* `money`
* `kiss`
* `tik`
* `hammer`
* `tektonik`
* `dontsee`
* `handsair`
* `shrug`
* `disco`
* `dab`
* `headexplode`

{% hint style="info" %}
**💡 Dica**: Se um jogador andar ou pular enquanto a animação estiver sendo reproduzida, ele a interromperá. Se você não quiser que isso seja possível, você pode congelar o avatar com [Input Modifiers](/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/locomotion.md#freeze-the-player) durante a animação do avatar.
{% endhint %}

### Animações personalizadas

Use o `triggerSceneEmote()` para fazer com que o jogador execute uma animação personalizada, armazenada como um arquivo .glb como parte do asset da Scene.

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

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

* `src`: Uma string com o path para o arquivo do emote.
* `loop`: Se true, a animação será reproduzida em loop continuamente até que o jogador se mova ou a animação seja interrompida. False por padrão.
* `mask`: (opcional) Reproduz a animação apenas em parte do corpo do avatar, usando um valor do `AvatarMask` enum. Por exemplo, `AvatarMask.AM_UPPER_BODY` anima apenas a parte superior do corpo do avatar. Veja [Animar apenas a parte superior do corpo](#animate-only-the-upper-body).

```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: 'Fazer bola de neve' },
	},
	() => {
		triggerSceneEmote({ src: 'animations/Snowball_Throw_emote.glb', loop: false, mask: AvatarMask.AM_UPPER_BODY })
	}
)
```

{% hint style="info" %}
**💡 Dica**: Se um jogador andar ou pular enquanto a animação estiver sendo reproduzida, ele a interromperá. Se você não quiser que isso seja possível, você pode congelar o avatar com [Input Modifiers](/creator/content-creator-pt/scenes-sdk7/interatividade/avatares/locomotion.md#freeze-the-player) durante a animação do avatar.
{% endhint %}

### Animar apenas a parte superior do corpo

Ambos `triggerEmote()` e `triggerSceneEmote()` aceita uma propriedade `mask` opcional, que limita a animação apenas a parte do corpo do avatar.

Normalmente, uma animação é interrompida assim que o jogador anda ou pula, porque as animações padrão de locomoção assumem o corpo inteiro. Quando você define `mask` como `AvatarMask.AM_UPPER_BODY`, a animação controla apenas o avatar da cintura para cima, e as pernas permanecem controladas pelas animações padrão de locomoção. Isso significa que o jogador pode continuar andando ou correndo pela Scene enquanto a parte superior do corpo reproduz sua animação. Use isso para ações que não devem interromper o movimento, como carregar 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: 'Comemorar' },
	},
	() => {
		triggerSceneEmote({
			src: 'animations/Cheer_emote.glb',
			loop: true,
			mask: AvatarMask.AM_UPPER_BODY,
		})
	}
)
```

Neste exemplo, o jogador clica em um botão e começa a comemorar com os braços no ar, em uma animação em loop. Como apenas a parte superior do corpo é animada, ele pode continuar correndo pela Scene enquanto comemora, por exemplo, para acompanhar a ação em uma corrida ou em uma partida de futebol.

Alguns pontos a ter em mente:

* `AvatarMask.AM_UPPER_BODY` é atualmente o único valor no `AvatarMask` enum. Para reproduzir uma animação no corpo inteiro, simplesmente não defina a `mask` propriedade.
* O `loop` propriedade se comporta da mesma forma que nas animações de corpo inteiro: com `loop: false` a animação mascarada é reproduzida uma vez e depois a parte superior do corpo retorna à locomoção normal, com `loop: true` ela se repetindo até ser interrompida.
* Para interromper uma animação mascarada em loop pelo código, chame `stopEmote({})`, também importado de `~system/RestrictedActions`.

### Detetar quando um emote termina

Cada evento do ciclo de vida do emote é reportado por meio do `AvatarEmoteCommand` componente na entity do jogador. Cada nova entrada carrega um `state` campo, com um valor do `EmoteState` enum:

* `EmoteState.ES_STARTED`: O emote começou a ser reproduzido. Esse também é o valor reportado quando o `state` campo está ausente (entradas escritas por clients mais antigos).
* `EmoteState.ES_FINISHED`: Um emote sem loop foi reproduzido até seu fim natural.
* `EmoteState.ES_INTERRUPTED`: O emote foi interrompido antes do fim: o jogador se moveu ou pulou, foi teleportado, outro emote foi iniciado, o emote foi explicitamente interrompido ou o jogador saiu da Scene.

Isso funciona para emotes acionados pela Scene (`triggerEmote()` e `triggerSceneEmote()`) assim como para emotes que o próprio jogador reproduz pela roda de emotes, e também para emotes reproduzidos por outros jogadores na Scene.

Use o `onChange` função no `AvatarEmoteCommand` componente 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 iniciado: ', emote.emoteUrn)
				break
			case EmoteState.ES_FINISHED:
				console.log('emote concluído naturalmente: ', emote.emoteUrn)
				break
			case EmoteState.ES_INTERRUPTED:
				console.log('emote foi interrompido: ', emote.emoteUrn)
				break
		}
	})
}
```

{% hint style="warning" %}
**📔 Observação**: Este recurso é suportado apenas no cliente Desktop. Emotes reproduzidos com um `mask` (emotes de parte do corpo) no jogador local atualmente não reportam eventos do ciclo de vida.
{% endhint %}

{% hint style="info" %}
**💡 Dica**: Para reproduzir animações em avatares que não são jogadores, veja [Avatares NPC](/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.