> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/trigger-areas.md).

# 트리거 영역

씬에서 트리거 영역을 사용하는 방법을 알아보세요

트리거 영역을 사용하면 플레이어가 영역에 들어오거나 나갈 때, 또는 다른 어떤 엔터티가 영역에 들어오거나 나갈 때 발생하는 이벤트에 반응할 수 있습니다. 이는 상호작용하는 장면을 만드는 데 필요한 기본 도구입니다. 플레이어가 다가오면 문이 열리게 하거나, 공이 골에 들어가면 점수를 얻는 것과 같은 용도로 사용할 수 있습니다.

## 트리거 영역 사용하기

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

```ts
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` 이벤트를 발생시킨 엔터티가 현재 플레이어인지, 다른 사람의 아바타가 아닌지를 확인하기 위해

## 트리거 영역 형태

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

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

// 박스
TriggerArea.setBox(triggerEntity)

// 구체
TriggerArea.setSphere(triggerEntity)
```

{% hint style="info" %}
**💡 팁**: 구체는 엔진이 계산하기 가장 쉬운 형태입니다. 구체의 중심으로부터의 거리를 확인하는 방식으로 구현되기 때문입니다. 확실하지 않다면 구체를 사용하세요.
{% endhint %}

트리거 영역의 크기를 변경하려면 다음을 사용할 수 있습니다 `크기` 속성을 `Transform` 컴포넌트를 보유한 엔터티에 `TriggerArea`.

```ts
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` 트리거 영역이 있는 엔터티에 컴포넌트를 추가하고, 디버그하려는 형태로 모양을 설정하세요. 기본 메시의 크기는 트리거 영역의 크기와 일치합니다.

```ts
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`: 엔터티가 트리거 영역 안에 있는 동안, 매 프레임마다 트리거됩니다.

```ts
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)
* `타임스탬프`: 트리거 이벤트의 타임스탬프입니다
* `트리거`: 다음 필드를 가진 객체입니다:
  * `entity`: 트리거를 발생시킨 엔터티의 ID입니다(트리거 영역에 들어온 엔터티)
  * `layers`: 트리거를 발생시킨 엔터티의 충돌 레이어입니다
  * `위치`: 트리거를 발생시킨 엔터티의 위치입니다
  * `회전`: 트리거를 발생시킨 엔터티의 회전입니다
  * `크기`: 트리거를 발생시킨 엔터티의 스케일입니다

{% hint style="warning" %}
**흔히 헷갈리는 점**: 이름과 달리, `result.triggeredEntity` 하지 않습니다 **아닙니다** 는 이벤트를 트리거한 엔터티를 가리킵니다. 이 두 필드는 쉽게 혼동됩니다:

* `result.trigger?.entity`: 트리거 영역 안으로 걸어 들어온 엔터티입니다. 보통 확인하고 싶은 대상이며, 예를 들어 어느 플레이어나 객체가 들어왔는지 식별할 때 사용합니다.
* `result.triggeredEntity`: 다음을 소유한 엔터티입니다 `TriggerArea` 컴포넌트(들어온 엔터티가 아니라 트리거 존 자체입니다).

사용: `result.trigger?.entity` 들어오는 엔터티를 식별해야 할 때 사용합니다.
{% endhint %}

```ts
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`: 감지합니다 **모든 아바타**, 로컬 플레이어와 장면에 렌더링되는 다른 모든 플레이어를 모두 포함합니다. 누가 들어오든 상관이 있을 때 사용하세요. 예를 들어 누구든 다가오면 문이 열리거나, 방 안에 몇 명이 있는지 세어야 할 때 사용할 수 있습니다. 레이어를 따로 지정하지 않으면 기본값으로 이 레이어가 사용됩니다.

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

```ts
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`, 모든 아바타가 트리거 영역을 활성화합니다. 트리거를 발생시킨 아바타가 로컬 플레이어인지 확인하려면 result의 엔터티를 다음과 비교하세요: `engine.PlayerEntity`:

```ts
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`그리고 이 트리거의 효과를 모든 플레이어 간에 동기화하는 것이 이상적입니다. 예를 들어 슬라이딩 도어는 당신의 아바타에게만 열리지만, 그 문의 열린 상태는 다른 모든 플레이어와 공유됩니다.

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

## 트리거 영역 레이어

다음의 선택적 두 번째 인수를 사용해 `TriggerArea` 컴포넌트에서 트리거 영역을 활성화할 레이어를 설정하세요. 기본적으로 트리거 영역은 다음 레이어에 의해서만 활성화됩니다 `ColliderLayer.CL_PLAYER`, 자세한 내용은 [영역에 들어오는 플레이어 감지하기](#detect-players-entering-an-area).

다른 엔터티를 감지하려면 충돌 레이어를 다음의 두 번째 인수로 전달하여 변경할 수 있습니다 `TriggerArea` 컴포넌트를 부여해야 합니다.

```ts
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` 컴포넌트를 사용하여 모든 플레이어를 순회하세요. 자세한 내용은 [충돌 레이어](/creator/content-creator-ko/sdk7/3d/colliders.md#Collision-layers) 자세한 내용은 다음을 참조하세요.

* `ColliderLayer.CL_PLAYER`: 모든 아바타(로컬 + 원격)
* `ColliderLayer.CL_MAIN_PLAYER`: 로컬 플레이어만
* `ColliderLayer.CL_PHYSICS`
* `ColliderLayer.CL_POINTER`
* `ColliderLayer.CL_CUSTOM1` 부터 `CL_CUSTOM8`
* `ColliderLayer.CL_NONE`

{% hint style="info" %}
**💡 팁**: 레이어 `CL_CUSTOM1` 부터 `CL_CUSTOM8` 는 그 자체로 특별한 동작이 없으므로, 장면에 가장 잘 맞는 용도로 자유롭게 사용할 수 있습니다.
{% endhint %}

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

```ts
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` 트리거 영역에 들어올 때 트리거됩니다.

{% hint style="info" %}
**💡 팁**: 다음을 실제로 다루는 작동 예제를 보려면 `TriggerArea` 엔드투엔드로 살펴보세요: [`75,-9-trigger-areas`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/75,-9-trigger-areas) 테스트 장면을 확인하세요. 이 장면은 ENTER/EXIT 와이어 계약과 SDK의 틱별 `onTriggerStay` 합성, 회전된 영역, 커스텀 콜라이더 레이어에서 이동하는 트리거 발생자, 그리고 떨어지는 엔터티에 부착된 영역을 다룹니다. 콜라이더 레이어 자체의 동작을 보려면 다음을 확인하세요 [`5,5-collider-layers`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/5,5-collider-layers).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/trigger-areas.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.