Áreas de activación

Aprende cómo usar trigger areas en tu escena

Las áreas de activación (trigger areas) te permiten reaccionar al evento de un jugador entrando o saliendo de un área, o de cualquier otra entidad entrando o saliendo 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 las áreas de activación

Para usar áreas de activación 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'

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

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

// Área de activación
TriggerArea.setBox(triggerEntity)

// Evento cuando el área de activación se activa
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 componente reacciona al evento de cualquier jugador entrando en el área. El código anterior añade if (result.trigger?.entity !== engine.PlayerEntity) return para comprobar que la entidad que causó el evento es el jugador actual, y no el avatar de otra persona

Formas de las áreas de activación

Las áreas de activación 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 activación, puedes usar la scale propiedad del Transform componente en la entidad que contiene la 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 añadir un MeshShape componente a la entidad con el área de activación, y establecer la forma a la que quieras depurar. Las dimensiones de la malla por defecto 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 de áreas de activación

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

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

• onTriggerExit: Se dispara cuando una entidad sale del área de activación.

• onTriggerStay: Se dispara mientras una entidad 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 esté dentro
triggerAreaEventsSystem.onTriggerStay(triggerEntity, function(result) {
  console.log('¡El jugador está en el área de activación!')
})

Respuestas a eventos de activación

Cuando se dispara un evento de un área de activación, puedes usar el result parámetro para obtener información tanto de la entidad que fue activada como de la entidad que provocó 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 activación)

• 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 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 entidad que provocó la activación (la entidad que entró en el área de activación)

  • layer: La capa de colisión de la entidad que provocó la activación

  • position: La posición de la entidad que provocó la activación

  • rotation: La rotación de la entidad que provocó la activación

  • scale: La escala de la entidad que provocó la activación

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

// Área de activación
const triggeredEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

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

// Entidad que activará el área de activación
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 activación!', 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('Marca de tiempo: ', 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 áreas de activación

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

Por defecto, el área de activación se activa sólo por la capa ColliderLayer.CL_PLAYER. Esta capa incluye a todos los jugadores, no sólo 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, añade la siguiente comprobación a la función del trigger if (result.trigger?.entity !== engine.PlayerEntity) return.

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

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

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

// Área de activación
TriggerArea.setBox(triggerEntity)

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

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

import { engine, Transform, TriggerArea, MeshCollider, 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),
})

// Entidad 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 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 activación 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 activación cuando cualquier entidad con las capas CL_CUSTOM1 o CL_CUSTOM2 entre en el área de activación.