> 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 ativação permitem reagir quando um jogador ou qualquer outra entidade entra ou sai de uma área. São uma ferramenta fundamental para criar cenas interativas. Use-as, por exemplo, para abrir uma porta quando o jogador se aproxima ou para marcar um ponto quando uma bola entra na baliza.

## Utilizar áreas de ativação

Para utilizar áreas de ativação, tem de adicionar um componente `TriggerArea` a uma entidade e, em seguida, utilizar um sistema `triggerAreaEventsSystem` para reagir aos eventos.

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

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

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

// Área de ativação
TriggerArea.setBox(triggerEntity)

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

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

## Formas das áreas de ativação

As áreas de ativação podem ter a forma de uma caixa ou de uma esfera.

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

// Caixa
TriggerArea.setBox(triggerEntity)

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

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

Para alterar o tamanho da área de ativação, pode utilizar a propriedade `scale` do componente `Transform` na entidade que contém o componente `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 cena e ver a área abrangida pela área de ativação, pode adicionar um componente `MeshRenderer` à entidade que contém a área de ativação e definir a forma para aquela que pretende depurar. As dimensões da Mesh predefinida corresponderão às dimensões da área de ativação.

```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 das áreas de ativação

Pode utilizar o sistema `triggerAreaEventsSystem` para reagir aos diferentes eventos de uma área de ativação:

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

```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('Player entered trigger area!')
})

// Ao sair
triggerAreaEventsSystem.onTriggerExit(triggerEntity, function(result) {
  console.log('Player exited trigger area!')
})

// Ao permanecer
triggerAreaEventsSystem.onTriggerStay(triggerEntity, function(result) {
  console.log('Player is in trigger area!')
})
```

## Responses de events de trigger

Quando um event de área de trigger é ativado, pode usar o parâmetro `result` para obter informações sobre a entity ativada e a entity que ativou o event.

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

* `triggeredEntity`: O ID da entity ativada (a entity à qual pertence a área de trigger)
* `triggeredEntityPosition`: A posição da entity ativada
* `triggeredEntityRotation`: A rotação da entity ativada
* `eventType`: O tipo de event de trigger (ENTER, EXIT, STAY)
* `timestamp`: O carimbo temporal do event de trigger
* `trigger`: Um objeto com os seguintes campos:
  * `entity`: O ID da entity que ativou o trigger (a entity que entrou na área de trigger)
  * `layers`: As layers de colisão da entity que ativou o trigger
  * `position`: A posição da entity que ativou o trigger
  * `rotation`: A rotação da entity que ativou o trigger
  * `scale`: A escala da entity que ativou o trigger

{% hint style="warning" %}
**Confusão frequente**: apesar do nome, `result.triggeredEntity` efetivamente **não** se refere à entity que ativou o event. É fácil confundir estes dois campos:

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

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

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

// Entidade com a zona de acionamento
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('An entity entered trigger area!', result.triggeredEntity)
  console.log('Triggered entity position: ', result.triggeredEntityPosition)
  console.log('Triggered entity rotation: ', result.triggeredEntityRotation)
  console.log('Event type: ', result.eventType)
  console.log('Timestamp: ', result.timestamp)
  console.log('Trigger entity: ', result.trigger.entity)
  console.log('Trigger layers: ', result.trigger.layers)
  console.log('Trigger position: ', result.trigger.position)
  console.log('Trigger rotation: ', result.trigger.rotation)
  console.log('Trigger scale: ', result.trigger.scale)
})
```

## Detetar jogadores que entram numa área

A utilização mais comum das zonas de acionamento é reagir à entrada ou saída de jogadores. Duas camadas de colisão detetam Avatars, e a escolha da camada depende de quem a cena deve detetar:

* `ColliderLayer.CL_MAIN_PLAYER`: deteta **apenas o jogador que está a utilizar a máquina local**. Use esta opção quando a resposta se destina apenas a esse jogador, por exemplo, para o teletransportar, reproduzir um som para ele ou acompanhar o seu progresso numa missão. Esta é também a opção mais económica em termos de desempenho.
* `ColliderLayer.CL_PLAYER`: deteta **todos os Avatars**, tanto o jogador local como quaisquer outros jogadores apresentados na cena. Use esta opção quando a entrada de qualquer pessoa for relevante, por exemplo, para uma porta que se abre quando alguém se aproxima ou para contar quantas pessoas estão numa sala. Esta é a camada predefinida, caso nenhuma seja especificada.

O exemplo seguinte reage apenas ao jogador local:

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

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

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

// Zona de acionamento que deteta apenas o jogador local
TriggerArea.setBox(triggerEntity, ColliderLayer.CL_MAIN_PLAYER)

// Evento quando a área de ativação é ativada
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function (result) {
  console.log('You entered the trigger area!')
})
```

Ao usar `CL_PLAYER`, todos os Avatars ativam a zona de acionamento. Para saber se o Avatar que a ativou é o jogador local, compare a entidade no resultado com `engine.PlayerEntity`:

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

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

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

// Zona de acionamento que usa a camada predefinida CL_PLAYER
TriggerArea.setBox(triggerEntity)

// Evento quando a área de ativação é ativada
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function (result) {
  if (result.trigger?.entity === engine.PlayerEntity) {
    console.log('You entered the trigger area!')
  } else {
    console.log('Another player entered the trigger area!')
  }
})
```

Na maioria dos casos, em vez de tentar detetar todos os jogadores, a abordagem ideal é detetar apenas o jogador atual (através de `CL_MAIN_PLAYER`) e, em seguida, sincronizar os efeitos deste acionamento entre todos os jogadores. Por exemplo, uma porta deslizante abre-se apenas para o seu Avatar, mas o estado aberto da porta é depois partilhado com todos os outros jogadores.

{% hint style="info" %}
**💡 Sugestão**: as zonas de acionamento cuja máscara inclui apenas camadas de Avatar (`CL_PLAYER`, `CL_MAIN_PLAYER`, ou ambas) são otimizadas: o Engine coloca-as numa camada de física exclusiva para Avatars, pelo que as sobreposições com qualquer elemento que não seja um Avatar são descartadas pelo Engine de física antes de chegarem ao código da cena. Uma zona de acionamento com uma máscara exatamente igual a `CL_MAIN_PLAYER` é ainda mais otimizada: ignora qualquer sobreposição com Colliders que não sejam do jogador local antes de chegar ao manipulador, pelo que detetar apenas o jogador local é praticamente gratuito.
{% endhint %}

## Camadas das zonas de acionamento

Utilize o segundo argumento opcional de `TriggerArea` para definir as camadas que ativarão a área de acionamento. Por predefinição, a área de acionamento só é ativada pela camada `ColliderLayer.CL_PLAYER`, consulte [Detetar jogadores que entram numa área](#detect-players-entering-an-area).

Pode alterar a camada de colisão para detetar qualquer outra entidade, passando-a como segundo argumento do componente `TriggerArea` .

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

// Área de ativação
const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity, ColliderLayer.CL_CUSTOM1)

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

// Entidade que ativará a área de acionamento
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 componente `MeshCollider` . Consulte [Camadas de colisão](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/colliders.md#collision-layers) para obter mais informações.

* `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" %}
**💡 Sugestão**: As camadas `CL_CUSTOM1` até `CL_CUSTOM8` não têm qualquer comportamento especial por si só; pode utilizá-las como preferir na sua cena.
{% endhint %}

Também pode configurar uma área de acionamento para detetar várias camadas 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 acionamento quando qualquer entidade com as camadas `CL_CUSTOM1` ou `CL_CUSTOM2` entrar na área de acionamento.

{% hint style="info" %}
**💡 Sugestão**: Para ver um exemplo funcional que testa o componente `TriggerArea` de ponta a ponta, consulte a [`75,-9-trigger-areas`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/75,-9-trigger-areas) cena de teste, que abrange o contrato de comunicação ENTER/EXIT e o `onTriggerStay` síntese, áreas rotacionadas, elementos que ativam gatilhos em movimento em camadas de collider personalizadas e áreas anexadas a entities em queda. Para ver como as próprias camadas de collider se comportam, consulte [`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.
