> 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/scenes-sdk7/interactivity/avatars/avatar-animations.md). # Avatar Animations Make the player's avatar play default or custom animations, and detect when an emote finishes You can make the player perform an animation as part of the scene's code. This can help provide more immersion, and it can also help communicate what other players are doing to each other. The avatar animations are seen both by the player (in 3rd person view) and any other players around. Player-controlled animations that run on the full body are overridden by the default locomotion animations, like walking and jumping. So full-body animations played by the scene only play while the player is standing still. If the player walks or jumps, any full-body animations are interrupted. Upper-body animations don't get interrupted by movement. {% hint style="warning" %} **📔 Note**: Players can only be animated if they already are standing inside the scene's bounds, not if they are on a neighboring scene. Smart wearables can play animations anywhere. While a player is performing an animation, they are not affected by collisions, and their movements aren't constrained by the scene's physics. Also note that if an animation displaces the player from their original position (for example, if the animation involves a jump), the player's Transform component will not be affected by this displacement. {% endhint %} ### Use the Scene Editor The easiest way to make a player perform an animation is to use the Scene Editor. Use the no-code **Play Emote** action to play a default animation, or the **Play Custom Emote** action to play an animation from a file. See [Make any item smart](/creator/scene-editor/interactivity/make-any-item-smart.md). ### 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 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. See [Animate only the upper body](#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' }) } ) ``` The following emotes show feedback about player actions in your scene, all of these are valid values for the `predefinedEmote` field: * `buttonDown` * `buttonFront` * `getHit` * `knockOut` * `lever` * `openChest` * `openDoor` * `punch` * `push` * `swingWeaponOneHand` * `swingWeaponTwoHands` * `throw` * `sittingChair1` * `sittingChair2` * `sittingGround1` * `sittingGround2` These emotes are available to all players in their default emote wheel, and can also be used in any scene. * `wave` * `fistpump` * `robot` * `raiseHand` * `clap` * `money` * `kiss` * `tik` * `hammer` * `tektonik` * `dontsee` * `handsair` * `shrug` * `disco` * `dab` * `headexplode` {% hint style="info" %} **💡 Tip**: If a player walks or jumps while playing the animation, they will interrupt it. If you don't want that to be possible, you can freeze the avatar with [Input Modifiers](/creator/scenes-sdk7/interactivity/avatars/locomotion.md#freeze-the-player) for the duration of the avatar animation. {% endhint %} ### Custom animations Use the `triggerSceneEmote()` to make the player perform a custom animation, stored as a .glb file as part of the scene's asset. {% hint style="warning" %} **📔 Note**: The file's name **must** end in `_emote.glb` to work as an avatar animation. {% endhint %} 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. See [Animate only the upper body](#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: 'Make snowball' }, }, () => { triggerSceneEmote({ src: 'animations/Snowball_Throw_emote.glb', loop: false, mask: AvatarMask.AM_UPPER_BODY }) } ) ``` {% hint style="info" %} **💡 Tip**: If a player walks or jumps while playing the animation, they will interrupt it. If you don't want that to be possible, you can freeze the avatar with [Input Modifiers](/creator/scenes-sdk7/interactivity/avatars/locomotion.md#freeze-the-player) for the duration of the avatar animation. {% endhint %} ### Animate only the upper body Both `triggerEmote()` and `triggerSceneEmote()` accept an optional `mask` property, that limits the animation to only part of the avatar's body. Normally, an animation stops as soon as the player walks or jumps, because the default locomotion animations take over the whole body. When you set `mask` to `AvatarMask.AM_UPPER_BODY`, the animation only drives the avatar from the waist up, and the legs remain controlled by the default locomotion animations. This means the player can keep walking or running around the scene while the upper body plays your animation. Use this for actions that shouldn't interrupt movement, like carrying a crate, holding a torch, or juggling. ```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: 'animations/Cheer_emote.glb', loop: true, mask: AvatarMask.AM_UPPER_BODY, }) } ) ``` In this example, the player clicks a button and starts cheering with their arms in the air, in a looping animation. Since only the upper body is animated, they can keep running around the scene while they cheer, for example to follow the action in a race or a football match. Some things to keep in mind: * `AvatarMask.AM_UPPER_BODY` is currently the only value in the `AvatarMask` enum. To play an animation on the full body, simply don't set the `mask` property. * The `loop` property behaves the same as with full-body animations: with `loop: false` the masked animation plays once and the upper body then returns to normal locomotion, with `loop: true` it repeats until stopped. * To stop a looping masked animation from code, call `stopEmote({})`, also imported from `~system/RestrictedActions`. ### Detect when an emote finishes Every emote lifecycle event is reported through the `AvatarEmoteCommand` component on the player entity. Each new entry carries a `state` field, with a value from the `EmoteState` enum: * `EmoteState.ES_STARTED`: The emote started playing. This is also the value reported when the `state` field is absent (entries written by older clients). * `EmoteState.ES_FINISHED`: A non-looping emote played through to its natural end. * `EmoteState.ES_INTERRUPTED`: The emote was cut short: the player moved or jumped, teleported, another emote started, the emote was explicitly stopped, or the player left the scene. This works for emotes triggered by the scene (`triggerEmote()` and `triggerSceneEmote()`) as well as emotes the player plays themselves through the emote wheel, and also for emotes played by other players in the scene. Use the `onChange` function on the `AvatarEmoteCommand` component to react to each new entry: ```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" %} **📔 Note**: This feature is only supported in the Desktop client. Emotes played with a `mask` (partial-body emotes) on the local player don't currently report lifecycle events. {% endhint %} {% hint style="info" %} **💡 Tip**: To play animations on avatars that aren't players, see [NPC Avatars](/creator/scenes-sdk7/interactivity/avatars/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/scenes-sdk7/interactivity/avatars/avatar-animations.md?ask=&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.