feat: head sync

[daniele-dcl]

Pull Request Description

Implementation of the head sync shape: https://www.notion.so/decentraland/Head-Sync-2735f41146a580d49421f7939a81aa2e

Basically we just sync head look-at vector across clients, so now we can see where other players are looking at.

Protocol PR: decentraland/protocol#326

Test Instructions

Can be tested anywhere, requires 2+ players.

• Head movement should be synced across clients
• Special case: head movement is disabled during emotes, that should also be the case for remote players. That is, say a player is looking up, then it plays an emote. You will see the head of the avatar stops pointing straight up, instead it just follows the natural movement of the emote. The same should be observed for other players
• Same applies to:
  • Player not being grounded
  • Player standing on a steep slope. A steep slope should be one that makes the avatar slide
  • Player being stunned (to my knowledge that only happens after a long fall)
  • Apparently also when standing on a moving platform (not sure why, but that's how the code works at the moment)

Some of the above conditions might be problematic to test. I personally think emotes are the most important to test because if we don't correctly disable head IK during emotes playback, it will look pretty weird.

Also in the settings there's a new option to disable head-sync. When head-sync is disabled other players should NOT see the head movement of the player who has it disabled.

Dev Notes

• Added a new int32 field in the protocol to send the look at data across the netowork
  • 1 bit for the enabled falg
  • 6 bits for yaw
  • 6 bits for pitch
  • Extra bits reserved for the 2nd part of the shape (avatar arm pointing at things)
• Extended IK system to handle remote players
• Enabled the RigBuilder component on remote players. This might impact performance? It was disabled before
• Notice in the system handling received network messages, we do NOT interpolate the IK angles like we do for the player position. This is because the IK logic already perform interpolation internally (see ApplyHeadLookAt.Execute)

[github-actions]

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

Name	Link
Commit	5e7ee74
Logs	https://github.com/decentraland/unity-explorer/actions/runs/20428787513
Download Windows	https://github.com/decentraland/unity-explorer/suites/52811734104/artifacts/4942327219
Download Windows S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/feat/head-sync/pr-16945-5e7ee74/Decentraland_windows64.zip
Download Mac	https://github.com/decentraland/unity-explorer/suites/52811734104/artifacts/4942274403
Download Mac S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/feat/head-sync/pr-16945-5e7ee74/Decentraland_macos.zip
Built on	2025-12-22T10:52:42Z

[Ludmilafantaniella]

✅ QA Approved
Tested and verified on Windows and macOS following the testing sheet and PR indications.

Coverage:

• Minigames: Head sync behaves correctly, no head sync breakage observed.

• Scenes with forced POV (e.g. MetadyneLabs): no issues, head sync does not break.

• Emotes: When triggering an emote while head sync is active and held in a specific position, head sync is correctly disabled and the emote plays as expected.

• Moving platforms / elevators: Head sync remains stable.

• Cross-OS testing (Windows ↔ macOS): Head sync works correctly across clients.

• Additional coverage & regression testing:

  • Head sync tested across multiple scenes, under different circumstances and movement types.
  • Regression testing performed on Backpack preview (emotes and wearables).
  • User Profile functionality verified.
  • Testing executed in Genesis Plaza V2, covering all available interactions in that environment.

No blocking issues found.
PR looks good to merge 👍

emote-headSync.mp4

Moving.plattforms.mp4