# Áreas de trigger

As áreas de trigger permitem que você reaja ao evento de um player entrar ou sair de uma área, ou de qualquer outra entity entrar ou sair de uma área. Esta é uma ferramenta fundamental para criar scenes interativas. Use-as para coisas como abrir uma porta quando o player se aproxima, ou marcar um ponto quando uma bola entra em um gol.

## Usando áreas de trigger

Para usar áreas de trigger, você precisa adicionar um `TriggerArea` component a uma entity, depois use um `triggerAreaEventsSystem` para reagir aos eventos.

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

// criar entity
const triggerEntity = engine.addEntity()

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

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

// Evento quando a área de trigger é ativada
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  if (result.trigger?.entity !== engine.PlayerEntity) return;
  console.log('Player entrou na área de trigger!')
})
```

Por padrão, o `TriggerArea` component reage ao evento de *qualquer* player entrando na área. O código acima adiciona `if (result.trigger?.entity !== engine.PlayerEntity) return` para verificar se a entity que causou o evento é o player atual, e não o avatar de outra pessoa

## Formas da área de trigger

As áreas de trigger podem ser tanto um box quanto uma sphere.

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

// Box
TriggerArea.setBox(triggerEntity)

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

{% hint style="info" %}
**💡 Dica**: A sphere é a forma mais fácil de calcular para o engine, pois é obtida verificando a distância a partir do centro da sphere. Em caso de dúvida, use uma sphere.
{% endhint %}

Para alterar o tamanho da área de trigger, você pode usar o `scale` propriedade do `Transform` component na entity que contém o `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),
})
```

### Debugging

Para fazer debug da sua scene e ver a área coberta pela área de trigger, você pode adicionar um `MeshShape` component à entity com a área de trigger, e definir a shape para a que você deseja depurar. As dimensões da mesh padrão corresponderão às dimensões da á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 da área de trigger

Você pode usar o `triggerAreaEventsSystem` para reagir aos diferentes eventos de uma área de trigger:

* `onTriggerEnter`: Disparado quando uma entity entra na área de trigger.
* `onTriggerExit`: Disparado quando uma entity sai da área de trigger.
* `onTriggerStay`: Disparado enquanto uma entity está na área de trigger, a cada frame.

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

const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

// Na entrada
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('Player entrou na área de trigger!')
})

// Na saída
triggerAreaEventsSystem.onTriggerExit(triggerEntity, function(result) {
  console.log('Player saiu da área de trigger!')
})

// Enquanto permanecer
triggerAreaEventsSystem.onTriggerStay(triggerEntity, function(result) {
  console.log('Player está na área de trigger!')
})
```

## Respostas aos eventos de trigger

Quando um evento de área de trigger é disparado, você pode usar o `result` parâmetro para obter informações tanto sobre a entity que foi disparada quanto sobre a entity que disparou o evento.

As seguintes propriedades estão disponíveis no `result` parâmetro:

* `triggeredEntity`: O ID da entity que foi disparada (esta é a entity que possui a área de trigger)
* `triggeredEntityPosition`: A posição da entity que foi disparada
* `triggeredEntityRotation`: A rotação da entity que foi disparada
* `eventType`: O tipo de evento de trigger (ENTER, EXIT, STAY)
* `timestamp`: O timestamp do evento de trigger
* `trigger`: Um objeto com os seguintes campos:
  * `entity`: O ID da entity que disparou o trigger (a entity que entrou na área de trigger)
  * `layer`: A camada de colisão da entity que disparou o trigger
  * `position`: A posição da entity que disparou o trigger
  * `rotation`: A rotação da entity que disparou o trigger
  * `scale`: A escala da entity que disparou o trigger

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

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

TriggerArea.setBox(triggerEntity)

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

// Entity que vai disparar a área de trigger
const triggerEntity = engine.addEntity()

const triggeredEntity = engine.addEntity()

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

// Na entrada
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('Uma entity entrou na área de trigger!', result.triggeredEntity)
  console.log('Posição da entity disparada: ', result.triggeredEntityPosition)
  console.log('Rotação da entity disparada: ', result.triggeredEntityRotation)
  console.log('Tipo de evento: ', result.eventType)
  console.log('Timestamp: ', result.timestamp)
  console.log('Trigger entity: ', result.trigger.entity)
  console.log('Camada do trigger: ', result.trigger.layer)
  console.log('Posição do trigger: ', result.trigger.position)
  console.log('Rotação do trigger: ', result.trigger.rotation)
  console.log('Escala do trigger: ', result.trigger.scale)
})
```

## Camadas da área de trigger

Use o segundo argumento opcional do `TriggerArea` component para definir as layers que ativarão a área de trigger.

Por padrão, a área de trigger é ativada apenas pela layer `ColliderLayer.CL_PLAYER`. Essa layer inclui todos os players, não apenas o player atual, mas também qualquer outro avatar que esteja sendo renderizado na scene. Se você quiser detectar apenas o player atual e não os outros, adicione a seguinte verificação à função de trigger `if (result.trigger?.entity !== engine.PlayerEntity) return`.

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

// criar entity
const triggerEntity = engine.addEntity()

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

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

// Evento quando a área de trigger é ativada
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  if (result.trigger?.entity !== engine.PlayerEntity) return;
  console.log('Player entrou na área de trigger!')
})
```

Você também pode alterar a collision layer para detectar qualquer outra entity passando-a como o segundo argumento do `TriggerArea` component.

```ts
import { engine, Transform, TriggerArea, MeshCollider, 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),
})

// Entity que ativará a área de trigger
const movingEntity = engine.addEntity()

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

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

Os valores permitidos são os mesmos que os do `MeshCollider` component. Veja [Collision layers](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/colliders.md#Collision-layers) para mais detalhes.

* `ColliderLayer.CL_PHYSICS`
* `ColliderLayer.CL_POINTER`
* `ColliderLayer.CL_CUSTOM1` até `CL_CUSTOM8`
* `ColliderLayer.CL_NONE`

{% hint style="info" %}
**💡 Dica**: As layers `CL_CUSTOM1` até `CL_CUSTOM8` não têm nenhum comportamento especial por si só; você pode usá-las para o que melhor se adequar à sua scene.
{% endhint %}

Você também pode configurar uma área de trigger para detectar várias layers ao mesmo tempo.

```ts
import { engine, Transform, TriggerArea, 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),
})
```

Isso ativará a área de trigger quando qualquer entity com as layers `CL_CUSTOM1` ou `CL_CUSTOM2` entrar na área de trigger.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/trigger-areas.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.