> 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-pt/scenes-sdk7/fundamentos-de-conteudo-3d/trigger-areas.md).

# Áreas de Trigger

Saiba como usar áreas de trigger na sua scene

As áreas de trigger permitem-lhe reagir ao evento de um jogador entrar ou sair de uma área, ou de qualquer outra entidade entrar ou sair de uma área. Esta é uma ferramenta fundamental para criar cenas interativas. Use-as para coisas como abrir uma porta quando o jogador se aproxima, ou marcar um ponto quando uma bola entra numa baliza.

## Usar áreas de trigger

Para usar áreas de trigger, precisa de adicionar um `TriggerArea` componente a uma entidade, e depois usar um `triggerAreaEventsSystem` para reagir aos eventos.

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

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

// definir 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('O jogador entrou na área de trigger!')
})
```

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

## Formas da área de trigger

As áreas de trigger podem ser um cubo ou uma esfera.

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

// Cubo
TriggerArea.setBox(triggerEntity)

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

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

Para alterar o tamanho da área de trigger, pode usar o `scale` property do `Transform` componente na entidade que contém a `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),
})
```

### Depuração

Para depurar a sua cena e ver a área coberta pela área de trigger, pode adicionar um `MeshRenderer` componente à entidade com a área de trigger, e definir a forma para aquela que quer depurar. As dimensões da mesh predefinida 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 entidade entra na área de trigger.
* `onTriggerExit`: Disparado quando uma entidade sai da área de trigger.
* `onTriggerStay`: Disparado enquanto uma entidade 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)

// Ao entrar
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('O jogador entrou na área de trigger!')
})

// Ao sair
triggerAreaEventsSystem.onTriggerExit(triggerEntity, function(result) {
  console.log('O jogador saiu da área de trigger!')
})

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

## Respostas ao evento de trigger

Quando um evento de área de trigger é disparado, pode usar o `result` parâmetro para obter informações sobre a entidade que foi acionada e sobre a entidade que acionou o evento.

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

* `triggeredEntity`: O ID da entidade que foi acionada (esta é a entidade que possui a área de trigger)
* `triggeredEntityPosition`: A posição da entidade que foi acionada
* `triggeredEntityRotation`: A rotação da entidade que foi acionada
* `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 entidade que acionou o trigger (a entidade que entrou na área de trigger)
  * `layers`: As camadas de colisão da entidade que acionou o trigger
  * `position`: A posição da entidade que acionou o trigger
  * `rotation`: A rotação da entidade que acionou o trigger
  * `scale`: A escala da entidade que acionou o trigger

{% hint style="warning" %}
**Confusão comum**: apesar do nome, `result.triggeredEntity` não **não** refere-se à entidade que acionou o evento. Estes dois campos são facilmente confundidos:

* `result.trigger?.entity`: a entidade que entrou na área de trigger. Isto é normalmente o que quer verificar, por exemplo para identificar qual jogador ou objeto entrou.
* `result.triggeredEntity`: a entidade que possui o `TriggerArea` componente (a própria zona de trigger, não a entidade que entrou nela).

Use `result.trigger?.entity` quando precisar de identificar a entidade que entrou.
{% endhint %}

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

// Entidade com a área de trigger
const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

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

// Ao entrar
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('Uma entidade entrou na área de trigger!', result.triggeredEntity)
  console.log('Posição da entidade acionada: ', result.triggeredEntityPosition)
  console.log('Rotação da entidade acionada: ', result.triggeredEntityRotation)
  console.log('Tipo de evento: ', result.eventType)
  console.log('Timestamp: ', result.timestamp)
  console.log('Entidade do trigger: ', result.trigger.entity)
  console.log('Camadas do trigger: ', result.trigger.layers)
  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)
})
```

## Detetar jogadores a entrar numa área

A utilização mais comum das áreas de trigger é reagir a jogadores a entrar ou a sair. Duas camadas de colisão detetam avatares, e qual deve usar depende de quem a cena deve reagir:

* `ColliderLayer.CL_MAIN_PLAYER`: Deteta **apenas o jogador na máquina local**. Use isto quando a resposta se destina apenas a esse jogador, por exemplo para o teletransportar, reproduzir um som para ele, ou acompanhar o progresso dele numa missão. Esta é também a opção mais barata em termos de desempenho.
* `ColliderLayer.CL_PLAYER`: Deteta **todos os avatares**, tanto o jogador local como quaisquer outros jogadores que estejam a ser renderizados na cena. Use isto quando a entrada de qualquer pessoa for importante, por exemplo uma porta que se abre quando alguém se aproxima, ou contar quantas pessoas estão numa sala. Esta é a camada predefinida se nenhuma for especificada.

O exemplo seguinte reage apenas ao jogador local:

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

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

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

// Área de trigger que deteta apenas o jogador local
TriggerArea.setBox(triggerEntity, ColliderLayer.CL_MAIN_PLAYER)

// Evento quando a área de trigger é ativada
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function (result) {
  console.log('Entrou na área de trigger!')
})
```

Ao usar `CL_PLAYER`, todos os avatares ativam a área de trigger. Para saber se o avatar que a acionou é o jogador local, compare a entidade no resultado com `engine.PlayerEntity`:

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

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

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

// Área de trigger, usando a camada CL_PLAYER predefinida
TriggerArea.setBox(triggerEntity)

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

Na maioria dos casos, em vez de tentar detetar todos os jogadores, a abordagem ideal é detetar apenas o jogador atual (via `CL_MAIN_PLAYER`) e depois sincronizar os efeitos deste trigger entre todos os jogadores. Por exemplo, uma porta de correr abre apenas para o seu avatar, mas depois o estado aberto dessa porta é partilhado com todos os outros jogadores.

{% hint style="info" %}
**💡 Dica**: As áreas de trigger cuja máscara inclui apenas layers de avatar (`CL_PLAYER`, `CL_MAIN_PLAYER`, ou ambas) são otimizadas: o engine coloca-as numa physics layer apenas de avatares, pelo que sobreposições com qualquer coisa que não seja um avatar são descartadas pelo physics engine antes de chegarem ao código da sua cena. Uma área de trigger com uma máscara exatamente igual a `CL_MAIN_PLAYER` é ainda mais otimizada: corta antecipadamente qualquer sobreposição com colliders de jogadores não locais antes de chegar ao handler, pelo que detetar apenas o jogador local é, na prática, gratuito.
{% endhint %}

## Camadas da área de trigger

Use o segundo argumento opcional do `TriggerArea` componente para definir as layers que irão ativar a área de trigger. Por defeito, a área de trigger é ativada apenas pela layer `ColliderLayer.CL_PLAYER`, veja [Detetar jogadores a entrar numa área](#detect-players-entering-an-area).

Pode alterar a collision layer para detetar qualquer outra entidade, passando-a como o segundo argumento do `TriggerArea` component.

```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),
})

// Entidade que irá 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` componente. Veja [Collision layers](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md#Collision-layers) para mais detalhes.

* `ColliderLayer.CL_PLAYER`: qualquer avatar (local + remoto)
* `ColliderLayer.CL_MAIN_PLAYER`: apenas o jogador local
* `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ó, pode usá-las para o que melhor se adequar à sua cena.
{% endhint %}

Também pode configurar uma área de trigger para detetar várias layers ao mesmo tempo.

```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),
})
```

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

{% hint style="info" %}
**💡 Dica**: Para um exemplo funcional que testa `TriggerArea` de ponta a ponta, veja a [`75,-9-trigger-areas`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/75,-9-trigger-areas) cena de teste, que cobre o contrato wire de ENTER/EXIT e a síntese por tick do SDK, `onTriggerStay` síntese, áreas rodadas, triggerers em movimento em layers de collider personalizadas, e áreas anexadas a entidades em queda. Para ver como as próprias collider layers se comportam, veja [`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-pt/scenes-sdk7/fundamentos-de-conteudo-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.