트리거 영역

씬에서 트리거 영역을 사용하는 방법을 알아봅니다

트리거 영역은 플레이어가 영역에 들어오거나 나갈 때, 또는 다른 어떤 엔티티가 영역에 들어오거나 나갈 때의 이벤트에 반응할 수 있게 해줍니다. 이는 인터랙티브 장면을 만드는 데 핵심적인 도구입니다. 플레이어가 다가오면 문이 열리게 하거나, 공이 골대에 들어가면 점수를 얻는 데 사용할 수 있습니다.

트리거 영역 사용하기

트리거 영역을 사용하려면 먼저 다음을 추가해야 합니다 TriggerArea 를 엔티티에 컴포넌트로 추가한 다음, 다음을 사용하세요 triggerAreaEventsSystem 이벤트에 반응합니다.

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

// 엔티티 생성
const triggerEntity = engine.addEntity()

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

// 트리거 영역
TriggerArea.setBox(triggerEntity)

// 트리거 영역이 활성화될 때의 이벤트
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  if (result.trigger?.entity !== engine.PlayerEntity) return;
  console.log('플레이어가 트리거 영역에 들어왔습니다!')
})

기본적으로 TriggerArea 컴포넌트는 다음 이벤트에 반응합니다 어떤 플레이어가 영역으로 걸어 들어오는 것. 위 코드는 다음을 추가합니다 if (result.trigger?.entity !== engine.PlayerEntity) return 이벤트를 발생시킨 엔티티가 현재 플레이어이고 다른 사람의 아바타가 아님을 확인하기 위해

트리거 영역 모양

트리거 영역은 박스 또는 구일 수 있습니다.

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

// 박스
TriggerArea.setBox(triggerEntity)

// 구
TriggerArea.setSphere(triggerEntity)

💡 팁: 구는 구의 중심으로부터의 거리를 확인하는 방식으로 판정되므로 엔진이 계산하기 가장 쉬운 모양입니다. 확신이 없으면 구를 사용하세요.

트리거 영역의 크기를 변경하려면 다음을 사용할 수 있습니다 크기 의 속성을 Transform 를 보유한 엔티티의 컴포넌트를 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),
})

디버깅

장면을 디버그하고 트리거 영역이 덮는 범위를 보려면 다음을 추가할 수 있습니다 MeshRenderer 트리거 영역이 있는 엔티티에 컴포넌트를 추가하고, 디버그하려는 모양으로 설정하세요. 기본 메시의 크기는 트리거 영역의 크기와 일치합니다.

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

트리거 영역 이벤트

다음을 사용할 수 있습니다 triggerAreaEventsSystem 트리거 영역의 다양한 이벤트에 반응하려면 다음을 사용하세요:

• onTriggerEnter: 엔티티가 트리거 영역에 들어오면 트리거됩니다.

• onTriggerExit: 엔티티가 트리거 영역을 떠나면 트리거됩니다.

• onTriggerStay: 엔티티가 트리거 영역 안에 있는 동안, 매 프레임마다 트리거됩니다.

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

const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

// 진입 시
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('플레이어가 트리거 영역에 들어왔습니다!')
})

// 나갈 때
triggerAreaEventsSystem.onTriggerExit(triggerEntity, function(result) {
  console.log('플레이어가 트리거 영역을 벗어났습니다!')
})

// 머무는 동안
triggerAreaEventsSystem.onTriggerStay(triggerEntity, function(result) {
  console.log('플레이어가 트리거 영역 안에 있습니다!')
})

트리거 이벤트 응답

트리거 영역 이벤트가 트리거되면 다음을 사용할 수 있습니다 result 매개변수로 트리거된 엔티티와 이벤트를 트리거한 엔티티에 대한 정보를 모두 얻을 수 있습니다.

다음 속성을 result 매개변수에서 사용할 수 있습니다:

• triggeredEntity: 트리거된 엔티티의 ID입니다(트리거 영역을 소유한 엔티티입니다)

• triggeredEntityPosition: 트리거된 엔티티의 위치입니다

• triggeredEntityRotation: 트리거된 엔티티의 회전입니다

• eventType: 트리거 이벤트의 유형입니다(ENTER, EXIT, STAY)

• 타임스탬프: 트리거 이벤트의 타임스탬프입니다

• 트리거: 다음 필드를 가진 객체입니다:

  • 엔티티: 트리거를 발생시킨 엔티티의 ID입니다(트리거 영역에 들어온 엔티티)

  • layers: 트리거를 발생시킨 엔티티의 충돌 레이어입니다

  • 위치: 트리거를 발생시킨 엔티티의 위치입니다

  • 회전: 트리거를 발생시킨 엔티티의 회전입니다

  • 크기: 트리거를 발생시킨 엔티티의 스케일입니다

흔히 헷갈리는 점: 이름과 달리, result.triggeredEntity 합니다 아닙니다 는 이벤트를 트리거한 엔티티를 가리킵니다. 이 두 필드는 쉽게 혼동됩니다:

• result.trigger?.entity: 트리거 영역으로 들어간 엔티티입니다. 보통 확인하려는 대상은 이것으로, 예를 들어 어떤 플레이어나 객체가 들어왔는지 식별할 때 사용합니다.

• result.triggeredEntity: 다음을 소유한 엔티티입니다 TriggerArea 컴포넌트(들어온 엔티티가 아니라 트리거 영역 자체).

다음을 사용하세요 result.trigger?.entity 들어오는 엔티티를 식별해야 할 때 사용합니다.

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

// 트리거 영역이 있는 엔티티
const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity)

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

// 진입 시
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function(result) {
  console.log('엔티티가 트리거 영역에 들어왔습니다!', result.triggeredEntity)
  console.log('트리거된 엔티티 위치: ', result.triggeredEntityPosition)
  console.log('트리거된 엔티티 회전: ', result.triggeredEntityRotation)
  console.log('이벤트 유형: ', result.eventType)
  console.log('타임스탬프: ', result.timestamp)
  console.log('트리거 엔티티: ', result.trigger.entity)
  console.log('트리거 레이어: ', result.trigger.layers)
  console.log('트리거 위치: ', result.trigger.position)
  console.log('트리거 회전: ', result.trigger.rotation)
  console.log('트리거 스케일: ', result.trigger.scale)
})

영역에 들어오는 플레이어 감지하기

트리거 영역의 가장 일반적인 용도는 플레이어가 드나드는 것에 반응하는 것입니다. 두 개의 충돌 레이어가 아바타를 감지하며, 어떤 레이어를 사용할지는 장면이 누구에게 반응해야 하는지에 따라 달라집니다:

• ColliderLayer.CL_MAIN_PLAYER: 감지합니다 로컬 머신을 사용하는 플레이어만. 응답이 해당 플레이어만을 위한 것일 때 사용하세요. 예를 들어 그 플레이어를 텔레포트시키거나, 그 플레이어에게만 소리를 재생하거나, 퀘스트 진행 상황을 추적할 때입니다. 성능 측면에서도 가장 저렴한 옵션입니다.

• ColliderLayer.CL_PLAYER: 감지합니다 모든 아바타, 로컬 플레이어와 장면에 렌더링되는 다른 모든 플레이어를 모두 포함합니다. 누구든지 들어오는 것이 중요할 때 사용하세요. 예를 들어 누군가 다가오면 문이 열리거나, 방에 몇 명이 있는지 셀 때입니다. 별도로 지정하지 않으면 기본 레이어입니다.

다음 예시는 로컬 플레이어에게만 반응합니다:

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

// 엔티티 생성
const triggerEntity = engine.addEntity()

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

// 로컬 플레이어만 감지하는 트리거 영역
TriggerArea.setBox(triggerEntity, ColliderLayer.CL_MAIN_PLAYER)

// 트리거 영역이 활성화될 때의 이벤트
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function (result) {
  console.log('당신이 트리거 영역에 들어왔습니다!')
})

다음을 사용할 때 CL_PLAYER, 모든 아바타가 트리거 영역을 활성화합니다. 이를 트리거한 아바타가 로컬 플레이어인지 확인하려면 결과의 엔티티를 다음과 비교하세요 engine.PlayerEntity:

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

// 엔티티 생성
const triggerEntity = engine.addEntity()

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

// 트리거 영역, 기본 CL_PLAYER 레이어 사용
TriggerArea.setBox(triggerEntity)

// 트리거 영역이 활성화될 때의 이벤트
triggerAreaEventsSystem.onTriggerEnter(triggerEntity, function (result) {
  if (result.trigger?.entity === engine.PlayerEntity) {
    console.log('당신이 트리거 영역에 들어왔습니다!')
  } else {
    console.log('다른 플레이어가 트리거 영역에 들어왔습니다!')
  }
})

대부분의 경우 모든 플레이어를 감지하려 하기보다, 현재 플레이어만 감지하고(다음을 통해) CL_MAIN_PLAYER) 이 트리거의 효과를 모든 플레이어 간에 동기화하는 것이 이상적입니다. 예를 들어 미닫이문은 당신의 아바타에게만 열리지만, 그 문의 열린 상태는 다른 모든 플레이어와 공유됩니다.

💡 팁: 마스크에 아바타 레이어만 포함하는 트리거 영역(CL_PLAYER, CL_MAIN_PLAYER, 또는 둘 다)은 최적화됩니다. 엔진이 이를 아바타 전용 물리 레이어에 배치하므로, 아바타가 아닌 것과의 겹침은 장면의 코드에 도달하기 전에 물리 엔진에서 버려집니다. 마스크가 정확히 다음과 같은 트리거 영역은 CL_MAIN_PLAYER 더욱 최적화됩니다. 핸들러에 도달하기 전에 로컬 플레이어가 아닌 콜라이더와의 모든 겹침을 바로 차단하므로, 로컬 플레이어만 감지하는 것은 사실상 비용이 없습니다.

트리거 영역 레이어

다음의 선택적 두 번째 인수를 사용하여 TriggerArea 컴포넌트에 트리거 영역을 활성화할 레이어를 설정하세요. 기본적으로 트리거 영역은 레이어 ColliderLayer.CL_PLAYER, 참고: 영역에 들어오는 플레이어 감지하기.

를 통해서만 활성화됩니다. 다른 엔티티를 감지하도록 충돌 레이어를 변경하려면 이를 다음의 두 번째 인수로 전달하세요 TriggerArea 컴포넌트를 추가해야 합니다.

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

// 트리거 영역
const triggerEntity = engine.addEntity()

TriggerArea.setBox(triggerEntity, ColliderLayer.CL_CUSTOM1)

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

// 트리거 영역을 활성화할 엔티티
const movingEntity = engine.addEntity()

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

MeshCollider.setBox(movingEntity, ColliderLayer.CL_CUSTOM1)

허용되는 값은 다음과 동일합니다 MeshCollider 컴포넌트가 붙은 모든 플레이어를 순회하세요. 자세한 내용은 충돌 레이어 자세한 내용은.

• ColliderLayer.CL_PLAYER: 모든 아바타(로컬 + 원격)

• ColliderLayer.CL_MAIN_PLAYER: 로컬 플레이어만

• ColliderLayer.CL_PHYSICS

• ColliderLayer.CL_POINTER

• ColliderLayer.CL_CUSTOM1 부터 CL_CUSTOM8

• ColliderLayer.CL_NONE

💡 팁: 레이어 CL_CUSTOM1 부터 CL_CUSTOM8 자체적으로 특별한 동작이 없으므로, 장면에 가장 잘 맞는 용도로 자유롭게 사용할 수 있습니다.

트리거 영역이 여러 레이어를 한 번에 감지하도록 설정할 수도 있습니다.

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

이렇게 하면 다음 레이어를 가진 어떤 엔티티가 CL_CUSTOM1 또는 CL_CUSTOM2 트리거 영역에 들어올 때 트리거 영역이 활성화됩니다.

💡 팁: 다음을 사용하는 동작 예시는 TriggerArea 엔드투엔드로 확인하려면 다음을 보세요 75,-9-trigger-areas 테스트 장면입니다. 이 장면은 ENTER/EXIT 와이어 계약과 SDK의 틱별 onTriggerStay 합성, 회전된 영역, 사용자 지정 충돌 레이어의 이동하는 트리거 주체, 그리고 떨어지는 엔티티에 부착된 영역을 다룹니다. 충돌 레이어 자체의 동작을 보려면 다음을 보세요 5,5-collider-layers.