> 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/proximity-events.md). # 근접 이벤트 플레이어가 엔티티의 근접 범위에 들어오거나 벗어날 때를 감지합니다. 근접 상호작용을 사용하면 플레이어가 근처에 들어와 대략 그쪽을 바라볼 때, 커서를 엔티티에 맞추지 않아도 엔티티가 버튼 이벤트에 반응할 수 있습니다. 기존 포인터 이벤트는 레이 캐스팅을 사용합니다. 플레이어는 이벤트를 트리거하기 전에 먼저 커서를 엔티티의 콜라이더에 맞춰야 버튼을 누를 수 있습니다. 반면 근접 이벤트는 플레이어의 커서가 어디를 향하고 있든 상관없이, 아바타 주변의 지정된 영역 안에 있는 엔티티를 확인합니다. 근접 상호작용에서 고려되는 상호작용 영역은 플레이어의 위치에서 앞으로 뻗는, 구의 넓은 삼각형 조각입니다. 포인터 이벤트와 달리 카메라가 향하는 방향과는 무관하게, 아바타가 바라보는 방향이 중요합니다. 더 구체적인 사용자 지정 로직을 설정하려면 원시 데이터를 다루고 다음을 사용해야 할 수 있습니다 [고급](/creator/content-creator-ko/sdk7/interactivity/button-events/advanced-button-events.md) 접근 방식입니다. 엔티티가 상호작용 가능하려면 다음이 있어야 합니다 [collider](/creator/content-creator-ko/sdk7/3d/colliders.md). 참고: [장애물](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#obstacles) 자세한 내용은. ## 근접 콜백 등록 이 `pointerEventsSystem` 근접 이벤트를 위한 헬퍼 함수를 포함하며, 다음과 같은 패턴을 따릅니다: [포인터 이벤트 콜백](/creator/content-creator-ko/sdk7/interactivity/button-events/register-callback.md). ### 근접 버튼 누르기 다음을 사용하세요 `pointerEventsSystem.onProximityDown` 플레이어가 범위 안에 있는 동안 버튼 누름을 감지하기 위해 사용합니다. `onPointerDown`, 이 경우 플레이어가 커서를 엔티티에 맞출 필요가 없습니다. ```ts pointerEventsSystem.onProximityDown( { entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: 'E 누르기', maxDistance: 5, }, }, function () { console.log('플레이어가 엔티티 근처에서 버튼을 눌렀습니다') } ) ``` 다음을 사용하세요 `pointerEventsSystem.onProximityUp` 플레이어가 범위 안에 있을 때 버튼에서 손을 뗐는지 감지하기 위해 사용합니다. ```ts pointerEventsSystem.onProximityUp( { entity: myEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: 'E에서 손 떼기', maxDistance: 5, }, }, function () { console.log('엔티티 근처에서 플레이어가 버튼에서 손을 뗐습니다') } ) ``` {% hint style="warning" %} **📔 참고**: 하나의 `onProximityDown` 와 하나의 `onProximityUp` 는 엔티티당 하나씩만 등록할 수 있습니다. 한 번 추가되면 제거될 때까지 계속 수신합니다. 시스템 루프 안에서 이들을 호출하지 마세요. 그렇게 하면 동작이 계속 덮어써집니다. {% endhint %} ## 근접 이벤트 유형 다음 항목에 두 개의 새 값이 추가되었습니다: `PointerEventType` 열거형에서 사용할 수 있습니다: * `PET_PROXIMITY_ENTER`: 플레이어가 엔티티의 근접 범위 안으로 들어오면 트리거됩니다. * `PET_PROXIMITY_LEAVE`: 플레이어가 엔티티의 근접 범위 밖으로 나가면 트리거됩니다. 이들은 `PointerEvents` 컴포넌트와 `inputSystem` 다음을 위한 [시스템 기반 접근 방식](/creator/content-creator-ko/sdk7/interactivity/button-events/system-based-events.md#proximity-events). 이 방식은 또한 다음을 사용한 근접 버튼 누르기도 지원합니다: `InteractionType.PROXIMITY` 필드. ## 우선순위 여러 엔티티가 범위 안에 있고 같은 입력에 응답할 수 있을 때는 하나만 활성화되며, 기본적으로 가장 가까운 엔티티가 선택됩니다. 다음을 사용하여 `priority` 필드로 어느 쪽이 우선할지 제어합니다. 다음 값을 가진 엔티티가 **더 높은 숫자** 를 우선순위 값으로 가지면 먼저 응답합니다. 플레이어가 근접 상호작용이 있는 엔티티의 범위 안에 있으면서 동시에 플레이어의 커서가 포인터 상호작용이 있는 엔티티를 가리키고 있더라도, 포인터 상호작용이 있는 엔티티가 항상 우선됩니다. 다시 말해, 하나의 엔티티만 활성화됩니다. ```ts pointerEventsSystem.onProximityDown( { entity: doorEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: '문 열기', maxDistance: 5, priority: 2, }, }, function () { console.log('문이 활성화됨') } ) pointerEventsSystem.onProximityDown( { entity: floorEntity, opts: { button: InputAction.IA_PRIMARY, hoverText: '여기를 밟으세요', maxDistance: 5, priority: 1, }, }, function () { console.log('바닥이 활성화됨') } ) ``` 위의 예에서 두 엔티티가 모두 범위 안에 있으면, 문 엔티티가 더 높은 우선순위를 가지므로 응답합니다. 이 `priority` 필드는 다음의 속성에서도 설정할 수 있습니다: `PointerEvents` 컴포넌트를 추가해야 합니다. ## 옵션 근접 헬퍼 함수는 포인터 버전과 동일한 옵션을 사용합니다: * `button`: 감지할 버튼. 다음을 참조하세요: [포인터 버튼](/creator/content-creator-ko/sdk7/interactivity/button-events/click-events.md#pointer-buttons) 에서 지원되는 옵션을 확인하세요. * `maxDistance`: 플레이어의 **아바타** 에서 엔티티까지의 최대 거리(미터). 기본값은 10입니다. * `hoverText`: 플레이어가 엔티티 근처에 있을 때 UI에 표시할 텍스트. * `showHighlight`: true이면 플레이어가 범위 안에 있을 때 엔티티의 가장자리 하이라이트를 표시합니다. *true* 내보냅니다. * `showFeedback`: true이면 엔티티 중심 주변에 호버 피드백을 표시합니다. *true* 내보냅니다. * `priority`: 여러 엔티티가 근처에 있을 때 충돌을 해결합니다. 값이 높을수록 우선합니다. 여러 엔티티의 우선순위 값이 같으면 가장 가까운 엔티티가 선택됩니다. `maxPlayerDistance` 의 더 이상 사용되지 않는 별칭입니다 `maxDistance`. 둘 다 아바타로부터의 거리를 측정하므로 다음을 사용하세요 `maxDistance` 를 사용하세요. ### 범위 안에 있는 것으로 간주되는 기준 근접 이벤트는 다음에서 거리를 측정합니다: **플레이어 캡슐의 중심**, 대략 가슴 높이에서 엔티티 콜라이더의 가장 가까운 지점까지 측정합니다. 이는 커서 클릭의 측정 기준보다 약 1미터 높은 지점이므로, 같은 지점도 각 경로에서 약간 다른 거리로 읽힐 수 있습니다. 거리만으로는 충분하지 않습니다. 근접 이벤트를 발생시키려면 플레이어는 또한 다음 조건을 만족해야 합니다: * 다음을 충족해야 합니다: **바라보고 있어야** 엔티티를, 전방 약 120도의 원뿔 범위 안에서. * 다음이 있어야 합니다: **명확한 시야** 가 있어야 하며, 그 사이에 아무것도 없어야 합니다. {% hint style="warning" %} **📔 참고**: 근접 이벤트는 `maxCameraDistance`. 카메라 위치는 중요하지 않습니다. 아바타의 거리, 바라보는 방향, 시야만 고려됩니다. 다음을 참조하세요: [거리 제한](/creator/content-creator-ko/sdk7/interactivity/button-events/register-callback.md#distance-limits) 커서 이벤트에서 카메라 제한이 작동하는 방식은 {% endhint %} ## 콜백 제거 근접 콜백을 제거하려면 해당 remove 함수를 사용합니다: ```ts pointerEventsSystem.removeOnProximityDown(myEntity) pointerEventsSystem.removeOnProximityUp(myEntity) pointerEventsSystem.removeOnProximityEnter(myEntity) pointerEventsSystem.removeOnProximityLeave(myEntity) ``` 제거되면 엔티티는 더 이상 해당 근접 이벤트에 반응하지 않습니다. ## 근접 진입 및 이탈 다음을 사용하세요 `pointerEventsSystem.onProximityEnter` 플레이어가 엔티티의 근접 범위 안으로 들어올 때 콜백을 실행하고, `pointerEventsSystem.onProximityLeave` 플레이어가 나갈 때 실행합니다. 이는 플레이어에게 추가 피드백 힌트를 표시하는 데 사용할 수 있습니다. 예를 들어, 아이템과 상호작용할 수 있을 때 소리나 애니메이션을 보여줄 수 있습니다. ```ts pointerEventsSystem.onProximityEnter( { entity: myEntity, opts: { button: InputAction.IA_POINTER, hoverText: '근처', maxDistance: 5, }, }, function () { console.log('플레이어가 근접 범위에 들어왔습니다') } ) pointerEventsSystem.onProximityLeave( { entity: myEntity, opts: { button: InputAction.IA_POINTER, hoverText: '근처', maxDistance: 5, }, }, function () { console.log('플레이어가 근접 범위를 벗어났습니다') } ) ``` ## 예시: 근접 문 다음 예시는 플레이어가 근처에 서 있는 상태에서 버튼을 누르면 문을 열거나 닫으며, 문을 향해 조준할 필요가 없습니다. ```ts const doorPivot = engine.addEntity() Transform.create(doorPivot, { position: Vector3.create(3, 0, 4) }) const door = engine.addEntity() GltfContainer.create(door, { src: 'assets/door.glb' }) Transform.create(door, { position: Vector3.create(-1, 0, 0), parent: doorPivot }) let isDoorOpen = false const closedRot = Quaternion.fromEulerDegrees(0, 0, 0) const openRot = Quaternion.fromEulerDegrees(0, 90, 0) pointerEventsSystem.onProximityDown( { entity: door, opts: { button: InputAction.IA_PRIMARY, hoverText: '열기 / 닫기', maxDistance: 5, priority: 1, }, }, function () { if (isDoorOpen) { Tween.setRotate(doorPivot, openRot, closedRot, 700) isDoorOpen = false } else { Tween.setRotate(doorPivot, closedRot, openRot, 700) isDoorOpen = true } } ) ``` --- # 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/proximity-events.md?ask=&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.