Trigger Areas

Aprende cómo usar trigger areas en tu scene

Las áreas de trigger te permiten reaccionar al evento de que un jugador entre o salga de un área, o de que cualquier otra entity entre o salga 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 áreas de trigger

Para usar áreas de trigger necesitas añadir un TriggerArea componente a una entity, luego usa un triggerAreaEventsSystem para reaccionar a los eventos.

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

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

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

// Área de trigger
TriggerArea.setBox(triggerEntity)

// Evento cuando se activa el área de trigger
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  if (result.trigger?.entity !== engine.PlayerEntity) return;
  console.log('¡El jugador entró en el área de trigger!')
})

Por defecto, el TriggerArea componente reacciona al evento de cualquier jugador que entra en el área. El código anterior añade if (result.trigger?.entity !== engine.PlayerEntity) return para comprobar que la entity que causó el evento es el jugador actual, y no el avatar de otra persona

Formas del área de trigger

Las áreas de trigger pueden ser un cubo o una esfera.

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

// Cubo
TriggerArea.setBox(triggerEntity)

// Esfera
TriggerArea.setSphere(triggerEntity)

💡 Consejo: 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. En caso de duda, usa una esfera.

Para modificar el tamaño del área de trigger, puedes usar la scale propiedad del Transform componente en la entity 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 área de trigger, puedes añadir un MeshShape componente a la entity con el área de trigger, y establecer la forma que quieras depurar. Las dimensiones de la mesh predeterminada coincidirán con las dimensiones del á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 del área de trigger

Puedes usar el triggerAreaEventsSystem para reaccionar a los distintos eventos de un área de trigger:

• onTriggerEnter: Se activa cuando una entity entra en el área de trigger.

• onTriggerExit: Se activa cuando una entity sale del área de trigger.

• onTriggerStay: Se activa mientras una entity está en el área de trigger, 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 área de trigger!')
})

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

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

Respuestas a eventos de trigger

Cuando se activa un evento de área de trigger, puedes usar el result parámetro para obtener información tanto de la entity que fue activada como de la entity que activó el evento.

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

• triggeredEntity: El ID de la entity que fue activada (esta es la entity que posee el área de trigger)

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

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

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

• timestamp: La marca de tiempo del evento de trigger

• trigger: Un objeto con los siguientes campos:

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

  • layer: La capa de colisión de la entity que activó el trigger

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

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

  • scale: El scale de la entity que activó el trigger

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

// Área de trigger
const triggeredEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

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

// Entity que activará el área de trigger
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 entity entró en el área de trigger!', result.triggeredEntity)
  console.log('Posición de la entity activada: ', result.triggeredEntityPosition)
  console.log('Rotación de la entity activada: ', result.triggeredEntityRotation)
  console.log('Tipo de evento: ', result.eventType)
  console.log('Marca de tiempo: ', result.timestamp)
  console.log('Entity 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('Scale del trigger: ', result.trigger.scale)
})

Capas del área de trigger

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

Por defecto, el área de trigger solo se activa mediante la capa ColliderLayer.CL_PLAYER. Esta capa incluye a todos los players — no solo al jugador actual, sino también a cualquier otro avatar que se esté renderizando en la escena. Si quieres detectar solo al jugador actual y no a otros, tienes dos opciones:

• Usa la ColliderLayer.CL_MAIN_PLAYER capa en su lugar, que solo coincide con el jugador local.

• O conserva CL_PLAYER y añade if (result.trigger?.entity !== engine.PlayerEntity) return dentro del callback.

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

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

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

// Área de trigger
TriggerArea.setBox(triggerEntity)

// Evento cuando se activa el área de trigger
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  if (result.trigger?.entity !== engine.PlayerEntity) return;
  console.log('¡El jugador entró en el área de trigger!')
})

También puedes cambiar la capa de colisión para detectar cualquier otra entity pasándola como segundo argumento del TriggerArea componente.

import { engine, Transform, TriggerArea, MeshCollider, 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 activará el área de trigger
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 del MeshCollider componente. Consulta Capas de colisión para más detalles.

• ColliderLayer.CL_PLAYER: cualquier avatar (local + remoto)

• ColliderLayer.CL_MAIN_PLAYER: solo el jugador local

• ColliderLayer.CL_PHYSICS

• ColliderLayer.CL_POINTER

• ColliderLayer.CL_CUSTOM1 hasta CL_CUSTOM8

• ColliderLayer.CL_NONE

💡 Consejo: Las capas CL_CUSTOM1 hasta CL_CUSTOM8 no tienen ningún comportamiento especial por sí mismas, puedes usarlas para lo que mejor se adapte a tu escena.

💡 Consejo: Un área de trigger con una máscara exactamente igual a CL_MAIN_PLAYER está optimizada: el trigger interrumpe cualquier superposición con colliders de jugadores no locales antes de llegar al handler, así que detectar solo al jugador local es, en esencia, gratis.

También puedes configurar un área de trigger para detectar varias 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 área de trigger cuando cualquier entity con las capas CL_CUSTOM1 o CL_CUSTOM2 entre en el área de trigger.