feat: avatar masks

[Maurizio-dcl]

Pull Request Description

protocol PR
js-sdk-toolchain PR
sdk7-test-scenes PR

What does this PR change?

Implements avatar masks for the emote system, enabling partial-body (upper body) emote animations alongside full-body movement. This allows scenes to trigger emotes that only affect specific avatar parts while preserving locomotion on the rest of the body.

Test Instructions

These instructions are meant to be used in the 88,-13-avatar-masks-test-scene from this PR.

1. Green box triggers a masked emote on the upper body only
2. Yellow box triggers a full body emote
3. Red box stops any emote
4. Crate can be pickup up with E and dropped in front of the avatar with F

⚠️ NOTE: The crate uses the avatar attach component to demonstrate how masked emotes can be used with this component to achieve natural interactions with scene props, any bug related to the crate behavior should not be considered as part of this PR

Test Steps

1. Trigger the masked upper body emote interacting with the green box
2. Verify the upper body plays the emote animation while legs continue locomotion
3. Walk/run/jump during the masked emote — verify lower body movement is unaffected
4. Exit the scene and re-enter — verify masked emote pauses on exit and resumes on re-enter
5. Trigger a full-body emote while a masked emote is active (using the emote wheel or interacting with the yellow box) — verify masked emote stops and resumes on end
6. Start gliding while a masked emote is playing — verify masked emote stops and resumes on end
7. Test with another player in the same scene — verify remote player's masked emote renders correctly on upper body layer
8. Reload the scene and verify all state is reset — no masked emote should be playing
9. Trigger stopEmote() from scene — verify both local and remote masked emotes stop cleanly

Additional Testing Notes

• Edge case: quick entering / exiting should not leave stuck masked emote state
• Verify prop animations and head/hands IK are correctly disabled during masked emote playback
• Verify full-body emotes on remote players still work as before (no regression)

Quality Checklist

• Changes have been tested locally
• Documentation has been updated (if required)
• Performance impact has been considered
• For SDK features: Test scene is included

Code Review Reference

Please review our Code Review Standards before submitting.

[github-actions]

Windows and Mac build successful in Unity Cloud! You can find a link to the downloadable artifact below.

Name	Link
Commit	80c6440
Logs	https://github.com/decentraland/unity-explorer/actions/runs/24417001702
Download Windows	https://github.com/decentraland/unity-explorer/suites/64616787148/artifacts/6436563830
Download Windows S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/feat/avatar-masks/pr-21068-80c6440/Decentraland_windows64.zip
Download Mac	https://github.com/decentraland/unity-explorer/suites/64616787148/artifacts/6435935961
Download Mac S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/feat/avatar-masks/pr-21068-80c6440/Decentraland_macos.zip
Built on	2026-04-14T19:50:25Z

[AnsisMalins]

PR 7462

PR number: 7462
Windows change build
Windows baseline build
macOS change build
macOS baseline build

Intel Core i3

Change samples: 2672
Baseline samples: 2672

Metric	Change	Baseline	Delta	Improvement
CPU average	33.6 ms	33.6 ms	-0.0 ms	0.0%	⚪
CPU 1% worst	53.3 ms	57.9 ms	-4.7 ms	8.1%	🟢
CPU 0.1% worst	115.6 ms	147.5 ms	-31.9 ms	21.6%	🟢
GPU average	16.2 ms	16.4 ms	-0.2 ms	1.2%	⚪
GPU 1% worst	22.5 ms	22.0 ms	0.6 ms	-2.6%	⚪
GPU 0.1% worst	27.0 ms	25.8 ms	1.3 ms	-4.9%	🔴

[Ludmilafantaniella]

QA Result: ✅ Approved
Tested on Windows and Mac using the world provided by the dev (nebi.dcl.eth).

What was tested:

• Upper body masked emote triggers correctly via green box — legs continue locomotion unaffected
• Walk, run and jump during masked emote — lower body movement unaffected
• Exit and re-enter scene — masked emote pauses and resumes correctly
• Full body emote triggered while masked emote is active — masked emote stops and resumes on end
• Gliding while masked emote is playing — masked emote stops and resumes on end
• Remote player's masked emote renders correctly on upper body layer
• Scene reload — all state resets correctly, no stuck masked emote
• stopEmote() — both local and remote masked emotes stop cleanly
• Quick enter/exit edge case — no stuck state
• Full body emotes on remote players — no regression

Notes:

• Some issues were found during testing and have been fixed. Thread for context here.
• One sync issue remains but is unrelated to this branch — it also occurs in prod in scenes like Genesis Plaza.

7562-evi.1.mp4

✅Smoke Test performed:

• ✔️ Backpack and wearables in world
• ✔️ Emotes in world and in backpack
• Scene Emotes on Genesis Plaza
• Scene with auto emote: The Inn & Goerli
• ✔️ Teleport with map/coordinates/Jump In
• ✔️ Chat and multiplayer
• ✔️ Profile card
• ✔️ Camera
• ✔️ Skybox

[alejandro-jimenez-dcl]

Left some comments. Great work!