Trigger Areas

Aprende cómo usar trigger areas en tu escena

Las áreas de disparo (trigger areas) te permiten reaccionar al evento de un jugador que entra o sale de un área, o de cualquier otra entidad que entra o sale de un área. Esta es una herramienta fundamental para crear escenas interactivas. Úsalas para cosas como abrir una puerta cuando el jugador se acerca, o para sumar un punto cuando una pelota entra en una portería.

Uso de trigger areas

Para usar trigger areas necesitas añadir un TriggerArea componente a una entidad, luego usar un triggerAreaEventsSystem para reaccionar a los eventos.

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

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

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

// Trigger area
TriggerArea.setBox(triggerEntity)

// Evento cuando se activa el trigger area
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('¡El jugador entró en el trigger area!')
})

Formas de trigger area

Las trigger areas pueden ser una caja (box) o una esfera (sphere).

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

// Caja
TriggerArea.setBox(triggerEntity)

// Esfera
TriggerArea.setSphere(triggerEntity)

💡 Tip : La esfera es la forma más fácil de calcular para el engine, ya que se logra comprobando la distancia desde el centro de la esfera. Si tienes dudas, usa una esfera.

Para alterar el tamaño del trigger area, puedes usar el scale propiedad del Transform componente en la entidad que contiene el 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),
})

Depuración

Para depurar tu escena y ver el área cubierta por el trigger area, puedes añadir un MeshShape componente a la entidad con el trigger area, y establecer la forma a la que quieres depurar. Las dimensiones de la malla por defecto coincidirán con las dimensiones del 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 de trigger area

Puedes usar el triggerAreaEventsSystem para reaccionar a los diferentes eventos de un trigger area:

• onTriggerEnter : Activado cuando una entidad entra en el trigger area.

• onTriggerExit : Activado cuando una entidad sale del trigger area.

• onTriggerStay : Activado mientras una entidad está en el trigger area, en cada frame.

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

const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

// Al entrar
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('¡El jugador entró en el trigger area!')
})

// Al salir
triggerAreaEventsSystem.onTriggerExit(triggerEntity, function(result) {
  console.log('¡El jugador salió del trigger area!')
})

// Mientras está dentro
triggerAreaEventsSystem.onTriggerStay(triggerEntity, function(result) {
  console.log('¡El jugador está en el trigger area!')
})

Respuestas a eventos de trigger

Cuando se desencadena un evento de trigger area, puedes usar el result parámetro para obtener información tanto sobre la entidad que fue activada como sobre la entidad que activó el evento.

Las siguientes propiedades están disponibles en el result parámetro:

• triggeredEntity : El ID de la entidad que fue activada (esta es la entidad que posee el trigger area)

• triggeredEntityPosition : La posición de la entidad que fue activada

• triggeredEntityRotation : La rotación de la entidad que fue activada

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

• timestamp : La marca de tiempo (timestamp) del evento de trigger

• trigger : Un objeto con los siguientes campos:

  • entity : El ID de la entidad que activó el trigger (la entidad que entró en el trigger area)

  • layer : La capa de colisión (collision layer) de la entidad que activó el trigger

  • position : La posición de la entidad que activó el trigger

  • rotation : La rotación de la entidad que activó el trigger

  • scale : La escala de la entidad que activó el 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),
})

// Entidad que activará el trigger area
const triggerEntity = engine.addEntity()

const triggeredEntity = engine.addEntity()

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

// Al entrar
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('¡Una entidad entró en el trigger area!', result.triggeredEntity)
  console.log('Posición de la entidad activada: ', result.triggeredEntityPosition)
  console.log('Rotación de la entidad activada: ', result.triggeredEntityRotation)
  console.log('Tipo de evento: ', result.eventType)
  console.log('Timestamp: ', result.timestamp)
  console.log('Entidad del trigger: ', result.trigger.entity)
  console.log('Capa del trigger: ', result.trigger.layer)
  console.log('Posición del trigger: ', result.trigger.position)
  console.log('Rotación del trigger: ', result.trigger.rotation)
  console.log('Escala del trigger: ', result.trigger.scale)
})

Capas de trigger area

Usa el segundo argumento opcional del TriggerArea componente para establecer las capas que activarán el trigger area.

Por defecto, el trigger area se activa solo por el jugador, vía la capa ColliderLayer.CL_PLAYER. Puedes cambiar esto a cualquier otra collision layer pasando ésta como segundo argumento del 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),
})

// Entidad que activará el trigger area
const movingEntity = engine.addEntity()

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

MeshCollider.setBox(movingEntity, ColliderLayer.CL_CUSTOM1)

Los valores permitidos son los mismos que los de la MeshCollider componente. Ver Collision layers para más detalles.

• ColliderLayer.CL_PHYSICS

• ColliderLayer.CL_POINTER

• ColliderLayer.CL_CUSTOM1 hasta CL_CUSTOM8

• ColliderLayer.CL_NONE

💡 Tip : Las capas CL_CUSTOM1 hasta CL_CUSTOM8 no tienen ningún comportamiento especial por sí solas; puedes usarlas para lo que mejor convenga a tu escena.

También puedes configurar un trigger area para detectar múltiples capas a la vez.

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

Esto activará el trigger area cuando cualquier entidad con las capas CL_CUSTOM1 o CL_CUSTOM2 entre en el trigger area.