feat: avatarMask in triggerEmote functions

ai-sdk-context/sdk7-complete-reference.md

@@ -1070,12 +1070,16 @@ engine.addSystem(checkCameraMode)
 
 ```typescript
 import { triggerEmote, triggerSceneEmote } from '~system/RestrictedActions'
+import { AvatarMask } from '@dcl/sdk/ecs'
 
 // Default emote
 triggerEmote({ predefinedEmote: 'robot' })
 
 // Custom emote (file must end with _emote.glb)
 triggerSceneEmote({ src: 'animations/Snowball_Throw_emote.glb', loop: false })
+
+// Optional `mask` (both functions): play the animation on only part of the body
+triggerSceneEmote({ src: 'animations/Snowball_Throw_emote.glb', loop: false, mask: AvatarMask.AM_UPPER_BODY })
 ```
 
 Notes:

ai-sdk-context/sdk7-examples.mdc

@@ -1035,15 +1035,23 @@ CameraModeArea.create(entity, {
 ### Emotes
 ```typescript
 import { triggerEmote, triggerSceneEmote } from '~system/RestrictedActions'
+import { AvatarMask } from '@dcl/sdk/ecs'
 
 // Play a predefined avatar emote
 triggerEmote({ predefinedEmote: 'robot' })  // 'wave', 'dance', etc.
 
 // Play a custom animation
-triggerSceneEmote({ 
+triggerSceneEmote({
   src: 'animations/myAnimation.glb',
   loop: false
 })
+
+// Optional `mask` (both functions): play the animation on only part of the body
+triggerSceneEmote({
+  src: 'animations/myAnimation.glb',
+  loop: false,
+  mask: AvatarMask.AM_UPPER_BODY
+})
 ```
 
 ## Lights & Visual Effects

creator-esp/sdk7/interactivity/trigger-emotes.md

@@ -22,9 +22,10 @@ La forma más fácil de hacer que un jugador realice una animación es usar el [
 
 ## 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 toma un objeto con una sola propiedad como argumento:
+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 toma un objeto con las siguientes propiedades como argumento:
 
 * `predefinedEmote`: Un nombre de cadena para 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.
 
 ```ts
 import { triggerEmote } from '~system/RestrictedActions'
@@ -98,9 +99,11 @@ Esta función toma un objeto como argumento con los siguientes argumentos:
 
 * `src`: Una cadena con una ruta al archivo de emote.
 * `loop`: Si es true, la animación se repetirá continuamente hasta que el jugador se mueva o se detenga la animación. False por defecto.
+* `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.
 
 ```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) })
@@ -112,7 +115,7 @@ pointerEventsSystem.onPointerDown(
 		opts: { button: InputAction.IA_POINTER, hoverText: 'Make snowball' },
 	},
 	() => {
-		triggerSceneEmote({ src: 'animations/Snowball_Throw_emote.glb', loop: false })
+		triggerSceneEmote({ src: 'animations/Snowball_Throw_emote.glb', loop: false, mask: AvatarMask.AM_UPPER_BODY })
 	}
 )
 ```

creator/sdk7/interactivity/player-avatar.md

@@ -139,9 +139,10 @@ The easiest way to make a player perform an animation is to use the Scene Editor
 
 ### Default animations
 
-Use the `triggerEmote()` function to run one of the default animations that players are able to play anywhere in Decentraland. This function takes an object with a single property as an argument:
+Use the `triggerEmote()` function to run one of the default animations that players are able to play anywhere in Decentraland. This function takes an object with the following properties as an argument:
 
 * `predefinedEmote`: A string name for an existing emote.
+* `mask`: (optional) Play the animation on only part of the avatar's body, using a value from the `AvatarMask` enum. For example, `AvatarMask.AM_UPPER_BODY` animates only the avatar's upper body.
 
 ```ts
 import { triggerEmote } from '~system/RestrictedActions'
@@ -215,9 +216,11 @@ This function takes an object with the following properties:
 
 * `src`: A string with a path to the emote file.
 * `loop`: If true, the animation will loop continuously until the player moves or the animation is stopped. False by default.
+* `mask`: (optional) Play the animation on only part of the avatar's body, using a value from the `AvatarMask` enum. For example, `AvatarMask.AM_UPPER_BODY` animates only the avatar's 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) })
@@ -229,7 +232,7 @@ pointerEventsSystem.onPointerDown(
 		opts: { button: InputAction.IA_POINTER, hoverText: 'Make snowball' },
 	},
 	() => {
-		triggerSceneEmote({ src: 'animations/Snowball_Throw_emote.glb', loop: false })
+		triggerSceneEmote({ src: 'animations/Snowball_Throw_emote.glb', loop: false, mask: AvatarMask.AM_UPPER_BODY })
 	}
 )
 ```