> 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" %}
**📔 참고**:\
엔티티가 상호작용 가능하려면, 그것은 **반드시** 가지고 있어야 [collider](/creator/content-creator-ko/sdk7/3d/colliders.md). 참고: [장애물](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#obstacles) 자세한 내용은.
{% endhint %}

## 포인터 누르기

다음을 사용하세요 `pointerEventsSystem.onPointerDown()` 특정 버튼의 누름을 감지하는 데 사용됩니다.

이 문은 두 개의 매개변수가 필요합니다:

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

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

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

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

## 호버 피드백

엔티티와 상호작용할 수 있다는 것을 플레이어에게 어떤 식으로든 알려 주는 것이 매우 중요합니다.

다음과 함께 입력 액션을 등록할 때 `EventsSystem`, 기본적으로 플레이어에게는 다음이 표시됩니다:

* 엔티티의 가장자리 하이라이트
* 커서 근처에, 눌러야 하는 버튼 아이콘과 "상호작용"이라는 문자열이 있는 호버 힌트

이 요소들은 켜고 끄거나 사용자 지정할 수 있습니다.

UI의 호버 피드백은 다음에서 선택한 입력에 따라 다른 아이콘을 표시합니다. `button` 필드입니다. 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('버튼 뗌')
	}
)
```

이 문은 두 개의 매개변수가 필요합니다:

* `데이터`: 다음을 포함하는 객체:
  * `엔티티`: 처리할 엔티티
  * `opts`: 선택적 추가 데이터가 있는 객체:
    * `button`: 수신할 버튼이 무엇인지. 지원되는 옵션은 [포인터 버튼](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#pointer-buttons) 을 참조하세요. 버튼을 지정하지 않으면 앞으로 이동 및 점프 같은 이동 버튼을 포함해 모든 버튼이 수신됩니다.
    * `hoverText`: 호버 피드백 힌트에 표시할 문자열입니다. 기본값은 "Interact"입니다.
    * `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('커서가 엔티티 위 호버를 멈춤')
    }
)
```

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

## 콜백 제거

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

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

제거한 후에는 엔티티의 호버 피드백이 더 이상 표시되지 않아야 하며, 엔티티도 더 이상 상호작용할 수 없어야 합니다.

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

## 근접 상호작용

커서 조준이 아니라 플레이어와의 근접을 기준으로 트리거되는 상호작용은 다음을 참조하세요: [**근접 이벤트**](/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 방식을 사용하고 다음의 값을 설정할 수 있습니다. `button` 필드를 `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 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/register-callback.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.