Áreas de activación

Aprende a usar áreas de activación en tu escena

Las áreas de Trigger 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 aproxima, o para sumar un punto cuando una pelota entra en un gol.

Uso de áreas de Trigger

Para usar áreas de Trigger 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 área de Trigger
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('¡Jugador entró en el área de Trigger!')
})

Formas de las áreas de Trigger

Las áreas de Trigger pueden ser una caja o una esfera.

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

// Caja
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. Si tienes dudas, usa una esfera.

Para alterar el tamaño del área de Trigger, puedes usar el escala 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 área de Trigger, puedes añadir un MeshShape componente a la entidad con el área de Trigger, y establecer la forma a la que quieras depurar. Las dimensiones de la malla por defecto 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 de área de Trigger

Puedes usar la triggerAreaEventsSystem para reaccionar a los diferentes eventos de un área de Trigger:

• onTriggerEnter: Activado cuando una entidad entra en el área de Trigger.

• onTriggerExit: Activado cuando una entidad sale del área de Trigger.

• onTriggerStay: Activado mientras una entidad está en el área de Trigger, 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('¡Jugador entró en el área de Trigger!')
})

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

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

Respuestas a eventos de Trigger

Cuando se dispara un evento de área de Trigger, 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 área de Trigger)

• 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 área de Trigger)

  • layer: La capa de colisión de la entidad que activó el Trigger

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

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

  • escala: 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 á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 entidad entró en el área de Trigger!', 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 Trigger: ', result.trigger.entity)
  console.log('Capa Trigger: ', result.trigger.layer)
  console.log('Posición Trigger: ', result.trigger.position)
  console.log('Rotación Trigger: ', result.trigger.rotation)
  console.log('Escala Trigger: ', result.trigger.scale)
})

Capas de áreas 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 se activa solo por el jugador, vía la capa ColliderLayer.CL_PLAYER. Puedes cambiar esto a cualquier otra capa de colisión pasándola como segundo argumento del TriggerArea componente.

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 á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 de MeshCollider componente. Ver Collision layers para más detalles.

• 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í solas, puedes usarlas para lo que mejor convenga a tu escena.

También puedes configurar un área de Trigger 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 área de Trigger cuando cualquier entidad con las capas CL_CUSTOM1 u CL_CUSTOM2 entre en el área de Trigger.