fix: Maintain LocalPlayer-related data on all scenes

[mikhail-dcl]

Fixes decentraland/creator-hub#264

Problem

SDKProfile is propagated to the scene with 1 frame delay, making the following code fail onStart:

      const playerData = PlayerIdentityData.getOrNull(userEntity)
      const avatarData = AvatarBase.getOrNull(userEntity)
      const wearablesData = AvatarEquippedData.getOrNull(userEntity)

Solution

Make the whole set of Avatar-related components available on the systems' Initialize which is called before the scen starts. It's right the same flow seen in WriteMainPlayerTransformSystem

Sensitive changes

• User-related data now will be available for the scene even if it's not current
• To make it symmetric if the user profile is updated the corresponding data will be pushed to the scene as well (even if it's not current)
• The grey zone existed before: TransformComponent was available for the player entity right away whereas PlayerIdentityData, AvatarBase and AvatarEquippedData were not available until the player steps on the current scene

P.S. Behavior for remote peers has not changed.

How to QA

import { getPlayer } from '@dcl/sdk/src/players'

export function main() {

	let myPlayer = getPlayer()

	if (myPlayer) {
		console.log('Name : ', myPlayer.name)
		console.log('UserId : ', myPlayer.userId)
	}
}

• Execute the scene with the given script, you should see data properly logged.
• Perform regression on the scenes which are relying on the players' data

[github-actions]

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

Name	Link
Commit	d175dde
Logs	https://github.com/decentraland/unity-explorer/actions/runs/26278879094
Download Windows	https://github.com/decentraland/unity-explorer/suites/70288664200/artifacts/7157488885
Download Windows S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/feat/seed-local-player-crdt-on-scene-init/pr-22566-d175dde/Decentraland_windows64.zip
Download Mac	https://github.com/decentraland/unity-explorer/suites/70288664200/artifacts/7157345385
Download Mac S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/feat/seed-local-player-crdt-on-scene-init/pr-22566-d175dde/Decentraland_macos.zip
Built on	2026-05-22T09:42:49Z

[m3taphysics]

PR #8837, run #26182654059

Builds: Windows change, Windows baseline, macOS change, macOS baseline

Framework 13 i7

Metric	Change	Baseline	Delta	Improvement
Samples	2700	2700
CPU average	33.3 ms	33.3 ms	-0.0 ms	0.0%	⚪
CPU 1% worst	33.9 ms	34.0 ms	-0.1 ms	0.2%	⚪
CPU 0.1% worst	38.2 ms	37.2 ms	1.0 ms	-2.6%	⚪
GPU average	7.8 ms	7.9 ms	-0.1 ms	1.4%	⚪
GPU 1% worst	19.2 ms	18.6 ms	0.6 ms	-3.4%	🔴
GPU 0.1% worst	25.4 ms	23.5 ms	1.9 ms	-8.1%	🔴

[github-actions]

🔍 Claude reviewed this PR and found no blocking issues, but assessed it as complex — human DEV review is still required before merging.

[claude]

Failing tests not updated for this behavior change.

SceneState.Starting is now accepted as valid for assignment, but two pre-existing tests assert the opposite behavior and are not updated by this PR:

1. NotAssignPlayerWhenSceneIsStarting (lines 293–313) — asserts AssignedToScene = false when the scene is Starting, but this code will now set it to true. Both isMainPlayer = true and isMainPlayer = false variants fail.

2. AssignPlayerWhenSceneTransitionsFromStartingToRunning (lines 315–346) — the first Update() tick (scene still Starting) now assigns the player, so Assert.IsFalse(playerCRDTEntity.AssignedToScene) at line 334 fails.

These tests need to be updated to cover the new semantics. For NotAssignPlayerWhenSceneIsStarting, the test should be renamed and updated to verify that the player is assigned when the scene is Starting. For AssignPlayerWhenSceneTransitionsFromStartingToRunning, the intermediate assertion after the first tick should be removed or changed to IsTrue.

Fix this →

[m3taphysics]

PR #8837, run #26220267637

Builds: Windows change, Windows baseline, macOS change, macOS baseline

Framework 13 i7

Metric	Change	Baseline	Delta	Improvement
Samples	2699	2700
CPU average	33.3 ms	33.3 ms	0.0 ms	-0.0%	⚪
CPU 1% worst	34.0 ms	33.7 ms	0.3 ms	-0.8%	⚪
CPU 0.1% worst	36.9 ms	36.0 ms	0.9 ms	-2.6%	⚪
GPU average	7.9 ms	7.7 ms	0.1 ms	-1.8%	⚪
GPU 1% worst	19.2 ms	20.3 ms	-1.2 ms	5.8%	🟢
GPU 0.1% worst	25.2 ms	24.5 ms	0.7 ms	-3.0%	🔴

[claude]

BLOCKING — test assertion contradicts current implementation.

Commit ea34e551 removed the World.Remove<PlayerSceneCRDTEntity> call from RemovePlayerFromScene for the local player:

// Local Player is never removed from the scene world
if (crdtEntity.Id == SpecialEntitiesID.PLAYER_ENTITY)
    return;

With that early return, PlayerSceneCRDTEntity is never removed from PersistentEntities.Player when the local player leaves a scene. The assertion below will therefore always fail (component is still present):

Assert.IsFalse(scene1World.Has<PlayerSceneCRDTEntity>(playerCRDTEntity.SceneWorldEntity)); // FAILS

Per the PR's stated intent ("user-related data will be available for the scene even if it's not current"), the expected behavior is now that the component persists. Fix: change to Assert.IsTrue and update the comment on line 154 accordingly.

Fix this →

[claude]

BLOCKING — same issue as line 157. RemovePlayerFromScene returns early for local player without removing PlayerSceneCRDTEntity, so scene1Entity (which is scene1Facade.PersistentEntities.Player) still has the component after the player moves to scene2. Assert.IsFalse will fail. Change to Assert.IsTrue and update the comment on line 200 to say the persistent entity retains PlayerSceneCRDTEntity.

[m3taphysics]

PR #8837, run #26226730238

Builds: Windows change, Windows baseline, macOS change, macOS baseline

Framework 13 i7

Metric	Change	Baseline	Delta	Improvement
Samples	2700	2699
CPU average	33.3 ms	33.3 ms	-0.0 ms	0.0%	⚪
CPU 1% worst	33.5 ms	33.9 ms	-0.4 ms	1.3%	⚪
CPU 0.1% worst	33.8 ms	37.6 ms	-3.8 ms	10.2%	🟢
GPU average	7.6 ms	7.9 ms	-0.3 ms	3.8%	🟢
GPU 1% worst	19.2 ms	19.6 ms	-0.4 ms	1.9%	⚪
GPU 0.1% worst	25.3 ms	25.1 ms	0.2 ms	-0.9%	⚪

[DafGreco]

✔️ PR reviewed and approved by QA on both platforms following instructions playing both happy and un-happy path

Regressions for this ticket had been performed in order to verify that the normal flow is working as expected:

• [✔️ ] Backpack and wearables in world
• [✔️ ] Emotes in world and in backpack
• [ ✔️] Teleport with map/coordinates/Jump In
• [✔️ ] Chat and multiplayer
• [ ✔️] Profile card
• [ ✔️] Skybox
• [ ✔️] Settings

In order to re-create this one :

1. Open the index of a scene folder
2. Copy the text and erase the other one inside index
3. Save the new text
4. npm i on the src code
5. npm run start
6. check that when enteering to the scene the console mentions the name and wallet of the user

Evidence:

20260522-0824-01.1221605.mp4

[claude]

Claude finished @mikhail-dcl's task in 4m 7s —— View job

---

PR Review (Re-review after sync)

• Gather context (read CLAUDE.md, docs/README.md)
• Read changed files and full diff
• Check if previous blocking issues were resolved
• Verify current state of all changed files
• Post final review summary

---

Root-cause check

PASS. getPlayer() returned null in scene main() because SDKProfile / PlayerSceneCRDTEntity were seeded one frame after the JS runtime started. The fix is structural: LocalPlayerCRDTEntityHandlerSystem.Initialize() seeds both components onto PersistentEntities.Player in every scene world before the runtime starts. This addresses the root cause directly.

---

Previous blocking issue 1 — RESOLVED ✅

Commit 6c2dc08f correctly updated the SceneState.Starting tests:

• NotAssignPlayerWhenSceneIsStarting → renamed AssignPlayerWhenSceneIsStarting, all assertions inverted to confirm assignment
• AssignPlayerWhenSceneTransitionsFromStartingToRunning → renamed KeepPlayerAssignedWhenSceneTransitionsFromStartingToRunning, intermediate IsFalse changed to IsTrue

Previous blocking issue 2 — RESOLVED ✅

Commit d175ddef correctly updated the two assertions that were broken by ea34e551's early-return for local player in RemovePlayerFromScene:

• RemovePlayerCRDTEntityForPlayersLeavingScene(isMainPlayer=true) — line 157 now Assert.IsTrue(scene1World.Has<PlayerSceneCRDTEntity>(...)) ✅
• ChangeSceneOnPlayerMove(isMainPlayer=true) — line 202 now Assert.IsTrue(scene1Facade.EcsExecutor.World.Has<PlayerSceneCRDTEntity>(...)) ✅

Both match the new intended behavior: the persistent player entity retains PlayerSceneCRDTEntity even when the local player leaves a scene.

---

No new blocking issues

The full current diff is clean:

• LocalPlayerCRDTEntityHandlerSystem — Initialize() seeds PlayerSceneCRDTEntity + SDKProfile before JS runtime; Update() re-propagates on IsDirty. System ordering ([UpdateBefore] on WriteSDKAvatarBaseSystem etc.) ensures the seed is visible to writer systems.
• PlayerCRDTEntitiesHandlerSystem — RemovePlayerFromScene early-returns for local player (preserving persistent entity data). Remote-player path is unchanged.
• WriteSDKAvatarBaseSystem — Initialize() calls UpdateAvatarBaseQuery(World, true) with force=true; first Update() may write again because IsDirty is still set, but CRDT is idempotent — no impact.
• MultiplayerPlugin — LocalPlayerCRDTEntityHandlerSystem is now wired first in InjectToWorld, ensuring its Initialize() runs before the writer systems'.
• Test coverage — SeedLocalPlayerCRDTSystemShould (new) covers the seeding path and the no-profile early exit. All PlayerCRDTEntitiesHandlerSystemShould cases are consistent with current implementation.

---

Non-blocking observations (unchanged from previous review)

CharacterDataPropagationUtility.PropagateGlobalPlayerToScenePlayer is dead production code (only called from PlayerProfileDataPropagationSystemShould test). It uses an unguarded World.Add for PlayerSceneCRDTEntity — if it ever acquired a production caller after Initialize() runs, it would throw. No immediate risk since it has no production callers, but the method could be removed or converted to AddOrSet to prevent future confusion.

---

REVIEW_RESULT: PASS ✅
COMPLEXITY: COMPLEX
COMPLEXITY_REASON: Touches cross-world ECS access (global ↔ scene propagation via PersistentEntities), CRDT bridge seeding order, plugin/DI wiring, scene lifecycle state machine, and system execution ordering.
QA_REQUIRED: YES

[m3taphysics]

PR #8837, run #26280529239

Builds: Windows change, Windows baseline, macOS change, macOS baseline

Framework 13 i7

Metric	Change	Baseline	Delta	Improvement
Samples	2700	2700
CPU average	33.3 ms	33.3 ms	0.0 ms	-0.0%	⚪
CPU 1% worst	33.8 ms	33.7 ms	0.1 ms	-0.2%	⚪
CPU 0.1% worst	37.1 ms	37.3 ms	-0.3 ms	0.7%	⚪
GPU average	8.0 ms	8.0 ms	-0.0 ms	0.5%	⚪
GPU 1% worst	19.7 ms	18.6 ms	1.1 ms	-5.8%	🔴
GPU 0.1% worst	29.2 ms	25.0 ms	4.2 ms	-16.8%	🔴