Áreas de Gatilho

Aprenda como usar trigger areas em sua cena

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

Usando áreas de trigger

Para usar áreas de trigger você precisa adicionar um TriggerArea componente a uma entity, então usar um triggerAreaEventsSystem para reagir aos eventos.

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

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

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

// Trigger area
TriggerArea.setBox(triggerEntity)

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

Formas de trigger area

Áreas de trigger podem ser uma caixa ou uma esfera.

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

// Caixa
TriggerArea.setBox(triggerEntity)

// Esfera
TriggerArea.setSphere(triggerEntity)

💡 Tip: A esfera é a forma mais fácil de calcular para o engine, pois é obtida verificando a distância a partir do centro da esfera. Em caso de dúvida, use uma esfera.

Para alterar o tamanho da trigger area, você pode usar o scale propriedade do Transform componente na entity que contém o TriggerArea.

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 sua cena e ver a área coberta pela trigger area, você pode adicionar um MeshShape componente à entity com a trigger area, e definir a shape para aquela que você quer depurar. As dimensões do mesh padrão irão corresponder às dimensões da trigger area.

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 trigger area

Você pode usar o triggerAreaEventsSystem para reagir aos diferentes eventos de uma trigger area:

• onTriggerEnter: Disparado quando uma entity entra na trigger area.

• onTriggerExit: Disparado quando uma entity sai da trigger area.

• onTriggerStay: Disparado enquanto uma entity está na trigger area, a cada frame.

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 entrou na área de trigger!')
})

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

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

Respostas a eventos de trigger

Quando um evento de trigger area é disparado, você pode usar o result parâmetro para obter informações tanto sobre a entity que foi triggerada quanto sobre a entity que acionou o evento.

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

• triggeredEntity: O ID da entity que foi triggerada (esta é a entity que possui a trigger area)

• triggeredEntityPosition: A posição da entity que foi triggerada

• triggeredEntityRotation: A rotação da entity que foi triggerada

• eventType: O tipo de evento de trigger (ENTER, EXIT, STAY)

• timestamp: O timestamp do evento de trigger

• trigger: Um objeto com os seguintes campos:

  • entidade: O ID da entity que acionou o trigger (a entity que entrou na trigger area)

  • layer: A camada de colisão da entity que acionou o trigger

  • position: A posição da entity que acionou o trigger

  • rotation: A rotação da entity que acionou o trigger

  • scale: A escala da entity que acionou o trigger

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

// Trigger area
const triggeredEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

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

// Entity que irá acionar a trigger area
const triggerEntity = engine.addEntity()

const triggeredEntity = engine.addEntity()

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

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

Layers de trigger area

Use o segundo argumento opcional do TriggerArea componente para definir as layers que irão ativar a trigger area.

Por padrão, a trigger area é ativada apenas pelo player, via a layer ColliderLayer.CL_PLAYER. Você pode alterar isso para qualquer outra collision layer passando-a como o segundo argumento do TriggerArea component.

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

// Trigger area
const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity, ColliderLayer.CL_CUSTOM1)

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

// Entity que irá ativar a trigger area
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 para mais detalhes.

• ColliderLayer.CL_PHYSICS

• ColliderLayer.CL_POINTER

• ColliderLayer.CL_CUSTOM1 até CL_CUSTOM8

• ColliderLayer.CL_NONE

💡 Tip: As layers CL_CUSTOM1 até CL_CUSTOM8 não têm nenhum comportamento especial por si só, você pode usá-las para o que for mais adequado à sua cena.

Você também pode configurar uma trigger area para detectar múltiplas layers ao mesmo tempo.

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

Isto irá ativar a trigger area quando qualquer entity com as layers CL_CUSTOM1 ou CL_CUSTOM2 entrar na trigger area.