feat: sdk movePlayerTo duration

[pravusjif]

WHY

In talks with the Content Team and Regenesis Labs an idea came up to improve the movePlayerTo() restricted action to be able to assign a duration to the movement, making the avatar be automatically interpolated (and animated) towards the target position.

The idea also involved making the movePlayerTo() awaitable, so that creators can run code after the movement finishes (e.g.: running a scene emote when the movePlayerTo() actually finishes)

With this new update creators can use movePlayerTo() in the following way (or as can be seen in the dedicated test scene for this feature):

import { Vector3 } from '@dcl/sdk/math'
import { movePlayerTo } from '~system/RestrictedActions'

export function main() {
  function movePlayer() {
    // InputModifier here to BLOCK input if wanted

    movePlayerTo({
      newRelativePosition: Vector3.create(15, 0.1, 15),
      duration: 2
    }).then((result) => {
      console.log(`movePlayerTo() success/not-interrupted ? ${result.success}`)
      
      // CUSTOM CODE THAT RUNS AFTER MOVEMENT FINISHES HERE...
      
      // Remove InputModifier here if used
    })
  }
  movePlayer()
}

Related PRs:

• feat: movePlayerTo new duration field protocol#331 (main branch)
• feat: movePlayerTo duration protocol#327 (experimental branch)
• feat: movePlayerTo duration js-sdk-toolchain#1254
• chore: movePlayerTo with duration test scene sdk7-test-scenes#41

WHAT

• Implemented new PlayerMoveToWithDurationIntent internal component and MovePlayerWithDurationSystem to handle the movement and animations in an encapsulated centralized place.
• Updated RestrictedActions workflow for movePlayerTo() to make it an async awaitable and to run the already existent flow when the duration parameter is not there (or is 0)
• Added None(typeof(PlayerMoveToWithDurationIntent)) in some queries in the following systems to avoid overriding the avatar rotation during the movement interpolation: RotateCharacterSystem, CalculateCharacterVelocitySystem, CharacterAnimationSystem, InterpolateCharacterSystem, CharacterPlatformSystem
• Implemented test coverage

TEST INSTRUCTIONS

1. Download this test scene and extract it somewhere
2. In the scene root folder open a terminal and run npm i and then npm run start -- --explorer-alpha
3. Close the Explorer that auto-opened. Leave the scene running in the console/terminal.
4. Download the build from this PR and open it connected to the local scene (keep in mind its position is 11,0): https://github.com/decentraland/unity-explorer/wiki/How-to-connect-to-a-local-scene-(Unity-Editor---Custom-Build---Latest-Released-Build)#connecting-a-custom-build-to-the-scene
5. Once you enter the scene confirm that:

• When you click on the little cube in the floor, your avatar automatically moves to it
• When the avatar moves it is animated as walking/running
• The avatar faces the cube direction while moving
• The cube gets randomly re-positioned when the avatar finishes moving
• The big sphere in the center of the scene doesn't block the automatic movement
• If you move freely and try to go through the big sphere, you can't due to collisions
• You can interrupt the automatic movement using your input (and the cube will be immediately randomly repositioned)

Screen.Recording.2025-12-21.at.7.15.39.PM.mp4

[github-actions]

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

Name	Link
Commit	fd61f47
Logs	https://github.com/decentraland/unity-explorer/actions/runs/20412581803
Download Windows	https://github.com/decentraland/unity-explorer/suites/52772655232/artifacts/4937660328
Download Windows S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/feat/sdk-move-player-to-duration/pr-16941-fd61f47/Decentraland_windows64.zip
Download Mac	https://github.com/decentraland/unity-explorer/suites/52772655232/artifacts/4937715193
Download Mac S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/feat/sdk-move-player-to-duration/pr-16941-fd61f47/Decentraland_macos.zip
Built on	2025-12-21T18:43:06Z