> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/trigger-areas.md).

# Áreas de trigger

Aprende cómo usar áreas de trigger en tu escena

Las áreas de trigger te permiten reaccionar al evento de que un jugador entre o salga de un área, o de que cualquier otra entidad entre o salga de un área. Son una herramienta fundamental para crear escenas interactivas. Úsalas para cosas como abrir una puerta cuando el jugador se acerca, o para sumar un punto cuando una pelota entra en una portería.

## Usando áreas de trigger

Para usar áreas de trigger necesitas añadir un `TriggerArea` componente a una entidad, luego usar un `triggerAreaEventsSystem` para reaccionar a los eventos.

```ts
import { engine, Transform, TriggerArea, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

// crear entidad
const triggerEntity = engine.addEntity()

// establecer Transform
Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8)
  })

// Área de trigger
TriggerArea.setBox(triggerEntity)

// Evento cuando se activa el área de trigger
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  if (result.trigger?.entity !== engine.PlayerEntity) return;
  console.log('¡El jugador entró en el área de trigger!')
})
```

De forma predeterminada, el `TriggerArea` componente reacciona al evento de *cualquier* jugador que entra en el área. El código anterior añade `if (result.trigger?.entity !== engine.PlayerEntity) return` para comprobar que la entidad que causó el evento es el jugador actual, y no el avatar de otra persona

## Formas de área de trigger

Las áreas de trigger pueden ser una caja o una esfera.

```ts
import { engine, Transform, TriggerArea } from '@dcl/sdk/ecs'

// Caja
TriggerArea.setBox(triggerEntity)

// Esfera
TriggerArea.setSphere(triggerEntity)
```

{% hint style="info" %}
**💡 Consejo**: La esfera es la forma más fácil de calcular para el engine, ya que se logra comprobando la distancia desde el centro de la esfera. Si tienes dudas, usa una esfera.
{% endhint %}

Para alterar el tamaño del área de trigger, puedes usar el `escala` propiedad del `Transform` componente en la entidad que contiene el `TriggerArea`.

```ts
import { engine, Transform, TriggerArea } from '@dcl/sdk/ecs'

const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

Transform.create(triggerEntity, {
  scale: Vector3.create(4, 2, 4),
})
```

### Depuración

Para depurar tu escena y ver el área cubierta por el área de trigger, puedes añadir un `MeshRenderer` componente a la entidad con el área de trigger, y establecer la forma en la que quieres depurar. Las dimensiones del mesh predeterminado coincidirán con las dimensiones del área de trigger.

```ts
import { engine, Transform, TriggerArea } from '@dcl/sdk/ecs'

const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

MeshRenderer.setBox(triggerEntity)

Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})
```

## Eventos del área de trigger

Puedes usar la `triggerAreaEventsSystem` para reaccionar a los distintos eventos de un área de trigger:

* `onTriggerEnter`: Se activa cuando una entidad entra en el área de trigger.
* `onTriggerExit`: Se activa cuando una entidad sale del área de trigger.
* `onTriggerStay`: Se activa mientras una entidad está en el área de trigger, en cada frame.

```ts
import { engine, Transform, TriggerArea, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

// Al entrar
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('¡El jugador entró en el área de trigger!')
})

// Al salir
triggerAreaEventsSystem.onTriggerExit(triggerEntity, function(result) {
  console.log('¡El jugador salió del área de trigger!')
})

// Mientras permanece
triggerAreaEventsSystem.onTriggerStay(triggerEntity, function(result) {
  console.log('¡El jugador está en el área de trigger!')
})
```

## Respuestas a eventos de trigger

Cuando se activa un evento de área de trigger, puedes usar el `result` parámetro para obtener información tanto de la entidad que fue activada como de la entidad que activó el evento.

Las siguientes propiedades están disponibles en el `result` parámetro:

* `triggeredEntity`: El ID de la entidad que fue activada (esta es la entidad que posee el área de trigger)
* `triggeredEntityPosition`: La posición de la entidad que fue activada
* `triggeredEntityRotation`: La rotación de la entidad que fue activada
* `eventType`: El tipo de evento de trigger (ENTER, EXIT, STAY)
* `marca de tiempo`: La marca de tiempo del evento de trigger
* `trigger`: Un objeto con los siguientes campos:
  * `entidad`: El ID de la entidad que activó el trigger (la entidad que entró en el área de trigger)
  * `layers`: Las capas de colisión de la entidad que activó el trigger
  * `posición`: La posición de la entidad que activó el trigger
  * `rotación`: La rotación de la entidad que activó el trigger
  * `escala`: La escala de la entidad que activó el trigger

{% hint style="warning" %}
**Confusión común**: a pesar de su nombre, `result.triggeredEntity` no **no** se refiere a la entidad que activó el evento. Estos dos campos se confunden fácilmente:

* `result.trigger?.entity`: la entidad que entró en el área de trigger. Esto suele ser lo que quieres comprobar, por ejemplo para identificar qué jugador u objeto entró.
* `result.triggeredEntity`: la entidad que posee el `TriggerArea` componente (la zona de trigger en sí, no la entidad que entró en ella).

Usa `result.trigger?.entity` cuando necesitas identificar la entidad que entra.
{% endhint %}

```ts
import { engine, Transform, TriggerArea, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

// Entidad con el área de trigger
const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})

// Al entrar
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('¡Una entidad entró en el área de trigger!', result.triggeredEntity)
  console.log('Posición de la entidad activada: ', result.triggeredEntityPosition)
  console.log('Rotación de la entidad activada: ', result.triggeredEntityRotation)
  console.log('Tipo de evento: ', result.eventType)
  console.log('Marca de tiempo: ', result.timestamp)
  console.log('Entidad del trigger: ', result.trigger.entity)
  console.log('Capas del trigger: ', result.trigger.layers)
  console.log('Posición del trigger: ', result.trigger.position)
  console.log('Rotación del trigger: ', result.trigger.rotation)
  console.log('Escala del trigger: ', result.trigger.scale)
})
```

## Detectar jugadores que entran en un área

El uso más común de las áreas de trigger es reaccionar a los jugadores que entran o salen. Dos capas de colisión detectan avatares, y cuál usar depende de a quién deba reaccionar la escena:

* `ColliderLayer.CL_MAIN_PLAYER`: Detecta **solo al jugador que usa la máquina local**. Usa esto cuando la respuesta esté pensada solo para ese jugador, por ejemplo para teletransportarlo, reproducirle un sonido o hacer seguimiento de su progreso en una misión. Esta también es la opción más barata en términos de rendimiento.
* `ColliderLayer.CL_PLAYER`: Detecta **todos los avatares**, tanto el jugador local como cualquier otro jugador que se esté renderizando en la escena. Usa esto cuando importe que cualquiera entre, por ejemplo una puerta que se abre cuando alguien se acerca, o contar cuántas personas hay en una habitación. Esta es la capa predeterminada si no se especifica ninguna.

El siguiente ejemplo reacciona solo al jugador local:

```ts
import { engine, Transform, TriggerArea, ColliderLayer, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

// crear entidad
const triggerEntity = engine.addEntity()

// establecer Transform
Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})

// Área de trigger que solo detecta al jugador local
TriggerArea.setBox(triggerEntity, ColliderLayer.CL_MAIN_PLAYER)

// Evento cuando se activa el área de trigger
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function (result) {
  console.log('¡Has entrado en el área de trigger!')
})
```

Al usar `CL_PLAYER`, todos los avatares activan el área de trigger. Para saber si el avatar que la activó es el jugador local, compara la entidad del resultado con `engine.PlayerEntity`:

```ts
import { engine, Transform, TriggerArea, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

// crear entidad
const triggerEntity = engine.addEntity()

// establecer Transform
Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})

// Área de trigger, usando la capa CL_PLAYER predeterminada
TriggerArea.setBox(triggerEntity)

// Evento cuando se activa el área de trigger
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function (result) {
  if (result.trigger?.entity === engine.PlayerEntity) {
    console.log('¡Has entrado en el área de trigger!')
  } else {
    console.log('¡Otro jugador entró en el área de trigger!')
  }
})
```

En la mayoría de los casos, en lugar de intentar detectar a todos los jugadores, el enfoque ideal es detectar solo al jugador actual (mediante `CL_MAIN_PLAYER`) y luego sincronizar los efectos de este trigger entre todos los jugadores. Por ejemplo, una puerta corredera se abre solo para tu avatar, pero luego el estado abierto de esa puerta se comparte con todos los demás jugadores.

{% hint style="info" %}
**💡 Consejo**: Las áreas de trigger cuya máscara solo incluye capas de avatar (`CL_PLAYER`, `CL_MAIN_PLAYER`, o ambas) están optimizadas: el engine las coloca en una capa física solo para avatares, por lo que las superposiciones con cualquier cosa que no sea un avatar son descartadas por el physics engine antes de llegar al código de tu escena. Un área de trigger con una máscara exactamente igual a `CL_MAIN_PLAYER` está optimizada aún más: corta de raíz cualquier superposición con colliders que no sean del jugador local antes de llegar al handler, así que detectar solo al jugador local es prácticamente gratis.
{% endhint %}

## Capas del área de trigger

Usa el segundo argumento opcional del `TriggerArea` componente para establecer las capas que activarán el área de trigger. De forma predeterminada, el área de trigger se activa solo por la capa `ColliderLayer.CL_PLAYER`, consulta [Detectar jugadores que entran en un área](#detect-players-entering-an-area).

Puedes cambiar la capa de colisión para detectar cualquier otra entidad pasándola como segundo argumento del `TriggerArea` componente.

```ts
import { engine, Transform, TriggerArea, MeshCollider, ColliderLayer, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

// Área de trigger
const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity, ColliderLayer.CL_CUSTOM1)

Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})

// Entidad que activará el área de trigger
const movingEntity = engine.addEntity()

Transform.create(movingEntity, {
  position: Vector3.create(8, 0, 8),
})

MeshCollider.setBox(movingEntity, ColliderLayer.CL_CUSTOM1)
```

Los valores permitidos son los mismos que los del `MeshCollider` componente. Consulta [capas de colisión](/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/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`
* `ColliderLayer.CL_NONE`

{% hint style="info" %}
**💡 Consejo**: Las capas `CL_CUSTOM1` hasta `CL_CUSTOM8` no tienen ningún comportamiento especial por sí solas, puedes usarlas para lo que mejor se adapte a tu escena.
{% endhint %}

También puedes configurar un área de trigger para detectar varias capas a la vez.

```ts
import { engine, Transform, TriggerArea, ColliderLayer, triggerAreaEventsSystem } from '@dcl/sdk/ecs'

const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity, ColliderLayer.CL_CUSTOM1 | ColliderLayer.CL_CUSTOM2)

Transform.create(triggerEntity, {
  position: Vector3.create(8, 0, 8),
})
```

Esto activará el área de trigger cuando cualquier entidad con las capas `CL_CUSTOM1` o `CL_CUSTOM2` entre en el área de trigger.

{% hint style="info" %}
**💡 Consejo**: Para ver un ejemplo funcional que usa `TriggerArea` de extremo a extremo, consulta la [`75,-9-trigger-areas`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/75,-9-trigger-areas) escena de prueba, que cubre el contrato de wire ENTER/EXIT y la síntesis por tick del SDK, áreas rotadas, activadores en movimiento en capas de collider personalizadas y áreas adjuntas a entidades en caída. Para ver cómo se comportan las propias capas de collider, consulta `onTriggerStay` sintetización [`5,5-collider-layers`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/5,5-collider-layers).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/fundamentos-del-contenido-3d/trigger-areas.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.