feat: sdk collision layer for main player + corrections

[pravusjif]

Adds the CL_MAIN_PLAYER collider layer (replaces the unused CL_RESERVED2) and unifies how Raycast and TriggerArea treat ColliderLayer masks for the local player avatar.

What changed

• New layer CL_MAIN_PLAYER (value 8) — targets the local player avatar specifically.
• Additive avatar semantics — the main player is tagged with both CL_PLAYER and CL_MAIN_PLAYER; remote avatars carry only CL_PLAYER.
• Unified main-player qualification rule — both Raycast and TriggerArea now use the same constant PLAYER_QUALIFYING_BITS = CL_PLAYER | CL_MAIN_PLAYER. CL_PHYSICS, CL_POINTER, CL_CUSTOM*, and CL_NONE no longer hit / fire on the local player.
• MeshCollider / GltfContainer — masks containing CL_PLAYER or CL_MAIN_PLAYER (without CL_PHYSICS) now route to a new dedicated Unity layer SDKAvatarHit: raycast- and trigger-detectable, but the player capsule walks through (previously the collider was silently disabled). Mixing in CL_PHYSICS keeps the mesh solid against the player.
• TriggerArea optimisation — a CL_MAIN_PLAYER-only trigger now skips remote-avatar overlaps inside the MonoBehaviour via the existing TargetTransform early-out.
• Unity layer rename AllAvatars → SDKAvatarTriggerArea — the layer slot (18) is unchanged, only the name changes. The old name was misleading (no avatars actually live on that layer; it hosts the avatar-targeting TriggerArea collider). Pairs cleanly with the existing SDKEntityTriggerArea name. C# constant renamed PhysicsLayers.ALL_AVATARS → PhysicsLayers.SDK_AVATAR_TRIGGER_AREA.

Behaviour comparison

BEFORE

Mask	Raycast hits main player	TriggerArea fires for main player
CL_PLAYER	yes	yes
CL_PHYSICS	yes	no
CL_POINTER alone	yes	no
CL_CUSTOM* alone	yes	no
CL_NONE	yes	no

The two systems disagreed on every mask except CL_PLAYER. (CL_MAIN_PLAYER did not exist.)

AFTER

Mask	Raycast hits main player	TriggerArea fires for main player
CL_PLAYER	yes	yes
CL_MAIN_PLAYER	yes	yes
CL_PLAYER | CL_MAIN_PLAYER	yes	yes
CL_PHYSICS	no	no
CL_POINTER alone	no	no
CL_CUSTOM* alone	no	no
CL_NONE	no	no

The two systems now agree on every mask.

Migration note

Scenes that previously relied on CL_PHYSICS raycasts to detect the local player must now OR CL_MAIN_PLAYER (or CL_PLAYER) into their mask. Walls-and-floors physics checks that do not target the player are unchanged.

Related PRs

• feat: collision layer for main player (main) protocol#418
• feat: collision layer main player js-sdk-toolchain#1414
• chore: update collision layer docs docs#104
• chore: sdk collider layers test scene sdk7-test-scenes#71

QA TEST INSTRUCTIONS

The test scene requires using 2 instances of the Explorer, however you have to focus on the outcome only looking at the behaviours in 1 of the 2 explorers. The other explorer is only used to move the "other avatar" around the test scene.

SETUP

Download the build from this PR and open it connected to the SEPOLIA (Switch MetaMask to the SEPOLIA network, not mainnet) sdk7testscenes.dcl.eth world and to position 5,5:

Windows
"C:\Users\[YOUR-USER]\Downloads\Decentraland_windows64\Decentraland.exe" --realm sdk7testscenes.dcl.eth --dclenv zone --position 5,5 --skip-version-check true --multi-instance

macOS
open -n Decentraland.app --args --realm sdk7testscenes.dcl.eth --dclenv zone --position 5,5 --skip-version-check true --multi-instance

(Generic instructions to connect a custom build with app params at: https://github.com/decentraland/unity-explorer/blob/dev/docs/how-to-connect-to-a-local-scene.md)

OTHER-PLAYER AVATAR TEST

TRIGGER AREAS

1. Move the "other player avatar" between the 4 trigger areas
2. Confirm that only the areas that contain "CL_PLAYER" in their name turn green when the other player avatar is inside.

RAYCAST

1. Place the other player avatar between the raycast sphere and the CL_PHYSICS cube
2. Wait until a NEW ray is shot targetting the CL_PLAYER layer and confirm that the other player avatar is detected by the raycast
3. Confirm that no other Layer detects the other player avatar (the CL_PHYSICS layer should be hitting the cube, not the other player avatar)

MAIN-PLAYER AVATAR TEST

TRIGGER AREAS

1. Move your main player avatar between the 4 trigger areas
2. Confirm that any area that contains "CL_PLAYER" OR "CL_MAIN_PLAYER" in their name turn green when the main player avatar is inside.

RAYCAST

1. Place the main player avatar between the raycast sphere and the CL_PHYSICS cube
2. Wait until a NEW ray is shot targetting the CL_PLAYER layer and confirm that the main player avatar is detected by the raycast.
3. Confirm the same happens with the CL_MAIN_PLAYER raycast
4. Confirm that no other Layer detects the main player avatar (the CL_PHYSICS layer should be hitting the cube, not the other player avatar)

RAYCAST LAYERS TEST

When you click the raycast sphere, it will rotate to target a different cube.

Run a full round of different raycast layers for EACH cube confirming that the cubes are only detected when they contain the layer that the raycast is targetting.

DEMO VIDEO

Screen.Recording.2026-06-08.at.10.39.03.PM.mp4

[github-actions]

New build in progress, come back later!

[m3taphysics]

PR #8865, run #27433993442

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

How to read this table

• Each build is measured 3 times. The values are the median, and (min–max) is the lowest and highest of those runs — a wide range means the metric is noisy and small differences are not trustworthy.
• Δ is Change minus Baseline (a negative Δ means Change is faster).
• 🟢 faster / 🔴 slower — a real difference: larger than both 3% and the run-to-run range.
• ⚪ within noise — the difference is smaller than how much the build varies between its own runs, so it cannot be told apart from random variation. Treat it as no change.
• Exceptions per run — the average number of exceptions in a run's log; more than the baseline is flagged 🔴 even when frame times look fine. The Exception breakdown under each table groups them by the explorer's report category and exception type (as totals across the runs).
• A run that logged unusually many exceptions (at least 10 and 5× the median of its build's runs — e.g. a service was down during it) is excluded from all numbers and called out under the table.

Framework 13 i7

Metric	Baseline	Change	Δ	Result
Samples	2701 (×3)	2701 (×3)
CPU average	33.3 ms	33.3 ms	0.0 ms	⚪ within noise
CPU 1% worst	33.8 ms (33.7–34.0)	33.7 ms (33.6–33.8)	-0.0 ms	⚪ within noise
CPU 0.1% worst	37.1 ms (36.0–37.2)	36.8 ms (34.9–37.8)	-0.4 ms	⚪ within noise
GPU average	7.5 ms (7.5–7.6)	7.8 ms (7.6–7.9)	0.3 ms	🔴 4% slower
GPU 1% worst	19.7 ms (19.2–20.0)	18.7 ms (18.6–19.5)	-0.9 ms	🟢 5% faster
GPU 0.1% worst	24.8 ms (24.1–26.8)	23.9 ms (23.5–26.1)	-0.8 ms	⚪ within noise
Exceptions per run	2	3	+1	🔴 more errors

Exception breakdown

Exception	Baseline (3 runs)	Change (3 runs)
[ENGINE] NullReferenceException	6	6
[ENGINE] ObjectDisposedException	0	3

[claude]

Claude finished @mikhail-dcl's task in 1m 3s —— View job

---

Security-Focused Dependency & Prompt Review (re-synced — head 4968f764)

• Diff PR vs origin/dev
• Check dependency changes (package.json / lockfiles / manifests)
• Check prompt-file changes (.claude/agents/**)
• Check new binaries / native plugins / asmdefs
• Post verdict

This is a re-sync of the supply-chain review. The net diff vs origin/dev contains no dependency, lockfile, manifest, or native-binary changes. The security-relevant surface is limited to two benign Claude subagent doc files; the rest is the CL_MAIN_PLAYER feature (out of scope for supply-chain review).

---

1. Dependency changes — 🟢 NONE

git diff origin/dev...HEAD touches no package.json, package-lock.json, manifest.json, or packages-lock.json. No registry/git/path dependency was added, removed, or repinned. (The @dcl/protocol bump referenced in the PR body already lives in origin/dev, so it does not appear in the two-dot diff.)

2. Binaries / native plugins / asmdefs — 🟢 PASS

File	Finding	Risk
Plugins/DclNativeExitStopwatch.meta	Deleted — orphaned .meta (guid only, no associated binary). Removing a dangling meta.	🟢 Low
Character Camera.prefab	Unity prefab (collision-layer config for the feature). Not a native/managed binary.	🟢 Low
PhysicsLayers.Tests.asmref (added)	References an in-repo assembly by GUID (da80994a…) — test-only. No precompiled/external assembly reference.	🟢 Low
DynamicsManager.asset, TagManager.asset	Project-settings (new SDKAvatarHit layer + collision matrix). Feature config, no executable surface.	🟢 Low

No .dll/.so/.dylib/.bundle, no install/build hooks, no assembly-visibility escalation.

3. Prompt-file changes — 🟢 PASS

.claude/agents/dcl-sdk-feature-implementation/{dcl-sdk-specialist,dcl-test-scene-specialist}.md are Claude Code subagent definitions — not under .github/workflows/ or .github/prompts/, so they never execute with workflow secrets (W.1–W.10 don't apply).

• dcl-sdk-specialist.md (+11): adds a ColliderLayer mask semantics reference section — pure domain documentation (mask qualification rules, SDKAvatarHit routing). No tool/allowlist escalation, no network/filesystem directives.
• dcl-test-scene-specialist.md (+43/-9): adds a {x},{y}-{scene-name} folder-naming convention and a completion gate. Shell snippets (cp -r, ls, grep, mv, npm run build/check-parcels) are scoped to local test-scene authoring — no destructive GitHub ops, no secret reads, no exfil primitives, no untrusted-input interpolation.

No prompt-injection or privilege-escalation surface.

---

Verdict

No dependency, lockfile, manifest, asmdef, or native-binary surface relative to origin/dev; the deleted .meta is an orphaned no-binary file; the prompt-file changes are benign subagent documentation outside the secret-bearing workflow surface. No HIGH or MEDIUM findings.

DEPENDENCY_REVIEW: PASS
  • feat/collision-layer-main-player @ 4968f764