> 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/register-callback.md).

# 콜백 등록

씬에서 사용자 클릭을 처리하는 방법을 알아보세요.

버튼 이벤트를 처리하는 가장 쉬운 방법은 특정 엔티티에 콜백 함수를 등록하는 것입니다. 해당 엔티티가 특정 버튼으로 상호작용될 때마다 콜백 함수가 호출됩니다.

여러 비슷한 엔티티에 같은 동작을 추가해야 한다면, 다음을 사용하는 것을 고려해 보세요 [시스템 기반의](/creator/content-creator-ko/sdk7/interactivity/button-events/system-based-events.md) 엔티티마다 콜백을 추가하는 대신 접근 방식입니다. 시스템 기반 접근 방식은 비슷한 엔티티 목록을 순회할 때 더 효율적일 수 있습니다.

Register callback 방식은 단일 엔티티에 영향을 주는 동작을 설명하고 싶을 때 특히 유용합니다. 더 직관적이기 때문입니다.

{% hint style="warning" %}
**📔 참고**:\
엔티티가 상호작용 가능하려면, 그것은 **반드시** 가져야 합니다 [콜라이더](/creator/content-creator-ko/sdk7/3d/colliders.md). 자세한 내용은 [장애물](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#obstacles) 자세한 내용은 다음을 참조하세요.
{% endhint %}

## 포인터 누름

사용: `pointerEventsSystem.onPointerDown()` 특정 버튼의 누름을 감지합니다.

이 문장은 두 개의 매개변수를 필요로 합니다:

* `데이터`: 다음을 포함하는 객체:
  * `entity`: 처리할 엔티티
  * `opts`: 선택적 추가 데이터를 포함하는 객체:
    * `버튼`: 어떤 버튼을 감지할지 지정합니다. 참조 [포인터 버튼](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#pointer-buttons) 지원되는 옵션을 확인하세요. 버튼을 지정하지 않으면 앞으로 이동 및 점프 같은 이동 버튼을 포함한 모든 버튼을 감지합니다.
    * `maxDistance`: 엔티티와 플레이어의 **아바타**, 미터 단위입니다. 기본값은 10입니다. 참조 [거리 제한](#distance-limits).
    * `maxCameraDistance`: 엔티티와 **현재 활성 카메라의**, 미터 단위입니다. 기본적으로 설정되지 않습니다. 참조 [거리 제한](#distance-limits).
    * `hoverText`: 호버 피드백 힌트에 표시할 문자열입니다. 기본값은 "상호작용"입니다.
    * `showFeedback`: false이면 이 엔티티의 호버 힌트와 가장자리 강조 표시는 모두 숨깁니다. *true* 항목만 내보냅니다.
    * `showHighlight`: true이면 플레이어가 커서를 엔티티 위에 올렸을 때 가장자리 강조 표시를 볼 수 있습니다. *true* 기본값입니다. 이 값은 다음의 경우에만 고려됩니다. `showFeedback` 일 때 *true*.
* `cb`: 엔티티를 가리키는 동안 버튼 누름 이벤트가 발생할 때마다 실행할 콜백 함수

```ts
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: '클릭' },
	},
	function () {
		console.log('엔티티를 클릭했습니다')
	}
)
```

위 명령은 콜백 함수를 등록된 상태로 유지하며, 관련 버튼 이벤트가 발생할 때마다 호출됩니다. 콜백은 동기 함수여야 한다는 점에 유의하세요; `async` 함수는 여기서 지원되지 않으며 오류가 발생합니다.

{% hint style="warning" %}
**📔 참고**:\
하나만 `pointerEventsSystem.onPointerDown` 엔티티당 하나만 등록할 수 있습니다. 추가되면 리스너가 제거될 때까지 이벤트를 계속 감지합니다. 포인터 이벤트 동작을 계속 덮어쓰게 되므로 시스템 안에서 이를 반복적으로 실행하지 마세요.
{% endhint %}

## 호버 피드백

플레이어에게 엔티티와 상호작용할 수 있다는 어떤 형태의 표시를 주는 것은 매우 중요합니다.

다음을 사용해 입력 동작을 등록할 때 `EventsSystem`, 기본적으로 플레이어는 다음을 보게 됩니다:

* 엔티티의 가장자리 강조 표시
* 커서 근처에, 눌러야 하는 버튼의 아이콘과 "상호작용"이라고 적힌 문자열이 있는 호버 힌트가 표시됩니다.

이러한 요소는 켜고 끌 수 있으며 사용자 지정할 수 있습니다.

UI의 호버 피드백은 다음에서 선택한 입력에 따라 다른 아이콘을 표시합니다. `버튼` 필드입니다. PC에서는 다음이 있는 아이콘을 표시합니다 `E` 에 대해 `InputAction.IA_PRIMARY`, 그리고 `F` 에 대해 `InputAction.IA_SECONDARY`, 그리고 마우스는 `InputAction.IA_POINTER`.

문자열을 변경하려면 다음의 값을 변경하세요 `hoverText` 값입니다. 이 문자열은 짧게 유지하세요. 그래야 빠르게 읽을 수 있고 화면에서 너무 방해되지 않습니다.

```ts
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: '문 열기' },
	},
	function () {
		// 문 열기
	}
)
```

호버 힌트를 숨기되 가장자리 강조 표시는 남기려면 다음의 값을 설정하세요 `hoverText` 를 ""로.

```ts
pointerEventsSystem.onPointerDown(
  {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: ''}},
  function () {
    console.log("깜짝 상호작용 항목을 클릭했습니다")
  }
)
```

가장자리 강조 표시는 숨기되 호버 힌트는 남기려면 다음을 설정하세요 `showHighlight` 를 *false*.

```ts
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: {
			button: InputAction.IA_PRIMARY,
			hoverText: '문 열기',
			showHighlight: false,
		},
	},
	function () {
		console.log('비밀 문을 열었습니다')
	}
)
```

호버 힌트와 가장자리 강조 표시를 모두 숨기려면 다음을 설정하세요 `showFeedback` 를 *false*. 이렇게 하면 커서에는 아이콘, 텍스트, 가장자리 강조 표시가 아무것도 표시되지 않습니다.

```ts
pointerEventsSystem.onPointerDown(
  {entity: myEntity, opts: { button: InputAction.IA_PRIMARY, showFeedback: false}},
  function () {
    console.log("비밀 문을 열었습니다")
  }
)
```

### 기존 피드백 변경

다음을 사용해 입력 동작을 등록할 때 `EventsSystem`, 이는 다음을 생성하는 것입니다 `PointerEvents` 구성 요소를 생성하여 뒤에서 상호작용 가능한 엔티티에 추가하는 것입니다. 이 구성 요소는 UI 호버 힌트의 동작을 처리합니다. 호버 피드백의 동작을 변경하려면 이 구성 요소를 수정하세요. 참조 [피드백 표시](/creator/content-creator-ko/sdk7/interactivity/button-events/system-based-events.md#show-feedback) 이 구성 요소를 다루는 방법에 대한 자세한 내용은

```ts
const hoverFeedback = PointerEvents.getMutable(myEntity)

if (hoverFeedback.pointerEvents[0]?.eventInfo) {
	hoverFeedback.pointerEvents[0].eventInfo.hoverText = '문 닫기'
}
```

## 거리 제한

기본적으로 플레이어는 자신의 **아바타** 가 엔티티로부터 10미터 이내에 있을 때만 엔티티와 상호작용할 수 있습니다. 플레이어가 너무 멀리 떨어져 있으면 엔티티의 강조 효과가 초록색이 아니라 빨간색으로 바뀌며, 포인터 이벤트는 발생하지 않습니다.

사용: `maxDistance` 해당 범위를 변경하려면:

```ts
// 플레이어의 아바타가 5미터 이내에 있을 때만 클릭 가능
pointerEventsSystem.onPointerDown(
	{ entity: myEntity, opts: { maxDistance: 5 } },
	function () {
		console.log('엔티티를 클릭했습니다')
	}
)
```

### 카메라 거리로 제한

`maxCameraDistance` 다음을 기준으로 측정합니다 **현재 활성화된 카메라** 아바타 대신입니다. 장면에서 플레이어와 떨어진 곳에 배치된 카메라를 사용하고 있으며, 카메라가 볼 수 있는 것을 기준으로 엔티티를 클릭 가능하게 하고 싶을 때 유용합니다. [가상 카메라로 전환합니다.](/creator/content-creator-ko/sdk7/3d/camera.md#using-virtual-cameras) 플레이어로부터 떨어진 곳에 배치되어 있으며, 카메라가 볼 수 있는 것을 기준으로 엔티티를 클릭 가능하게 하고 싶을 때 유용합니다.

```ts
// 활성 카메라가 15미터 이내에 있을 때만 클릭 가능
pointerEventsSystem.onPointerDown(
	{ entity: myEntity, opts: { maxCameraDistance: 15 } },
	function () {
		console.log('엔티티를 클릭했습니다')
	}
)
```

### 두 제한이 결합되는 방식

두 옵션은 서로 독립적인 검사입니다. 어떤 검사가 실행되는지는 어떤 값을 설정했는지에 따라 달라집니다:

| 설정한 내용                | 플레이어에게 필요한 것                 |
| --------------------- | ---------------------------- |
| 둘 다 아님                | 아바타가 10미터 이내 (기본값)           |
| `maxDistance` 만       | 아바타가 `maxDistance`           |
| `maxCameraDistance` 만 | 카메라가 `maxCameraDistance`     |
| 둘 다                   | **둘 중 하나** 검사 하나만 통과해도 충분합니다 |

둘 다 설정하는 것은 "걸어서 다가갈 만큼 충분히 가깝고, **또는** 또렷하게 볼 만큼 충분히 가깝다"라고 말하는 방법입니다:

```ts
// 아바타가 3미터 이내이거나 카메라가 20미터 이내일 때 클릭 가능
pointerEventsSystem.onPointerDown(
	{ entity: myEntity, opts: { maxDistance: 3, maxCameraDistance: 20 } },
	function () {
		console.log('엔티티를 클릭했습니다')
	}
)
```

{% hint style="warning" %}
**📔 참고**: `maxCameraDistance` 필요합니다 `@dcl/sdk` 7.28.0 이상 버전이 필요합니다. 이에 대한 지원은 이미 Bevy 기반 탐색기에서 사용할 수 있습니다. 지금 당장 모든 클라이언트에서 장면이 동일하게 동작해야 한다면, 다음에 의존하고 `maxDistance` 그리고 `maxCameraDistance` 이를 개선 사항으로 간주하세요.
{% endhint %}

### maxPlayerDistance는 더 이상 사용되지 않습니다

`maxPlayerDistance` 는 다음의 더 이상 사용되지 않는 별칭입니다: `maxDistance`: 둘 다 아바타로부터의 거리를 측정합니다. 새 장면에서는 다음을 사용하세요 `maxDistance` 새 장면에서

장면이 둘 다 설정하면 **더 큰** 두 값 중 더 큰 값이 아바타 거리 제한으로 사용됩니다.

## 포인터 놓기

사용: `pointerEventsSystem.onPointerUp` 지정된 플레이어가 엔티티를 가리키는 동안 버튼을 놓을 때 호출될 콜백 함수를 등록합니다.

```ts
pointerEventsSystem.onPointerUp(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_PRIMARY, hoverText: '버튼 놓기' },
	},
	function () {
		console.log('버튼을 놓음')
	}
)
```

이 문장은 두 개의 매개변수를 필요로 합니다:

* `데이터`: 다음을 포함하는 객체:
  * `entity`: 처리할 엔티티
  * `opts`: 선택적 추가 데이터를 포함하는 객체:
    * `버튼`: 어떤 버튼을 감지할지 지정합니다. 참조 [포인터 버튼](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#pointer-buttons) 지원되는 옵션을 확인하세요. 버튼을 지정하지 않으면 앞으로 이동 및 점프 같은 이동 버튼을 포함한 모든 버튼을 감지합니다.
    * `hoverText`: 호버 피드백 힌트에 표시할 문자열입니다. 기본값은 "상호작용"입니다.
    * `showFeedback`: false이면 이 엔티티의 호버 힌트를 숨깁니다. *true* 항목만 내보냅니다.
    * `maxDistance`: 플레이어의 아바타가 엔티티로부터 얼마나 떨어져 있어도 상호작용할 수 있는지, 미터 단위입니다. 기본값은 10입니다. 플레이어가 너무 멀면 호버 피드백이 표시되지 않으며 포인터 이벤트도 작동하지 않습니다. 참조 [거리 제한](#distance-limits).
* `cb`: 엔티티를 가리키는 동안 버튼 놓기 이벤트가 발생할 때마다 실행될 콜백 함수

동일한 엔티티에는 두 개의 서로 다른 콜백을 등록할 수 있습니다. 하나는 `pointerEventsSystem.onPointerDown` 그리고 하나는 `pointerEventsSystem.onPointerUp`. 엔티티에는 각 [여러 버튼 처리](#handle-multiple-buttons) 하나의 동일한 콜백에서 서로 다른 버튼을 감지합니다.

{% hint style="warning" %}
**📔 참고**: 버튼 놓기 이벤트의 호버 피드백은 버튼이 현재 눌린 상태일 때만 표시됩니다. 플레이어가 버튼을 누르지 않은 채 엔티티를 가리키면 피드백이 보이지 않으며, 있으면 버튼 누름 이벤트의 피드백만 표시됩니다.
{% endhint %}

## 호버 진입 및 이탈

사용: `pointerEventsSystem.onPointerHoverEnter` 플레이어의 커서가 엔티티를 가리키기 시작할 때 콜백을 실행하고 `pointerEventsSystem.onPointerHoverLeave` 커서가 더 이상 그것을 가리키지 않을 때

```ts
pointerEventsSystem.onPointerHoverEnter(
    {
        entity: myEntity,
        opts: { button: InputAction.IA_POINTER },
    },
    function () {
        console.log('커서가 엔티티 위에 호버를 시작했습니다')
    }
)

pointerEventsSystem.onPointerHoverLeave(
    {
        entity: myEntity,
        opts: { button: InputAction.IA_POINTER },
    },
    function () {
        console.log('커서가 엔티티 위에서 호버를 중지했습니다')
    }
)
```

이러한 콜백은 플레이어가 엔티티를 조준할 때 소리를 재생하거나 엔티티에 애니메이션을 적용하는 등 사용자 지정 호버 효과에 유용합니다.

## 콜백 제거

콜백 함수를 제거하려면 해당 remove 함수를 사용하세요:

```ts
pointerEventsSystem.removeOnPointerDown(myEntity)
pointerEventsSystem.removeOnPointerUp(myEntity)
pointerEventsSystem.removeOnPointerHoverEnter(myEntity)
pointerEventsSystem.removeOnPointerHoverLeave(myEntity)
```

제거되면 엔티티의 호버 피드백은 더 이상 표시되지 않으며, 엔티티도 더 이상 상호작용 가능하지 않아야 합니다.

각 remove 함수는 대응하는 register 함수가 추가한 항목만 제거합니다. 동일한 콜백을 반복적으로 등록하고 제거해도 엔티티에 오래된 항목이 남지 않습니다.

## 근접 상호작용

커서 조준이 아니라 플레이어의 근접에 따라 트리거되는 상호작용은 다음을 참조하세요 [**근접 이벤트**](/creator/content-creator-ko/sdk7/interactivity/button-events/proximity-events.md). 다음은 `pointerEventsSystem` 에는 동일한 도우미 함수(`onProximityDown`, `onProximityUp`, `onProximityEnter`, 그리고 `onProximityLeave`)가 있으며, 이 페이지에서 설명한 함수와 동일한 패턴을 따릅니다.

하나의 엔티티는 같은 이벤트 유형에 대해 커서 핸들러와 근접 핸들러를 모두 가질 수 있습니다. 두 콜백 모두 실행되며, 각자 자신의 조건이 충족될 때 실행됩니다.

### 입력 동작의 데이터

눌린 버튼, 맞은 엔티티, 레이의 방향과 길이 등 입력 동작에서 데이터를 가져옵니다. 다음을 참조하세요 ([문서 보기](https://github.com/decentraland/docs/tree/main/README.md))에서 사용 가능한 모든 데이터에 대한 설명을 볼 수 있습니다.

이 데이터를 가져오려면 콜백 함수에 매개변수를 전달하세요. 이 매개변수에는 입력 이벤트에 대한 데이터가 들어 있는 전체 데이터 구조가 포함됩니다.

```ts
pointerEventsSystem.onPointerDown(
	{ entity: myEntity, opts: { button: InputAction.IA_PRIMARY } },
	function (cmd) {
		console.log(cmd.hit?.entityId)
	}
)
```

### 여러 버튼 처리

하나 이상 등록할 수 없습니다 `onPointerDown` 단일 엔티티에 대해. 이상적으로는 다음을 사용해야 합니다 [시스템 기반의](/creator/content-creator-ko/sdk7/interactivity/button-events/system-based-events.md) 이 접근 방식은 원하는 만큼 다양한 입력을 처리할 수 있고, 각 버튼에 대해 UI 호버 피드백 힌트를 표시할 수 있기 때문입니다.

대안으로, Register callback 방식을 사용하고 다음을 설정할 수 있습니다 `버튼` 필드를 다음으로 `InputAction.IA_ANY`.

```ts
pointerEventsSystem.onPointerDown(
  {entity: myEntity, opts: { button: InputAction.IA_ANY}},
  function (cmd) {
      if(cmd.button === InputAction.IA_POINTER){
        // X 수행
      } else if (cmd.button === InputAction.IA_PRIMARY){
        // Y 수행
      }
  }
)
```

이 접근 방식은 호버 힌트가 하나의 문자열만 표시하고 어떤 동작을 활성화할지 지정하지 않기 때문에 이상적이지 않습니다. 또한 이렇게 하면 이동 키를 포함한 모든 입력 동작에 대해 콜백 함수가 실행되므로, 관심 있는 동작만 필터링해야 합니다.


---

# 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/interactivity/button-events/register-callback.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.