chore: update collision layer docs

creator-esp/scene-editor/interactivity/trigger-area.md

@@ -14,7 +14,7 @@ Para activar una acción cuando el jugador camina dentro o fuera de un área, us
 
 El cubo naranja que ves mientras editas tu escena solo es visible en el Scene Editor, se vuelve invisible al ejecutar un preview de la escena. Puedes ajustar y escalar fácilmente el cubo naranja para cubrir exactamente el área que necesitas.
 
-Si alguna parte del cuerpo del jugador se superpone con este cubo naranja, se llamará al evento asignado.
+Si alguna parte del cuerpo de un avatar — el jugador local o cualquier otro jugador renderizado en la escena — se superpone con este cubo naranja, se llamará al evento asignado.
 
 Usa los tipos de trigger **On Player Enters Area** y **On Player Leaves Area** en el componente **Triggers** del ítem. Las acciones en estos eventos de trigger se activan cada vez que el jugador entra o sale del área.
 
@@ -39,3 +39,7 @@ Múltiples trigger areas pueden superponerse, y no se afectan entre sí.
 
 El tamaño del área activable no se relaciona con la forma visible del ítem o sus colliders, siempre es un cubo de 1m en cada lado, afectado por la escala del ítem.
 {% endhint %}
+
+{% hint style="info" %}
+**💡 Tip**: Los trigger areas en el Scene Editor se activan con cualquier avatar — el jugador local y cualquier otro jugador renderizado cerca. Si necesitas reaccionar solo al jugador local e ignorar a los demás avatares, pasa a código y usa el [componente TriggerArea de SDK7](../../sdk7/3d-essentials/trigger-areas.md) con la capa de colisión `CL_MAIN_PLAYER`.
+{% endhint %}

creator-esp/sdk7/3d-essentials/colliders.md

@@ -141,11 +141,17 @@ La escena puede manejar capas de colisión separadas, que tienen diferentes comp
 
 Puedes configurar un componente `MeshCollider` o el componente `GltfContainer` para responder solo a un tipo de interacción, o a varias de ellas, o ninguna. Para hacer esto, en el `MeshCollider` establece la propiedad `collisionMask`, y en `GltfContainer` establece las propiedades `visibleMeshesCollisionMask` o `invisibleMeshesCollisionMask` a uno o varios de los siguientes valores:
 
-* `ColliderLayer.CL_PHYSICS`: Solo bloquea el movimiento del jugador (y no afecta eventos de puntero)
-* `ColliderLayer.CL_POINTER`: Responde solo a eventos de puntero (y no bloquea el movimiento del jugador)
-* `ColliderLayer.CL_CUSTOM1` hasta `CL_CUSTOM8`: Se pueden usar junto con raycasts, para que un rayo solo detecte colisiones con una capa específica.
+* `ColliderLayer.CL_PHYSICS`: Bloquea el movimiento del jugador (paredes, suelos, plataformas). No afecta eventos de puntero.
+* `ColliderLayer.CL_POINTER`: Responde solo a eventos de puntero. No bloquea el movimiento del jugador.
+* `ColliderLayer.CL_PLAYER`: Marca el collider como un "marcador de avatar". Los raycasts y trigger areas que apunten a `CL_PLAYER` lo detectarán, pero la cápsula del jugador lo atraviesa (no hay bloqueo físico). En meshes de escena es útil para señalar un mesh como "objetivo tipo avatar" solo para detección.
+* `ColliderLayer.CL_MAIN_PLAYER`: Igual que `CL_PLAYER`, pero orientado solo al jugador local. Los raycasts y trigger areas con `CL_MAIN_PLAYER` en su máscara lo detectan; los raycasts/triggers de avatares remotos no.
+* `ColliderLayer.CL_CUSTOM1` hasta `CL_CUSTOM8`: Se pueden usar junto con raycasts y trigger areas para detectar colisiones solo con capas personalizadas específicas.
 * `ColliderLayer.CL_NONE`: No responde a colisiones de ningún tipo.
 
+{% hint style="info" %}
+**💡 Tip**: `CL_PLAYER` y `CL_MAIN_PLAYER` en un `MeshCollider` / `GltfContainer` son capas **solo de detección** — la cápsula del jugador las atraviesa. Si quieres que el mesh sea detectable como avatar Y además bloquee físicamente al jugador, combina la capa de avatar con `CL_PHYSICS` (por ejemplo `CL_PHYSICS | CL_MAIN_PLAYER`).
+{% endhint %}
+
 {% hint style="warning" %}
 **📔 Nota**: Para deshabilitar colisiones de un componente `MeshCollider`, elimina el componente. No establezcas la capa de colisión en `ColliderLayer.CL_NONE`. Hay un problema conocido con el componente `MeshCollider`. En lugar de deshabilitar todas las colisiones, hace que este valor sea equivalente al predeterminado (`ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER`).
 {% endhint %}

creator-esp/sdk7/3d-essentials/trigger-areas.md

@@ -173,7 +173,12 @@ triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
 
 Usa el segundo argumento opcional del componente `TriggerArea` para establecer las capas que activarán el área de activación.
 
-Por defecto, el área de activación se activa solo por el jugador, a través de la capa `ColliderLayer.CL_PLAYER`. Puedes cambiar esto a cualquier otra capa de colisión pasándola como segundo argumento del componente `TriggerArea`.
+Por defecto, el área de activación se activa solo por la capa `ColliderLayer.CL_PLAYER`. Esta capa incluye a todos los jugadores — no solo al jugador local sino también a cualquier otro avatar que esté siendo renderizado en la escena. Si quieres detectar solo al jugador local y no a los demás, tienes dos opciones:
+
+* Usar la capa `ColliderLayer.CL_MAIN_PLAYER` en su lugar, que solo coincide con el jugador local.
+* O mantener `CL_PLAYER` y agregar `if (result.trigger?.entity !== engine.PlayerEntity) return` dentro del callback.
+
+También puedes cambiar a cualquier otra capa de colisión pasándola como segundo argumento del componente `TriggerArea`.
 
 ```ts
 import { engine, Transform, TriggerArea, MeshCollider, triggerAreaEventsSystem } from '@dcl/sdk/ecs'
@@ -199,6 +204,8 @@ MeshCollider.setBox(movingEntity, ColliderLayer.CL_CUSTOM1)
 
 Los valores permitidos son los mismos que los del componente `MeshCollider`. Consulta [Capas de colisión](colliders.md#Collision-layers) para más detalles.
 
+* `ColliderLayer.CL_PLAYER`: cualquier avatar (local + remoto)
+* `ColliderLayer.CL_MAIN_PLAYER`: solo el jugador local
 * `ColliderLayer.CL_PHYSICS`
 * `ColliderLayer.CL_POINTER`
 * `ColliderLayer.CL_CUSTOM1` hasta `CL_CUSTOM8`
@@ -208,6 +215,10 @@ Los valores permitidos son los mismos que los del componente `MeshCollider`. Con
 **💡 Consejo**: Las capas `CL_CUSTOM1` hasta `CL_CUSTOM8` no tienen ningún comportamiento especial por sí mismas, puedes usarlas para lo que mejor se adapte a tu escena.
 {% endhint %}
 
+{% hint style="info" %}
+**💡 Consejo**: Un trigger area con máscara exactamente igual a `CL_MAIN_PLAYER` está optimizado: el trigger descarta cualquier solapamiento con colliders que no sean del jugador local antes de llegar al handler, así que detectar solo al jugador local es esencialmente gratis.
+{% endhint %}
+
 También puedes configurar un área de activación para detectar múltiples capas a la vez.
 
 ```ts

creator-esp/sdk7/interactivity/raycasting.md

@@ -209,9 +209,9 @@ console.log(transform.position)
 
 ## Capas de colisión
 
-Es una buena práctica solo verificar colisiones contra entidades que sean relevantes, para hacer la escena más eficiente. El campo `collisionMask` permite listar solo capas de colisión específicas, que pueden incluir la capa de physics (que bloquea el movimiento del jugador), la capa de puntero (que se usa para eventos de puntero), y 8 capas personalizadas que puedes asignar libremente según tus necesidades. Consulta [capas de colisión](../3d-essentials/colliders.md#collision-layers). Por defecto, todas las capas se detectan.
+Es una buena práctica solo verificar colisiones contra entidades que sean relevantes, para hacer la escena más eficiente. El campo `collisionMask` permite listar solo capas de colisión específicas — la capa de physics (paredes y suelos), la capa de puntero (eventos de puntero), las capas de jugador (avatares), o 8 capas personalizadas que puedes asignar libremente. Consulta [capas de colisión](../3d-essentials/colliders.md#collision-layers).
 
-Por defecto, el campo `collisionMask` está configurado para responder tanto a las capas `ColliderLayer.CL_POINTER` como `ColliderLayer.CL_PHYSICS`. Puedes cambiar este valor para listar solo una de esas, o para incluir capas personalizadas. Usa el separador `|` para listar múltiples opciones.
+Por defecto, el campo `collisionMask` está configurado en `ColliderLayer.CL_PHYSICS`. Puedes cambiar este valor para listar otras capas, o combinar varias con el separador `|`.
 
 ```ts
 raycastSystem.registerLocalDirectionRaycast(
@@ -357,7 +357,51 @@ engine.addSystem((deltaTime) => {
 
 ## Colisionar con el jugador
 
-No puedes impactar directamente el avatar del jugador o los de otros jugadores con un rayo, pero lo que puedes hacer como solución alternativa es posicionar una entidad invisible ocupando el mismo espacio que un jugador usando el [componente AvatarAttach](../3d-essentials/entity-positioning.md#attach-an-entity-to-an-avatar), y verificar colisiones con ese cubo.
+Puedes detectar avatares directamente con raycasts incluyendo una de las capas de colisión de avatar en la máscara:
+
+* `ColliderLayer.CL_PLAYER`: detecta cualquier avatar — el jugador local Y cualquier otro jugador renderizado en la escena.
+* `ColliderLayer.CL_MAIN_PLAYER`: detecta solo al jugador local (main).
+
+Ambas capas pueden combinarse o usarse de forma independiente. La máscara `collisionMask` predeterminada para un raycast es `CL_PHYSICS`, que NO impacta avatares — debes optar por una o ambas capas de avatar explícitamente.
+
+```ts
+// Impactar solo al jugador local (ignorar otros avatares)
+raycastSystem.registerLocalDirectionRaycast(
+  {
+    entity: myEntity,
+    opts: {
+      direction: Vector3.Forward(),
+      collisionMask: ColliderLayer.CL_MAIN_PLAYER,
+    },
+  },
+  (raycastResult) => {
+    if (raycastResult.hits.length > 0) {
+      console.log('Impacto al jugador local')
+    }
+  }
+)
+
+// Impactar cualquier avatar (local + remoto)
+raycastSystem.registerLocalDirectionRaycast(
+  {
+    entity: myEntity,
+    opts: {
+      direction: Vector3.Forward(),
+      collisionMask: ColliderLayer.CL_PLAYER,
+    },
+  },
+  (raycastResult) => {
+    // raycastResult.hits[i].entityId es 0 para impactos contra avatares remotos (no tienen entity id en la escena local)
+    console.log(raycastResult.hits)
+  }
+)
+```
+
+Cuando un raycast impacta al jugador local, `hit.entityId` es `engine.PlayerEntity`. Los impactos contra avatares remotos no llevan un entity id de la escena local (el campo es `0`) ya que el jugador remoto no es una entidad en el mundo de tu escena — pero el impacto se reporta igual con su `position`, `length`, `normalHit`, y demás datos geométricos.
+
+{% hint style="info" %}
+**💡 Tip**: Para detectar solo a **otros** jugadores (excluyendo al jugador local), usa `CL_PLAYER` y filtra `hit.entityId !== engine.PlayerEntity` dentro del callback.
+{% endhint %}
 
 ## Raycasts desde el jugador
 

creator/scene-editor/interactivity/trigger-area.md

@@ -10,7 +10,7 @@ To trigger an action when the player walks into or out of an area, use the Trigg
 
 The orange cube you see while editing your scene is only visible in the Scene Editor, it becomes invisible when running a preview of the scene. You can easily adjust and scale the orange cube to cover exactly the area you need.
 
-If any part of the player's body overlaps with this orange cube, the assigned event will be called.
+If any part of an avatar's body — the local player or any other player rendered in the scene — overlaps with this orange cube, the assigned event will be called.
 
 Use the **On Player Enters Area** and **On Player Leaves Area** trigger types on the item's **Triggers** component. The actions on these trigger events are activated every time that the player enters or leaves the area.
 
@@ -35,3 +35,7 @@ Multiple trigger areas can overlap, and don't affect each other.
 
 The size of the triggerable area doesn't relate to the item's visible shape or its colliders, it's always a cube of 1m on each side, affected by the scale of the item.
 {% endhint %}
+
+{% hint style="info" %}
+**💡 Tip**: Trigger areas in the Scene Editor fire for any avatar — the local player and any other players rendered nearby. If you need to react only to the local player and ignore other avatars, drop down to code and use the [SDK7 TriggerArea component](../../sdk7/3d-essentials/trigger-areas.md) with the `CL_MAIN_PLAYER` collision layer.
+{% endhint %}

creator/sdk7/3d-essentials/colliders.md

@@ -140,11 +140,17 @@ The scene can handle separate collision layers, that have different behaviors.
 
 You can configure a `MeshCollider` component or the `GltfContainer` component to only respond to one kind of interaction, or to several of them, or none. To do this, on the `MeshCollider` set the `collisionMask` property, and on `GltfContainer` set the `visibleMeshesCollisionMask` or `invisibleMeshesCollisionMask` properties to one or several of the following values:
 
-- `ColliderLayer.CL_PHYSICS`: Only blocks player movement (and doesn't affect pointer events)
-- `ColliderLayer.CL_POINTER`: Responds only to pointer events (and doesn't block the player movement)
-- `ColliderLayer.CL_CUSTOM1` through to `CL_CUSTOM8`: Can be used together with raycasts, so that a ray only detects collisions with one specific layer.
+- `ColliderLayer.CL_PHYSICS`: Blocks player movement (scene walls, floors, platforms). Doesn't affect pointer events.
+- `ColliderLayer.CL_POINTER`: Responds only to pointer events. Doesn't block player movement.
+- `ColliderLayer.CL_PLAYER`: Tags the collider as an avatar marker. Raycasts and trigger areas that target `CL_PLAYER` will detect it, but the player capsule walks straight through it (no physical block). On scene meshes, this is useful to flag a mesh as "an avatar-like target" for detection only.
+- `ColliderLayer.CL_MAIN_PLAYER`: Like `CL_PLAYER`, but targeted at the local player only. Raycasts and trigger areas with `CL_MAIN_PLAYER` in their mask detect it; remote-avatar raycasts/triggers don't.
+- `ColliderLayer.CL_CUSTOM1` through to `CL_CUSTOM8`: Can be used together with raycasts and trigger areas to detect collisions only with specific custom layers.
 - `ColliderLayer.CL_NONE`: Doesn't respond to collisions of any kind.
 
+{% hint style="info" %}
+**💡 Tip**: `CL_PLAYER` and `CL_MAIN_PLAYER` on a `MeshCollider` / `GltfContainer` are **detection-only** layers — the player capsule passes through them. If you want the mesh to BOTH be detectable as an avatar AND physically block the player, combine the avatar layer with `CL_PHYSICS` (e.g. `CL_PHYSICS | CL_MAIN_PLAYER`).
+{% endhint %}
+
 {% hint style="warning" %}
 **📔 Note**: To disable collisions form a `MeshCollider` component, delete the component. Do not set the collision layer to `ColliderLayer.CL_NONE`. There's a known issue with the `MeshCollider` component. Instead of disabling all collisions, it makes this value equivalent to the default (`ColliderLayer.CL_PHYSICS | ColliderLayer.CL_POINTER`).
 {% endhint %}

creator/sdk7/3d-essentials/trigger-areas.md

@@ -173,7 +173,10 @@ triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
 
 Use the optional second argument of the `TriggerArea` component to set the layers that will activate the trigger area.
 
-By deault, the trigger area is activated only by the layer `ColliderLayer.CL_PLAYER`. This layer includes all players, not just the current player but also any other avatar that is being rendered in the scene. If you want to detect only the current player and not others, add the following check to the trigger function `if (result.trigger?.entity !== engine.PlayerEntity) return`.
+By default, the trigger area is activated only by the layer `ColliderLayer.CL_PLAYER`. This layer includes all players — not just the current player but also any other avatar that is being rendered in the scene. If you want to detect only the current player and not others, you have two options:
+
+- Use the `ColliderLayer.CL_MAIN_PLAYER` layer instead, which matches only the local player.
+- Or keep `CL_PLAYER` and add `if (result.trigger?.entity !== engine.PlayerEntity) return` inside the callback.
 
 ```ts
 import { engine, Transform, TriggerArea, triggerAreaEventsSystem } from '@dcl/sdk/ecs'
@@ -222,6 +225,8 @@ MeshCollider.setBox(movingEntity, ColliderLayer.CL_CUSTOM1)
 
 Allowed values are the same as the ones for the `MeshCollider` component. See [Collision layers](colliders.md#Collision-layers) for more details.
 
+* `ColliderLayer.CL_PLAYER`: any avatar (local + remote)
+* `ColliderLayer.CL_MAIN_PLAYER`: only the local player
 * `ColliderLayer.CL_PHYSICS`
 * `ColliderLayer.CL_POINTER`
 * `ColliderLayer.CL_CUSTOM1` through to `CL_CUSTOM8`
@@ -231,6 +236,10 @@ Allowed values are the same as the ones for the `MeshCollider` component. See [C
 **💡 Tip**: The layers `CL_CUSTOM1` through to `CL_CUSTOM8` don't have any special behavior on their own, you can use them for whatever suits your scene best.
 {% endhint %}
 
+{% hint style="info" %}
+**💡 Tip**: A trigger area with mask exactly equal to `CL_MAIN_PLAYER` is optimised: the trigger short-circuits any overlap with non-local-player colliders before reaching the handler, so detecting the local player only is essentially free.
+{% endhint %}
+
 You can also set up a trigger area to detect multiple layers at once.
 
 ```ts