> 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-es/scenes-sdk7/interactividad/avatares/avatar-animations.md).

# Animaciones del Avatar

Haz que el Avatar del jugador reproduzca animaciones predeterminadas o personalizadas, y detecta cuándo termina un emote

Puedes hacer que el jugador realice una animación como parte del código de la escena. Esto puede ayudar a generar una mayor inmersión y también a comunicar a los demás jugadores lo que están haciendo. Las animaciones del avatar las ve tanto el jugador (en vista en tercera persona) como cualquier otro jugador que esté cerca.

Las animaciones de cuerpo completo controladas por el jugador se sustituyen por las animaciones de locomoción predeterminadas, como caminar y saltar. Por eso, las animaciones de cuerpo completo que reproduce la escena solo se ejecutan mientras el jugador está quieto. Si el jugador camina o salta, se interrumpe cualquier animación de cuerpo completo. El movimiento no interrumpe las animaciones de la parte superior del cuerpo.

{% hint style="warning" %}
**📔 Nota**: Los jugadores solo pueden animarse si ya están dentro de los límites de la escena, no si están en una escena vecina. Los Wearables inteligentes pueden reproducir animaciones en cualquier lugar.

Mientras un jugador realiza una animación, las colisiones no lo afectan y sus movimientos no están sujetos a la física de la escena. Ten en cuenta también que, si una animación desplaza al jugador de su posición original (por ejemplo, si la animación incluye un salto), este desplazamiento no afectará al componente Transform del jugador.
{% endhint %}

### Usar el Scene Editor

La forma más sencilla de hacer que un jugador realice una animación es usar el Scene Editor. Usa la acción sin código **Play Emote** para reproducir una animación predeterminada, o la acción **Play Custom Emote** para reproducir una animación desde un archivo. Consulta [Hacer que cualquier elemento sea inteligente](https://docs.decentraland.org/creator/content-creator-es/scene-editor/interactividad/make-any-item-smart.md).

### Animaciones predeterminadas

Usa la función `triggerEmote()` para ejecutar una de las animaciones predeterminadas que los jugadores pueden reproducir en cualquier lugar de Decentraland. Esta función recibe como argumento un objeto con las siguientes propiedades:

* `predefinedEmote`: El nombre, en forma de cadena, de un Emote existente.
* `mask`: (opcional) Reproduce la animación solo en una parte del cuerpo del avatar, usando un valor del enum `AvatarMask` . Por ejemplo, `AvatarMask.AM_UPPER_BODY` anima solo la parte superior del cuerpo del avatar. Consulta [Animar solo la parte superior del cuerpo](#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' })
	}
)
```

Los siguientes Emotes muestran información sobre las acciones de los jugadores en tu escena. Todos estos son valores válidos para el campo `predefinedEmote` :

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

Los cuatro `sitting` emotes se repiten en bucle: el Avatar mantiene la pose hasta que el jugador se mueve o tu Scene llama a `stopEmote({})`. `stopEmote` se resuelve con `{ success: boolean }`, que es `false` cuando el Explorer rechaza la llamada, por ejemplo, porque el jugador ya no está en tu Scene. Todos los demás se reproducen una vez y el Avatar vuelve al estado idle.

Estos emotes están disponibles para todos los jugadores en su rueda de emotes predeterminada y también se pueden usar en cualquier Scene.

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

`cry` y `dance` también son valores válidos para `predefinedEmote`, aunque el pack **Avatar Animations** de Creator Hub no los incluya.

{% hint style="warning" %}
**📔 Nota**: Usa estos nombres exactamente como aparecen en la lista. Un nombre incorrecto falla silenciosamente en tu Scene: no se reproduce nada y no aparece nada en la consola de la Scene. Ten cuidado con `handsintheair` sin separadores, y con `fistpump_short` que lleva un sufijo.
{% endhint %}

{% hint style="info" %}
**💡 Consejo**: Si un jugador camina o salta mientras se reproduce la animación, la interrumpirá. Si quieres evitarlo, puedes congelar el Avatar con [Modificadores de entrada](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/avatares/locomotion.md#freeze-the-player) durante la animación del avatar.
{% endhint %}

### Animaciones personalizadas

Usa `triggerSceneEmote()` para hacer que el jugador realice una animación personalizada, guardada como archivo .glb dentro de los assets de la escena.

{% hint style="info" %}
**💡 Consejo**: No tienes que crearlas tú. El paquete **Avatar Animations** del Scene Editor incluye 45 animaciones listas para usar, como poses sentado, pescar, cargar una caja y bailar. Arrastra una a la vista 3D y el editor copiará su archivo a la escena. Luego, pasa la ruta del archivo a `triggerSceneEmote()`. Los archivos se guardan en `assets/asset-packs/<animation-folder>/`, por ejemplo, `assets/asset-packs/whack/Whack_Avatar_emote.glb`. Comprueba la ruta exacta en **Local Assets**. Consulta [Añadir elementos](https://docs.decentraland.org/creator/content-creator-es/scene-editor/primeros-pasos/about-editor.md#avatar-animations).
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: El nombre del archivo **debe** terminar en `_emote.glb` para funcionar como animación de avatar.
{% endhint %}

Esta función recibe un objeto con las siguientes propiedades:

* `src`: La ruta completa al archivo de emote, relativa a la carpeta raíz del proyecto. Un archivo ubicado en `assets/animations/sit_emote.glb` requiere `'assets/animations/sit_emote.glb'`.
* `loop`: Si es true, la animación se repetirá continuamente hasta que el jugador se mueva o se detenga la animación. De forma predeterminada, es false.
* `mask`: (opcional) Reproduce la animación solo en una parte del cuerpo del avatar, usando un valor del enum `AvatarMask` . Por ejemplo, `AvatarMask.AM_UPPER_BODY` anima solo la parte superior del cuerpo del avatar. Consulta [Animar solo la parte superior del cuerpo](#animate-only-the-upper-body).

{% hint style="warning" %}
**📔 Nota**: `src` debe ser la ruta completa al archivo. No se busca por nombre de archivo ni se añade el sufijo `_emote` automáticamente. Si la ruta es incorrecta, `triggerSceneEmote()` devuelve `{ success: false }` y no se reproduce nada. Copia la ruta desde la carpeta del proyecto e incluye todas las carpetas.
{% 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" %}
**💡 Consejo**: Si un jugador camina o salta mientras se reproduce la animación, la interrumpirá. Si quieres evitarlo, puedes congelar el Avatar con [Modificadores de entrada](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/avatares/locomotion.md#freeze-the-player) durante la animación del avatar.
{% endhint %}

#### Accesorios, partículas y sonido

Un archivo de emote reproducido con `triggerSceneEmote()` puede incluir accesorios, como una raqueta de tenis o un chorro de llamas, animados junto con el avatar. Créalo igual que un emote de Emotes 2.0 y sigue las reglas de nomenclatura que se indican en [Accesorios y sonidos](https://docs.decentraland.org/creator/content-creator-es/wearables-y-emotes/emotes/props-and-sounds.md):

* El archivo contiene dos clips de animación: uno cuyo nombre incluye `_Avatar` para el avatar, y otro cuyo nombre incluye `_Prop` para el armature del accesorio.
* Ambos clips tienen la misma duración.
* Los efectos de partículas funcionan si los conviertes en huesos animados; consulta [Partículas en Emotes](https://docs.decentraland.org/creator/content-creator-es/wearables-y-emotes/emotes/particles-in-emotes.md).

Los demás jugadores que están cerca ven los accesorios, igual que ven la animación del avatar.

{% hint style="warning" %}
**📔 Nota**: `triggerSceneEmote()` no reproduce sonido. El audio solo se reproduce en los Emotes cargados como Emotes independientes en Builder. Para asociar un sonido a un Emote de escena, reprodúcelo con un [AudioSource](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/sounds.md) al mismo tiempo.
{% endhint %}

### Animar solo la parte superior del cuerpo

Tanto `triggerEmote()` como `triggerSceneEmote()` aceptan una propiedad opcional `mask` que limita la animación a una parte del cuerpo del avatar.

Normalmente, una animación se detiene en cuanto el jugador camina o salta, porque las animaciones de locomoción predeterminadas toman el control de todo el cuerpo. Si estableces `mask` en `AvatarMask.AM_UPPER_BODY`, la animación solo controla el avatar de la cintura para arriba, mientras que las piernas siguen controladas por las animaciones de locomoción predeterminadas. Esto permite que el jugador siga caminando o corriendo por la escena mientras se reproduce la animación de la parte superior del cuerpo. Usa esta opción para acciones que no deberían interrumpir el movimiento, como cargar una caja, sostener una antorcha o hacer malabares.

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

En este ejemplo, el jugador hace clic en un botón y empieza a animar los brazos en alto en un ciclo continuo. Como solo se anima la parte superior del cuerpo, puede seguir corriendo por la escena mientras celebra, por ejemplo, para seguir la acción en una carrera o un partido de fútbol.

Ten en cuenta lo siguiente:

* `AvatarMask.AM_UPPER_BODY` es actualmente el único valor del enum `AvatarMask` . Para reproducir una animación en todo el cuerpo, simplemente no establezcas la propiedad `mask` .
* La propiedad `loop` se comporta igual que en las animaciones de cuerpo completo: con `loop: false` la animación enmascarada se reproduce una vez y luego la parte superior del cuerpo vuelve a la locomoción normal, mientras que con `loop: true` se repite hasta que se detiene.
* Para detener desde el código una animación enmascarada que se repite, llama a `stopEmote({})`, también importado de `~system/RestrictedActions`. Se resuelve con `{ success: boolean }`.

### Detectar cuándo termina un emote

Cada evento del ciclo de vida de un emote se informa a través del componente `AvatarEmoteCommand` en la entidad del jugador. Cada nueva entrada incluye un campo `state` con un valor del enum `EmoteState` :

* `EmoteState.ES_STARTED`: El emote empezó a reproducirse. Este también es el valor informado cuando el campo `state` no está presente.
* `EmoteState.ES_FINISHED`: Un emote que no se repite llegó hasta su final natural.
* `EmoteState.ES_INTERRUPTED`: El emote se interrumpió antes de tiempo: el jugador se movió o saltó, se teletransportó, empezó otro emote, el emote se detuvo explícitamente o el jugador salió de la escena.

Esto funciona con los emotes activados por la escena (`triggerEmote()` y `triggerSceneEmote()`), así como con los emotes que el jugador reproduce por su cuenta desde la rueda de emotes y con los emotes que reproducen otros jugadores en la escena.

Usa la función `onChange` del componente `AvatarEmoteCommand` para reaccionar a cada nueva 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 función solo es compatible con el cliente de escritorio. Actualmente, los emotes reproducidos con un `mask` (emotes de cuerpo parcial) en el jugador local no informan eventos del ciclo de vida.
{% endhint %}

{% hint style="info" %}
**💡 Consejo**: Para reproducir animaciones en avatares que no son jugadores, consulta [Avatares NPC](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/interactividad/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-es/scenes-sdk7/interactividad/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.
