Áreas de Trigger

Aprende cómo usar áreas de Trigger en tu escena

Las áreas de activación te permiten reaccionar al evento de que un jugador entre o salga de un área, o de que cualquier otra entidad 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 anotar un punto cuando una pelota entra en una portería.

Usar áreas de activación

Para usar áreas de activación necesitas agregar un TriggerArea component a una entity, luego usar 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 activación
TriggerArea.setBox(triggerEntity)

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

Por defecto, el TriggerArea component 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 activación

Las áreas de activación 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 alterar el tamaño del área de activación, puedes usar el scale propiedad del Transform component 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 activación, puedes agregar un MeshRenderer component a la entity con el área de activación, y establecer la forma que quieras depurar. Las dimensiones del mesh predeterminado coincidirán con las dimensiones del área de activación.

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 activación

Puedes usar el triggerAreaEventsSystem para reaccionar a los distintos eventos de un área de activación:

• onTriggerEnter: Se activa cuando una entity entra en el área de activación.

• onTriggerExit: Se activa cuando una entity sale del área de activación.

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

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

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

Respuestas a eventos de activación

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

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

• triggeredEntity: El ID de la entity que se activó (esta es la entity que posee el área de activación)

• triggeredEntityPosition: La posición de la entity que se activó

• triggeredEntityRotation: La rotación de la entity que se activó

• eventType: El tipo de evento de activación (ENTER, EXIT, STAY)

• timestamp: La marca de tiempo del evento de activación

• 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 activación)

  • layers: Las capas 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

Confusión común: a pesar de su nombre, result.triggeredEntity no se refiere a la entity que activó el evento. Estos dos campos se confunden fácilmente:

• result.trigger?.entity: la entity que entró en el área de activación. Esto suele ser lo que quieres comprobar, por ejemplo para identificar qué jugador u objeto entró.

• result.triggeredEntity: la entity que posee el TriggerArea component (la propia zona de activación, no la entity que entró en ella).

Usa result.trigger?.entity cuando necesites identificar la entity que entra.

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

// Entity con el área de activación
const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

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

// Al entrar
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('¡Una entity entró en el área de activación!', 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('Capas del trigger: ', result.trigger.layers)
  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)
})

Detectar jugadores que entran en un área

El uso más común de las áreas de activación es reaccionar a los jugadores que entran o salen. Dos capas de colisión detectan avatars, y cuál usar depende de a quién debe reaccionar la escena:

• ColliderLayer.CL_MAIN_PLAYER: Detecta solo al jugador que usa la máquina local. Úsalo cuando la respuesta esté pensada solo para ese jugador, por ejemplo para teleportarlo, reproducirle un sonido o hacer seguimiento de su progreso en una quest. Esta también es la opción más barata en términos de rendimiento.

• ColliderLayer.CL_PLAYER: Detecta todos los avatars, tanto al jugador local como a cualquier otro jugador que se esté renderizando en la escena. Úsalo cuando importe que entre cualquiera, por ejemplo una puerta que se abre cuando cualquiera se acerca, o contar cuántas personas hay en una room. Esta es la capa predeterminada si no se especifica ninguna.

El siguiente ejemplo reacciona solo al jugador local:

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

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

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

// Área de activación que solo detecta al jugador local
TriggerArea.setBox(triggerEntity, ColliderLayer.CL_MAIN_PLAYER)

// Evento cuando se activa el área de activación
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function (result) {
  console.log('¡Has entrado en el área de activación!')
})

Al usar CL_PLAYER, todos los avatars activan el área de activación. Para saber si el avatar que lo activó es el jugador local, compara la entity del resultado con engine.PlayerEntity:

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 activación, usando la capa predeterminada CL_PLAYER
TriggerArea.setBox(triggerEntity)

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

En la mayoría de los casos, en lugar de intentar detectar a todos los jugadores, el enfoque ideal es detectar solo al jugador actual (mediante CL_MAIN_PLAYER) y luego sincronizar los efectos de este trigger entre todos los jugadores. Por ejemplo, una puerta corrediza se abre solo para tu avatar, pero luego el estado abierto de esa puerta se comparte con todos los demás jugadores.

💡 Consejo: Las áreas de activación cuyo mask solo incluye capas de avatar (CL_PLAYER, CL_MAIN_PLAYER, o ambas) están optimizadas: el Engine las coloca en una capa física solo de avatars, así que los overlaps con cualquier cosa que no sea un avatar son descartados por el motor de física antes de llegar al código de tu escena. Un área de activación con un mask exactamente igual a CL_MAIN_PLAYER está aún más optimizada: omite cualquier overlap con colliders que no sean del jugador local antes de llegar al handler, por lo que detectar solo al jugador local es prácticamente gratis.

Capas del área de activación

Usa el segundo argumento opcional del TriggerArea component para establecer las capas que activarán el área de activación. Por defecto, el área de activación se activa solo por la layer ColliderLayer.CL_PLAYER, consulta Detectar jugadores que entran en un área.

Puedes cambiar la capa de colisión para detectar cualquier otra entity pasándola como el segundo argumento del TriggerArea component.

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

// Área de activación
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 activación
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 component. 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.

También puedes configurar un área de activación para detectar varias capas a la vez.

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

Esto activará el área de activación cuando cualquier entity con las capas CL_CUSTOM1 o CL_CUSTOM2 entre en el área de activación.

💡 Consejo: Para ver un ejemplo funcional que usa TriggerArea de principio a fin, consulta la 75,-9-trigger-areas escena de prueba, que cubre el wire contract de ENTER/EXIT y la síntesis por tick del SDK, onTriggerStay las áreas rotadas, los triggerers móviles en capas de collider personalizadas y las áreas adjuntas a entities que caen. Para ver cómo se comportan las propias capas de collider, consulta 5,5-collider-layers.