> 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/advanced-button-events.md).

# 고급 버튼 이벤트

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

씬에서의 상호작용이 다음과 호환되지 않는 사용자 지정 로직을 따라야 한다면 [콜백 등록](/creator/content-creator-ko/sdk7/interactivity/button-events/register-callback.md) 또는 [시스템 기반](/creator/content-creator-ko/sdk7/interactivity/button-events/system-based-events.md) 접근 방식과 호환되지 않는다면, 원시 입력 이벤트 데이터를 직접 다룰 수 있습니다. 이 방식은 가장 어렵지만 가장 유연합니다.

## PointerEventsResult 컴포넌트

엔진이 포인터 이벤트를 감지하면, 클릭된 엔티티에는 `PointerEventsResult` 컴포넌트가 할당됩니다. 이 컴포넌트에는 히트 이벤트에 대한 모든 원시 데이터가 포함되어 있으며, 이전 이벤트의 기록 데이터도 저장됩니다.

...의 헬퍼는 `inputSystem`와 같은 `inputSystem.isTriggered` 또는 `inputSystem.getInputCommand` 은 대부분의 간단한 시나리오에 적합하지만, 히트 이벤트에 대한 더 자세한 정보가 필요하다면, 다음의 원시 데이터를 확인하세요. `PointerEventsResult`.

그 `PointerEventsResult` 컴포넌트는 포인터 이벤트 목록을 보유하며, 각 이벤트마다 하나의 객체가 들어 있습니다. 최대 100개의 이벤트까지 목록을 저장하며, 최신 이벤트는 목록의 끝에 저장됩니다. 목록이 100개 길이에 도달하면 새 이벤트가 들어올 때마다 오래된 이벤트를 버리기 시작합니다.

목록의 각 이벤트에는 다음 데이터가 있습니다:

* `아날로그`: 선택적 숫자이며, 조이스틱 같은 아날로그 입력에서 발생한 이벤트에만 존재하고, 입력의 아날로그 값을 저장합니다.
* `버튼`: 어떤 버튼 ID가 눌렸는지. 이 숫자는 다음과 대응됩니다: `InputAction` 사용 가능한 모든 버튼을 나열하는 enum입니다.
* `state`: 포인터 이벤트의 유형이며, enum `PointerEventType`. *0* 를 뜻합니다 `PointerEventType.PET_UP`, *1* 를 `PointerEventType.PET_DOWN`, *2* 를 `PointerEventType.PET_HOVER_ENTER`, *3* 를 `PointerEventType.PET_HOVER_LEAVE`, *4* 를 `PointerEventType.PET_PROXIMITY_ENTER`, *5* 를 `PointerEventType.PET_PROXIMITY_LEAVE`
* `타임스탬프`: [람포트 타임스탬프](https://en.wikipedia.org/wiki/Lamport_timestamp) 각 버튼 이벤트를 식별하기 위해.

  > 참고: 이 타임스탬프는 현재 시간을 기준으로 번호가 매겨지는 것이 아닙니다. 0에서 시작해 각 이벤트마다 1씩 증가하는 카운터라고 생각하세요.
* `히트`: 히트 이벤트에 대한 다음 데이터를 포함하는 객체입니다:
  * `entityId`: 레이에 맞은 엔티티의 ID 번호입니다.
  * `meshName`: *String* 맞은 3D 모델 내 특정 메시의 내부 이름을 담고 있습니다. 이는 3D 모델이 여러 메시로 구성된 경우 유용합니다.
  * `globalOrigin`: *Vector3* 레이가 시작되는 위치를 위한 것(씬 기준)
  * `방향`: *Vector3* 전역 좌표계에서 광선의 방향 벡터와 함께
  * `위치`: *Vector3* 레이가 맞은 엔티티와 교차한 위치를 위한 것(씬 기준)
  * `length`: 엔티티와의 충돌이 발생한 위치까지, 시작점에서 레이의 길이입니다.
  * `normalHit`: *Vector3* 정규화된 방향 벡터와 함께, 월드 공간에서 히트의 법선 각도를 나타냅니다.

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

function PointerReadingSystem() {
  for (const [entity] of engine.getEntitiesWith(PointerEventsResult)) {
    const events = PointerEventsResult.get(entity)
    for (const event of events) {
      console.log('포인터 이벤트 데이터:', event)
    }
  }
}

engine.addSystem(PointerReadingSystem)
```

## 플레이어 이동 추적

플레이어 이동의 타이밍이 중요한 실시간 멀티플레이어 게임에서는, 제3자 서버를 사실상의 기준(source of truth)으로 사용해 각 플레이어의 위치를 추적하고 싶을 수 있습니다. 버튼 입력을 미리 감지하고, 아바타가 위치를 바꾸기 전에 서버에서 그 효과를 예측하면 응답 시간을 개선할 수 있습니다.

이 접근 방식은 네트워크 지연을 보완하는 데 도움이 되지만, 반드시 불일치가 발생하므로 플레이어의 현재 위치도 정기적으로 조회해 보정해야 합니다. 이러한 예측과 보정의 균형을 맞추려면 상당한 미세 조정이 필요할 수 있습니다.


---

# 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/advanced-button-events.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.