Trigger Areas

Saiba como usar trigger areas na sua scene

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 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 component a uma entity, depois use um triggerAreaEventsSystem para reagir aos eventos.

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 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 jogador atual, e não o avatar de outra pessoa

Formas da área de trigger

As á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)

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

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

Debugging

Para fazer debugging da sua Scene e ver a área coberta pela área de trigger, você pode adicionar um MeshRenderer component à entity com a área de trigger e definir a forma para a que você quer fazer debugging. As dimensões da mesh padrão corresponderão às dimensões da área de trigger.

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.

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

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

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

Respostas aos eventos de trigger

Quando um evento de área de trigger é disparado, você pode usar o result parameter 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 parameter:

• 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)

  • layers: As collision layers 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

Confusão comum: apesar do nome, result.triggeredEntity faz não refere à entity que disparou o evento. Esses dois campos são facilmente confundidos:

• result.trigger?.entity: a entity que entrou na área de trigger. Normalmente é isso que você quer verificar, por exemplo para identificar qual player ou objeto entrou.

• result.triggeredEntity: a entity que possui o TriggerArea component (a própria zona de trigger, não a entity que entrou nela).

Use result.trigger?.entity quando você precisar identificar a entity que entrou.

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

// Entity 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 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('Entity do trigger: ', result.trigger.entity)
  console.log('Layers 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)
})

Detectar players entrando em uma área

O uso mais comum de áreas de trigger é reagir a players entrando ou saindo. Duas collision layers detectam Avatars, e qual delas usar depende de a quem a Scene deve reagir:

• ColliderLayer.CL_MAIN_PLAYER: Detecta apenas o player usando a máquina local. Use isto quando a resposta for destinada apenas a esse player, por exemplo para teleportá-lo, reproduzir um som para ele ou acompanhar seu progresso em uma missão. Esta também é a opção mais barata em termos de performance.

• ColliderLayer.CL_PLAYER: Detecta todos os Avatars, tanto o player local quanto quaisquer outros players sendo renderizados na Scene. Use isto quando a entrada de qualquer pessoa importar, por exemplo uma porta que se abre quando alguém se aproxima, ou contar quantas pessoas há em uma sala. Esta é a layer padrão se nenhuma for especificada.

O exemplo a seguir reage apenas ao player local:

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 detecta apenas o player local
TriggerArea.setBox(triggerEntity, ColliderLayer.CL_MAIN_PLAYER)

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

Ao usar CL_PLAYER, todos os Avatars ativam a área de trigger. Para saber se o Avatar que a disparou é o player local, compare a entity no result com engine.PlayerEntity:

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 layer padrão CL_PLAYER
TriggerArea.setBox(triggerEntity)

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

Na maioria dos casos, em vez de tentar detectar todos os players, a abordagem ideal é detectar apenas o player atual (via CL_MAIN_PLAYER) e depois sincronizar os efeitos deste trigger entre todos os players. Por exemplo, uma porta de correr se abre apenas para o seu Avatar, mas depois o estado aberto dessa porta é compartilhado com todos os outros players.

💡 Dica: Áreas de trigger cuja mask inclui apenas avatar layers (CL_PLAYER, CL_MAIN_PLAYER, ou ambos) são otimizadas: o engine as coloca em uma physics layer apenas de avatars, então sobreposições com qualquer coisa que não seja um avatar são descartadas pelo physics engine antes de chegar ao código da sua Scene. Uma área de trigger com uma mask exatamente igual a CL_MAIN_PLAYER é otimizada ainda mais: ela interrompe antecipadamente qualquer sobreposição com colliders que não sejam do player local antes de chegar ao handler, então detectar apenas o player local é praticamente de graça.

Layers 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, veja Detectar players entrando em uma área.

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

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

// 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 para mais detalhes.

• ColliderLayer.CL_PLAYER: qualquer Avatar (local + remoto)

• ColliderLayer.CL_MAIN_PLAYER: apenas o player local

• ColliderLayer.CL_PHYSICS

• ColliderLayer.CL_POINTER

• ColliderLayer.CL_CUSTOM1 até CL_CUSTOM8

• ColliderLayer.CL_NONE

💡 Dica: As layers CL_CUSTOM1 até CL_CUSTOM8 não têm nenhum comportamento especial por si só; você pode usá-las da forma que melhor se adequar à sua Scene.

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

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

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

💡 Dica: Para um exemplo funcional que utiliza TriggerArea de ponta a ponta, veja a 75,-9-trigger-areas test Scene, que cobre o contrato de wire ENTER/EXIT e a síntese por tick do SDK, onTriggerStay áreas rotacionadas, disparadores em movimento em custom collider layers, e áreas anexadas a entities em queda. Para ver como as próprias collider layers se comportam, veja 5,5-collider-layers.