> 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/interactivity/button-events/system-based-events.md).

# 시스템 기반 이벤트

씬에서 사용자 클릭을 처리하는 방법을 알아봅니다.

씬에 동일한 로직으로 활성화되는 비슷한 엔티티가 여러 개 있다면, 모든 엔티티를 반복 처리하고 해당 동작을 한 번만 정의하는 단일 시스템을 작성할 수 있습니다. 이 방식은 성능 면에서도 더 효율적이며 [데이터 지향적](https://docs.decentraland.org/creator/content-creator-ko/sdk7/architecture/data-oriented-programming.md) 접근 방식입니다.

시스템을 사용해 [전역 입력 이벤트](#global-input-events)를 감지할 수도 있습니다. 이 경우 플레이어 커서가 어디를 향하는지와 관계없이 키를 누를 때마다 씬이 반응합니다.

단일 엔티티를 클릭하거나 버튼을 눌러 활성화하기만 하면 된다면, 가장 쉬운 방법은 [콜백 등록](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/register-callback.md) 접근 방식을 사용하는 것입니다.

더 구체적인 사용자 지정 로직을 설정하려면 원시 데이터를 직접 처리하고 [고급](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/advanced-button-events.md) 접근 방식을 사용할 수 있습니다.

엔티티와 상호작용하려면 엔티티에 [콜라이더](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/colliders.md)가 있어야 합니다. 자세한 내용은 [장애물](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#obstacles) 을 참조하세요. 근접 클릭 이벤트에도 동일하게 적용됩니다.

## 시스템 사용

틱마다 `inputSystem` 네임스페이스의 입력 헬퍼 함수 중 하나를 실행해 버튼 이벤트를 확인합니다. 이 함수는 [시스템](https://docs.decentraland.org/creator/content-creator-ko/sdk7/architecture/systems.md).

예를 들어, 다음 시스템은 `inputSystem.isTriggered()` 함수를 사용해 포인터가 클릭되었는지 확인합니다. 매 틱마다 버튼이 눌렸는지 확인하고, 함수가 `inputSystem.isTriggered()` 반환하는 값이 *true*이면 시스템은 이에 대응하는 사용자 지정 로직을 실행합니다.

```ts
engine.addSystem(() => {
	if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN)) {
		// 버튼을 눌렀을 때 실행할 로직
	}
})
```

다음 헬퍼 함수는 `inputSystem` 네임스페이스에서 사용할 수 있으며, 매 틱마다 비슷한 방식으로 호출할 수 있습니다.

* `inputSystem.isTriggered`: 마지막 틱 이후 입력 동작이 발생했으면 true를 반환합니다.
* `inputSystem.isPressed`: 입력이 현재 눌려 있으면 true를 반환합니다. 버튼을 놓을 때까지 매 틱마다 true를 반환합니다.
* `inputSystem.getInputCommand`: 입력 동작에 관한 데이터가 포함된 객체를 반환합니다.

각 함수에 관한 자세한 내용은 아래 섹션을 참조하세요.

엔티티의 버튼 이벤트를 처리할 때는 플레이어가 엔티티와 상호작용할 수 있다는 것을 알 수 있도록 항상 피드백을 제공하세요. 엔티티에 `PointerEvents` 컴포넌트를 추가하면 플레이어가 해당 엔티티 위에 커서를 올렸을 때 힌트가 표시됩니다. 상호작용 가능한 엔티티에 마우스 오버 힌트를 추가하는 방법은 [피드백 표시](#show-feedback) 를 참조하세요.

### 전역 입력 이벤트

SDK가 추적하는 모든 입력에서 버튼을 누르거나 놓는 이벤트를 감지하려면 `inputSystem.isTriggered` 를 사용하세요.

```ts
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN)
	) {
		// 버튼을 눌렀을 때 실행할 로직
	}
})
```

위 예제는 포인터의 위치나 경로에 있는 엔티티와 관계없이 버튼을 눌렀는지 확인합니다.

`inputSystem.isTriggered()` 는 *true* 를 지정된 버튼이 게임 루프의 현재 틱에서 눌린 경우에만 반환합니다. 버튼을 누르지 않았거나 이전 틱부터 이미 눌려 있었다면 반환값은 *false*.

{% hint style="warning" %}
**📔 참고**: 포인터 이벤트를 감지하려면 플레이어가 씬의 경계 안에 있어야 합니다. 또한 플레이어의 커서가 잠겨 있어야 하며, 커서가 자유로운 상태에서 누른 버튼은 감지되지 않습니다.

상호작용하려는 모든 엔티티에는 [`PointerEvents` 컴포넌트](#show-feedback) 와 [콜라이더가 모두 있어야 합니다](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/colliders.md).
{% endhint %}

다음은 `inputSystem.isTriggered` 함수에 필요한 필수 인수입니다:

* `InputAction`: 수신할 입력으로, 다음 `InputAction` 열거형의 값입니다. 지원되는 옵션은 [포인터 버튼](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#pointer-buttons) 을 참고하세요.
* `PointerEventType`: 수신할 이벤트 유형으로, 다음 `PointerEventType` 열거형의 값입니다. 지원되는 옵션은 [포인터 이벤트 유형](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#types-of-pointer-events) 을 참고하세요.

### 엔티티 활성화

특정 엔티티를 가리키는 동안 발생하는 버튼 이벤트를 감지하려면 `inputSystem.isTriggered` 에 세 번째 선택적 인수를 전달하여 확인할 엔티티를 지정합니다.

```ts
// 엔티티에 PointerEvents 컴포넌트 추가
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				showFeedback: false,
			},
		},
	],
})

// 시스템 생성
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(
			InputAction.IA_POINTER,
			PointerEventType.PET_DOWN,
			myEntity
		)
	) {
		// myEntity에서 버튼을 눌렀을 때 실행할 로직
	}
})
```

위 예제는 매 틱마다 하드코딩된 단일 엔티티를 포인터 버튼(마우스 왼쪽 버튼)으로 눌렀는지 확인합니다.

다음은 `inputSystem.isTriggered` 함수가 받는 인수입니다:

* `InputAction`: 수신할 입력으로, 다음 `InputAction` 열거형의 값입니다. 지원되는 옵션은 [포인터 버튼](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#pointer-buttons) 을 참고하세요.
* `PointerEventType`: 수신할 이벤트 유형으로, 다음 `PointerEventType` 열거형의 값입니다. 지원되는 옵션은 [포인터 이벤트 유형](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#types-of-pointer-events) 을 참고하세요.
* `Entity` *(선택 사항)*: 이러한 이벤트를 확인할 엔티티입니다. 값을 제공하지 않으면 플레이어의 커서가 가리키는 위치와 관계없이 전역적으로 버튼을 눌렀는지 확인합니다.

이 예제에서는 상호작용하려는 엔티티에 `PointerEvents` 컴포넌트도 추가합니다. 이 단계는 필수이며, 이 컴포넌트가 없으면 다음의 어떤 함수로도 해당 엔티티를 감지할 수 없습니다: `inputSystem`. 자세한 내용은 [Show Feedback](#show-feedback) 구성 요소에 대한 자세한 내용은 `PointerEvents` 을 참조하세요.

{% hint style="warning" %}
**📔 참고**: 그리고 [충돌체](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/colliders.md)에 대한 자세한 내용은 [장애물](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#obstacles) 을 참조하세요.
{% endhint %}

플레이어가 같은 방식으로 상호작용할 수 있는 엔티티가 여러 개라면 다음을 사용하는 것이 좋습니다. `inputSystem.getInputCommand`. 이 명령은 엔티티 ID를 포함하여 전역 클릭 명령에 대한 정보를 반환합니다. 이를 사용하면 모든 엔티티를 처리할 수 있는 단일 함수를 실행할 수 있습니다.

```ts
engine.addSystem(() => {
	const result = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN
	)
	if (result) {
		if (result.hit?.entityId === myEntity) {
			// 클릭 처리
		}
	}
})
```

{% hint style="warning" %}
**📔 참고**: 상호작용하려는 모든 엔티티에는 다음 두 가지가 모두 있어야 합니다. [`PointerEvents` 구성 요소](#show-feedback) 및 [충돌체](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/colliders.md).
{% endhint %}

을 참조하세요. [입력 동작의 데이터](#data-from-input-action) 에서 자세한 내용을 확인하세요. 이 방법을 사용하면 포인터 이벤트가 적중한 대상에 대한 더 자세한 데이터도 얻을 수 있습니다.

### 입력 버튼 놓기

다음과 같이 `PointerEventType.PET_UP`.

```ts
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(
			InputAction.IA_POINTER,
			PointerEventType.PET_UP,
			myEntity
		)
	) {
		// myEntity를 가리키는 동안 버튼을 놓았을 때의 로직
	}
})
```

{% hint style="warning" %}
**📔 참고**: 특정 엔티티를 대상으로 포인터 놓기 이벤트를 확인할 때는 버튼을 누른 순간 커서가 가리키던 위치를 고려하지 않습니다. 버튼을 놓는 순간 커서가 가리키는 위치만 고려합니다.

또한 엔티티에는 다음 두 가지가 모두 있어야 합니다. [`PointerEvents` 구성 요소](#show-feedback) 및 [충돌체](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/colliders.md).
{% endhint %}

### 눌린 버튼 확인

다음을 사용하여 버튼이 현재 눌려 있는지 확인할 수 있습니다. `inputSystem.isPressed()` 시스템 내에서 사용합니다.

```ts
engine.addSystem(() => {
	if (inputSystem.isPressed(InputAction.IA_POINTER)) {
		// 버튼을 누르고 있을 때의 로직
	}
})
```

`inputSystem.isPressed()` 는 버튼을 누르고 있는 동안 *true* 를 반환합니다. 버튼을 언제 눌렀는지, 플레이어의 커서가 어디를 가리키는지와 관계없습니다. 그렇지 않으면 다음을 반환합니다. *false*.

해당 `inputSystem.isPressed` 함수는 인수 하나를 받습니다:

* `InputAction`: 수신할 입력으로, 다음 `InputAction` 열거형의 값입니다. 지원되는 옵션은 [포인터 버튼](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#pointer-buttons) 을 참고하세요.

### 여러 엔티티 처리

씬에 포인터 이벤트의 영향을 같은 방식으로 받는 엔티티가 여러 개 있다면, 이들을 모두 순회하는 시스템을 작성하는 것이 합리적입니다.

```ts
engine.addSystem(() => {
	const activatedEntites = engine.getEntitiesWith(PointerEvents)
	for (const [entity] of activatedEntites) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_DOWN,
				entity
			)
		) {
			// 엔티티와의 상호작용에 대응하는 로직
		}
	}
})
```

이 예제에서는 [컴포넌트 쿼리](https://docs.decentraland.org/creator/content-creator-ko/sdk7/architecture/querying-components.md) 를 사용하여 다음 컴포넌트가 있는 모든 엔티티를 순회합니다: `PointerEvents` . 그런 다음 엔티티를 하나씩 순회하면서 각각을 `inputSystem.isTriggered`로 확인합니다. 이 엔티티 중 하나에서 입력 동작이 감지되면 사용자 지정 로직을 실행합니다.

하나의 시스템에서 *모든* 엔티티를 다음 컴포넌트 기준으로 순회하는 대신, `PointerEvents` 컴포넌트가 있고 서로 다르게 동작해야 하는 엔티티를 처리할 별도의 시스템을 작성할 수 있습니다. 권장되는 방법은 특정 [사용자 지정 컴포넌트](https://docs.decentraland.org/creator/content-creator-ko/sdk7/architecture/custom-components.md)로 서로 다른 유형의 엔티티를 표시하고, 별도의 시스템에서 각각을 순회하는 것입니다.

```ts
engine.addSystem(() => {
	const activatedDoors = engine.getEntitiesWith(IsDoor, PointerEvents)
	for (const [entity] of activatedDoors) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_DOWN,
				entity
			)
		) {
			openDoor(entity)
		}
	}
})

engine.addSystem(() => {
	const pickedUpGems = engine.getEntitiesWith(IsGem, PointerEvents)
	for (const [entity] of pickedUpGems) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_DOWN,
				entity
			)
		) {
			pickUp(entity)
		}
	}
})
```

이 예제에는 다음 이름의 사용자 지정 컴포넌트가 있는 모든 엔티티를 순회하는 시스템과 `IsDoor` 다음 이름의 사용자 지정 컴포넌트가 있는 모든 엔티티를 순회하는 또 다른 시스템이 있습니다: `isGem`. 두 시스템 모두 일치하는 각 엔티티가 포인터 버튼으로 활성화되었는지 확인합니다.

이처럼 씬의 코드를 구성하는 방식은 매우 [데이터 지향적](https://docs.decentraland.org/creator/content-creator-ko/sdk7/architecture/data-oriented-programming.md) 이며 메모리 리소스를 효율적으로 사용할 수 있습니다.

\## 하나의 엔티티에 여러 버튼 사용

다음과 같은 헬퍼를 사용하면 `pointerEventsSystem.onPointerDown`각 엔티티에 한 가지 유형의 이벤트만 지정할 수 있습니다. 서로 다른 버튼 이벤트 두 개를 등록할 수 없습니다. 시스템 기반 이벤트를 사용하면 이러한 제한이 없습니다. 예를 들어 다음 엔티티는 플레이어가 E와 F를 눌러 상호작용할 수 있으며, 각 키는 서로 다른 기능을 실행합니다.

```ts
    engine.addSystem(() => {
        if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN, myEntity)) {
            // E에 반응
        }
        if (inputSystem.isTriggered(InputAction.IA_SECONDARY, PointerEventType.PET_DOWN, myEntity)) {
            // F에 반응
        }
    })
```

## 피드백 표시

엔티티를 가리키는 동안 UI 힌트를 표시하려면 해당 엔티티의 `PointerEvents` 컴포넌트에 있는 속성을 사용하세요.

```ts
// 엔티티 생성
const myEntity = engine.addEntity()

// 엔티티에 PointerEvents 컴포넌트를 추가합니다
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
			},
		},
	],
})
```

플레이어의 커서가 이 엔티티의 콜라이더를 가리키면 UI에 호버 힌트가 표시되어 해당 엔티티와 상호작용할 수 있음을 알립니다. 설정할 수 있는 항목에 대한 자세한 내용은 아래 섹션을 참조하세요.

{% hint style="warning" %}
**📔 참고**: `PointerEvents`  컴포넌트는 호버 피드백을 표시하는 기능만 처리합니다. 버튼 이벤트 자체를 사용자 지정 로직으로 처리하려면 다음을 참조하세요. [Using-a-system](#using-a-system).
{% endhint %}

다음 `PointerEvents`  컴포넌트를 사용하려면 포인터 이벤트 정의가 하나 이상 필요합니다. 각 포인터 이벤트 정의는 다음 항목으로 구성할 수 있습니다:

* `eventType`: 수신할 이벤트의 유형으로, 다음 항목의 값입니다. `PointerEventType` 열거형입니다. 지원되는 옵션은 [포인터 이벤트 유형](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#types-of-pointer-events) 을 참조하세요.
* `eventInfo`: 다음 필드를 포함할 수 있는 객체입니다.
  * `button` (*필수*): 수신할 입력을 지정합니다. 값은 다음의 `InputAction` 열거형에서 선택합니다. 지원되는 옵션은 [포인터 버튼](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#pointer-buttons) 을 참조하세요.
  * `hoverText` *(선택 사항)*: 호버 피드백 힌트에 표시할 문자열입니다. 기본값은 "Interact"입니다.
  * `showFeedback` *(선택 사항)* : false이면 이 엔티티의 마우스 오버 힌트와 가장자리 강조 표시가 모두 숨겨집니다. *true* 기본값입니다.
  * `showHighlight` *(선택 사항)* : true이면 플레이어가 커서를 엔티티 위에 올렸을 때 가장자리 강조 표시가 나타납니다. *true* 기본값입니다. 이 값은 다음 항목이 `showFeedback` 인 경우에만 고려됩니다 *true*.
  * `maxDistance` *(선택 사항)*: 플레이어의 **아바타가** 엔티티와 상호작용할 수 있는 최대 거리(미터)입니다. 기본값은 *10미터*입니다. 자세한 내용은 [최대 거리](#max-distance).
  * `maxCameraDistance` *(선택 사항)*: 활성 **카메라가** 엔티티와 상호작용할 수 있는 최대 거리를 미터 단위로 지정합니다. 기본값은 설정되어 있지 않습니다. 자세한 내용은 [최대 거리](#max-distance).
  * `priority` *(선택 사항)*: 여러 엔티티가 겹칠 때 어떤 엔티티를 우선할지 지정합니다. 값이 높을수록 우선순위가 높습니다. *0* 기본값입니다.

하나의 `PointerEvents` 컴포넌트에는 여러 포인터 이벤트 정의를 저장할 수 있으며, 각 정의는 서로 다른 버튼의 이벤트를 감지할 수 있습니다. 각 엔티티에는 *하나의* `PointerEvents` 컴포넌트만 사용할 수 있지만, 이 컴포넌트의 `pointerEvents` 배열에 응답할 이벤트별로 여러 객체를 포함할 수 있습니다.

```ts
PointerEvents.create(NPCEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Greet',
			},
		},
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				hoverText: 'Choke',
			},
		},
		{
			eventType: PointerEventType.PET_UP,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				hoverText: 'Stop Choke',
			},
		},
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_SECONDARY,
				hoverText: 'Give gem',
			},
		},
	],
})
```

플레이어에게는 포인터 이벤트마다 하나씩, 커서 주위에 원형으로 표시되는 여러 레이블이 나타납니다.

아래 예시에서는 `PointerEvents` 를 사용해 마우스 오버 힌트를 표시하고, 사용자 지정 로직으로 플레이어의 동작을 실제로 처리하는 시스템을 함께 사용합니다.

```ts
// 엔티티 생성
const myEntity = engine.addEntity()

// 엔티티에 마우스 오버 피드백 표시
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Open',
			},
		},
	],
})

// 엔티티의 클릭 이벤트 처리
engine.addSystem(() => {
	if (
		inputSystem.isTriggered(
			InputAction.IA_POINTER,
			PointerEventType.PET_DOWN,
			myEntity
		)
	) {
		// 입력 동작에 대한 사용자 지정 로직
	}
})
```

### 마우스 오버 피드백

플레이어가 커서를 `PointerEvents` 컴포넌트가 있는 아이템 위에 올리면 다음이 표시됩니다.

* 엔티티의 가장자리 강조 표시
* 커서 근처에 표시되는 마우스 오버 힌트로, 눌러야 하는 버튼의 아이콘과 "상호작용"이라는 문구가 포함됩니다.

이러한 요소는 표시 여부를 전환하고 사용자 지정할 수 있습니다.

UI의 마우스 오버 피드백에는 `button` 필드에서 선택한 입력에 따라 다른 아이콘이 표시됩니다. PC에서는 `E`  아이콘이 `InputAction.IA_PRIMARY`에, `F`  아이콘이 `InputAction.IA_SECONDARY`에, 마우스 아이콘이 `InputAction.IA_POINTER`.

문구를 변경하려면 `hoverText` 값을 변경하세요. 빠르게 읽을 수 있고 화면을 지나치게 가리지 않도록 문구를 짧게 유지하세요.

```ts
// 엔티티 생성
const chest = engine.addEntity()

// 엔티티에 PointerEvents 컴포넌트를 추가합니다
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Open',
			},
		},
	],
})
```

위 예제에서 포인터 이벤트에는 다음 값이 포함됩니다. `hoverText`. 이 필드는 플레이어가 엔티티를 가리키는 동안 UI에 표시할 문자열을 정의합니다. 기본 문자열은 다음과 같습니다. *Interact*.

{% hint style="info" %}
**💡 팁**: `hoverText`  문자열은 상호작용할 때 수행되는 동작을 설명해야 합니다. 예를 들면 다음과 같습니다. `열기`, `활성화`, `잡기`, `선택`. 플레이어의 주의를 너무 많이 빼앗지 않도록 이 문자열은 최대한 짧아야 합니다.
{% endhint %}

엔티티에 포인터 이벤트가 여러 개 있으면 각 이벤트의 호버 힌트가 커서 주변에 방사형으로 표시됩니다.

The `hoverText` of an `.UP` 포인터 이벤트는 플레이어가 해당 키를 이미 누른 상태에서 엔티티를 가리킬 때만 표시됩니다.

엔티티에 `DOWN` 포인터 이벤트와 `UP` 포인터 이벤트가 모두 있으면, `DOWN` 버튼을 누르지 않은 동안에는 해당 동작의 힌트가 표시됩니다. 버튼을 눌러 계속 누르고 있는 경우에만 힌트가 `UP` 이벤트의 힌트로 바뀝니다.

```ts
// 엔티티 생성
const entity = engine.addEntity()

// 엔티티에 PointerEvents 컴포넌트를 추가합니다
PointerEvents.create(entity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: '드래그',
			},
		},
		{
			eventType: PointerEventType.PET_UP,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Drop',
			},
		},
	],
})
```

호버 힌트는 숨기고 가장자리 강조 표시를 남기려면 `hoverText` 의 값을 ""로 설정합니다.

```ts
// 엔티티 생성
const chest = engine.addEntity()

// 엔티티에 PointerEvents 컴포넌트를 추가합니다
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: '',
			},
		},
	],
})
```

가장자리 강조 표시는 숨기고 호버 힌트를 남기려면 `showHighlight` 을 *false*.

```ts
// 엔티티 생성
const chest = engine.addEntity()

// 엔티티에 PointerEvents 컴포넌트를 추가합니다
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				hoverText: 'Open door',
				showHighlight: false,
			},
		},
	],
})
```

호버 힌트와 가장자리 강조 표시를 모두 숨기려면 `showFeedback` 를 *false*로 설정합니다. 이렇게 하면 커서에 아이콘이나 텍스트가 표시되지 않고 가장자리도 강조 표시되지 않습니다. 엔티티에서 `PointerEvents` 컴포넌트를 제거해도 됩니다.

```ts
// 엔티티 생성
const chest = engine.addEntity()

// 엔티티에 PointerEvents 컴포넌트를 추가합니다
PointerEvents.create(chest, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				showFeedback: false,
			},
		},
	],
})
```

### 최대 거리

일부 엔티티는 가까이 있을 때만 상호작용할 수 있도록 의도적으로 설정할 수 있습니다. 플레이어가 엔티티에서 너무 멀리 떨어져 있으면 커서 옆에 호버 힌트가 표시되지 않습니다.

기본적으로 엔티티는 플레이어의 **아바타가** 엔티티에서 *10미터* 이내에 있을 때만 클릭할 수 있습니다. 이 범위는 포인터 이벤트의 `maxDistance` 속성을 설정해 변경할 수 있습니다.

```ts
// 엔티티 생성
const myEntity = engine.addEntity()

// 엔티티에 PointerEvents 컴포넌트를 추가합니다
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_POINTER,
				maxDistance: 6,
			},
		},
	],
})

// 포인터 이벤트를 처리하는 시스템 구현
engine.addSystem(() => {
	// 포인터 이벤트에 관한 데이터 가져오기
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)

	// 클릭한 위치가 충분히 가까운지 확인
	if (cmd && cmd.hit && cmd.hit.length < 6) {
		// 작업 수행
	}
})
```

위 예시에서는 호버 힌트의 최대 거리를 *6미터*로 설정합니다. 입력 동작을 처리하는 로직에도 같은 규칙이 적용되도록 하세요. 입력 동작의 거리를 가져오는 방법은 [입력 동작의 데이터](#data-from-input-action) 를 참조하세요.

`maxDistance` 는 플레이어의 **아바타**를 기준으로 측정되므로 1인칭과 3인칭에서 동일하게 작동합니다.

대신 **활성 카메라** 를 기준으로 상호작용 거리를 제한하려면 `maxCameraDistance`를 사용하세요. 두 속성을 모두 설정하면 둘 중 하나의 검사만 통과해도 됩니다. 전체 규칙은 [거리 제한](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/register-callback.md#distance-limits) 을 참조하세요.

{% hint style="warning" %}
**📔 참고**: `maxPlayerDistance` 는 `maxDistance`의 더 이상 사용되지 않는 별칭입니다. 두 속성 모두 아바타를 기준으로 거리를 측정하므로, 새 장면에서는 `maxDistance` 를 사용하세요.
{% endhint %}

## 고급 사용자 지정 힌트

&#x20;`PointerEvents`  구성 요소는 플레이어의 커서가 엔티티 위에 머물기 시작할 때 UI 힌트를 쉽게 표시할 수 있게 해줍니다. 일반적으로 힌트는 플레이어가 다른 Decentraland 장면에서 익숙하게 보던 방식과 일관되게 작동하는 것이 좋습니다. 하지만 경우에 따라 상호작용할 수 있다는 점을 사용자 지정 방식으로 알리고 싶을 수도 있습니다. 예를 들어, 플레이어의 커서가 엔티티 위에 머물기 시작할 때 은은한 소리를 재생할 수 있습니다. 커서가 엔티티 위에 있는 동안 엔티티 주위에 빛나는 강조 표시를 보여주고, 커서가 더 이상 엔티티 위에 있지 않을 때 숨길 수도 있습니다. 특정 게임플레이 메커니즘에도 활용할 수 있습니다.

inputSystem.isTriggered() `함수를`  `PointerEventType.PET_HOVER_ENTER`  및 `PointerEventType.PET_HOVER_LEAVE`  이벤트와 함께 사용하면 플레이어의 커서가 엔티티의 콜라이더를 가리키기 시작하거나 가리키기를 멈출 때마다 사용자 지정 동작을 실행할 수 있습니다.

아래 예시에서는 커서가 엔티티의 콜라이더를 가리키기 시작하면 엔티티 크기를 *1.5* 로 키우고, 커서가 엔티티에서 벗어나면 크기를 *1* 로 되돌립니다.

```ts
engine.addSystem(() => {
	const meshEntities = engine.getEntitiesWith(MeshRenderer)
	for (const [entity] of meshEntities) {
		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_HOVER_ENTER,
				entity
			)
		) {
			Transform.getMutable(entity).scale = Vector3.create(1.5, 1.5, 1.5)
		}

		if (
			inputSystem.isTriggered(
				InputAction.IA_POINTER,
				PointerEventType.PET_HOVER_LEAVE,
				entity
			)
		) {
			Transform.getMutable(entity).scale = Vector3.create(1, 1, 1)
		}
	}
})
```

{% hint style="warning" %}
**📔 참고**: 상호작용하려는 모든 엔티티에는 다음 두 가지가 모두 있어야 합니다. [`PointerEvents` 구성 요소](#show-feedback) 및 [충돌체](https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/colliders.md).
{% endhint %}

## 근접 이벤트

커서가 어디를 가리키는지와 관계없이 근접 버튼 입력을 확인하려면 다음을 사용합니다. `PET_DOWN` 을 사용하는 엔티티에서 `InteractionType.PROXIMITY`를 사용하세요. 포인터 이벤트 정의에서 `interactionType` 필드를 `eventInfo`옆에 설정하면 이벤트가 근접 기반으로 지정됩니다.

자세한 내용과 사용 가능한 헬퍼 함수는 [**근접 이벤트**](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/proximity-events.md) 를 참조하세요.

```ts
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_DOWN,
			eventInfo: {
				button: InputAction.IA_PRIMARY,
				hoverText: 'Press E',
				maxDistance: 5
			},
			interactionType: InteractionType.PROXIMITY,
		},
	],
})

engine.addSystem(() => {
	if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN, myEntity)) {
		console.log('Player pressed button near entity')
	}
})
```

pointerEventsSystem.onProximityDown `같은 헬퍼를 사용하면`하나의 엔티티에 커서 핸들러 하나와 근접 핸들러 하나를 동시에 둘 수 있으며, 두 콜백 모두 실행됩니다. 하지만 동일한 핸들러에 서로 다른 버튼 두 개를 등록할 수는 없습니다. 시스템 기반 이벤트에는 이런 제한이 없습니다. 동작마다 항목을 하나씩 정의하면 됩니다. 예를 들어, 커서로 가리킨 뒤 E를 누르거나, 커서로 가리키지 않고 가까이 다가가 E를 눌러 상호작용할 수 있는 엔티티는 다음과 같습니다.

```ts
	PointerEvents.create(myEntity, {
        pointerEvents: [
            {
                eventType: PointerEventType.PET_DOWN,
                eventInfo: {
                    button: InputAction.IA_POINTER,
                    hoverText: '클릭',
                    maxDistance: 15,
                },
                interactionType: InteractionType.CURSOR,
            },
            {
                eventType: PointerEventType.PET_DOWN,
                eventInfo: {
                    button: InputAction.IA_PRIMARY,
                    hoverText: 'Press E',
                    maxDistance: 15,
                },
                interactionType: InteractionType.PROXIMITY,
            },
        ],
    })
    
    engine.addSystem(() => {
        if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_DOWN, myEntity)) {
            console.log('Player clicked at entity')
        }
        if (inputSystem.isTriggered(InputAction.IA_PRIMARY, PointerEventType.PET_DOWN, myEntity)) {
            console.log('Player pressed button near entity')
        }
    })
```

또한 `inputSystem.isTriggered()` 를 `PET_PROXIMITY_ENTER` 및 `PET_PROXIMITY_LEAVE` 이벤트 유형과 함께 사용하면 플레이어가 엔티티의 근접 범위에 들어오거나 나갈 때 반응할 수 있습니다. 사운드나 애니메이션을 재생하는 등 근접 활성화 엔티티에 추가 피드백을 표시할 때 유용합니다.

이 기능을 사용하려면 엔티티에 해당 근접 이벤트 유형이 정의된 `PointerEvents` 컴포넌트가 있어야 합니다.

```ts
PointerEvents.create(myEntity, {
	pointerEvents: [
		{
			eventType: PointerEventType.PET_PROXIMITY_ENTER,
			eventInfo: {
				button: InputAction.IA_POINTER,
				maxDistance: 5,
			},
		},
		{
			eventType: PointerEventType.PET_PROXIMITY_LEAVE,
			eventInfo: {
				button: InputAction.IA_POINTER,
				maxDistance: 5,
				showFeedback: false,
			},
		},
	],
})

engine.addSystem(() => {
	if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_PROXIMITY_ENTER, myEntity)) {
		console.log('Player entered proximity')
	}
	if (inputSystem.isTriggered(InputAction.IA_POINTER, PointerEventType.PET_PROXIMITY_LEAVE, myEntity)) {
		console.log('Player left proximity')
	}
})
```

## 입력 액션 데이터

누른 버튼, 적중한 엔티티, 광선의 방향과 길이 등 입력 액션의 데이터를 가져옵니다. 사용 가능한 모든 데이터에 대한 설명은 ([문서 참조](https://github.com/decentraland/docs/tree/main/README.md))를 확인하세요.

이 데이터를 가져오려면 `inputSystem.getInputCommand`를 사용하세요. 이 함수는 입력 이벤트에 대한 데이터가 포함된 전체 데이터 구조를 반환합니다.

```ts
engine.addSystem(() => {
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)
	if (cmd) {
		console.log(cmd.hit?.entityId)
	}
})
```

쿼리와 일치하는 입력 동작이 없으면 `inputSystem.getInputCommand` 는 *null*을 반환합니다. 로직에서 이 상황을 처리해야 합니다.

### 최대 클릭 거리

최대 거리를 설정해 엔티티를 가까운 거리에서만 클릭할 수 있게 하려면 `hit.length` 이벤트 데이터의 속성을 가져오세요.

```ts
// 포인터 이벤트를 처리하는 시스템 구현
engine.addSystem(() => {
	// 포인터 이벤트에 관한 데이터 가져오기
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)

	// 클릭한 위치가 충분히 가까운지 확인
	if (cmd && cmd.hit && cmd.hit.length < 6) {
		// 작업 수행
	}
})
```

{% hint style="warning" %}
**📔 참고**: 멀리 있는 이벤트를 무시한다면 일관된 동작을 위해 `maxDistance` 매개변수를 `PointerEvents` 컴포넌트에 설정하세요.
{% endhint %}

### 모델 내부의 서로 다른 메시

일반적으로 *.glTF* 3D 모델은 여러 메시로 구성되며, 각 메시에는 고유한 내부 이름이 있습니다. 모든 버튼 이벤트에는 클릭된 메시가 무엇인지에 대한 정보가 포함되므로, 이 정보를 사용해 각 경우에 서로 다른 클릭 동작을 트리거할 수 있습니다.

모델 내부 메시의 이름을 확인하려면 다음과 같은 편집 도구로 3D 모델을 열어야 합니다. [Blender](https://www.blender.org/) 등을 사용할 수 있습니다.

![](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-e2fc19b4253833aec3e79f338177b0c6657fb696%2Fmesh-names.webp?alt=media)

{% hint style="info" %}
**💡 팁**: 클릭된 메시의 이름을 로그에 기록한 다음 콘솔에서 확인할 수도 있습니다.
{% endhint %}

클릭 이벤트가 반환하는 `meshName` 속성은 `hit` 객체의 일부로 제공됩니다.

아래 예시의 하우스 모델에는 `firePlace`라는 메시가 포함되어 있습니다. 해당 메시를 클릭했을 때만 벽난로에 불을 켜려고 합니다.

```ts
engine.addSystem(() => {
	const cmd = inputSystem.getInputCommand(
		InputAction.IA_POINTER,
		PointerEventType.PET_DOWN,
		myEntity
	)
	if (cmd && cmd.hit?.meshName === 'firePlace') {
		// 불 켜기
	}
})
```

{% hint style="warning" %}
**📔 참고**: 이는 포인터 기반 이벤트에만 적용되며 근접 기반 이벤트에는 적용되지 않습니다. 근접 기반 이벤트에서는 모델의 모든 메시가 동시에 플레이어와 가까이 있을 수 있기 때문입니다.
{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/button-events/system-based-events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
