# ProximityPrompt

## 개요

ProximityPrompt는 플레이어가 오브젝트에 가까이 접근했을 때 상호작용 가능한 행동과 입력을 화면에 안내하는 기능입니다. 플레이어는 표시된 입력 키를 눌러 오브젝트와 상호작용할 수 있습니다.

이 기능은 플레이어에게 어떤 오브젝트가 상호작용 가능한지 직관적으로 알려주는 UI 요소로 사용됩니다. 상자, 문, 자원, NPC, 장치 등 다양한 오브젝트에 적용할 수 있으며, 탐험·RPG·생존 장르의 게임에서 널리 활용됩니다.

ProximityPrompt는 단순 입력(Press) 과 홀드 입력(Hold) 두 가지 방식의 상호작용을 모두 지원합니다.

## 사용 방법

ProximityPrompt는 BasePart, Attachment, Model의 하위에 배치하여 사용할 수 있습니다.

플레이어 캐릭터가 프롬프트가 설정된 오브젝트의 활성화 거리(MaxActivationDistance) 안에 들어오면 입력을 유도하는 UI가 자동으로 표시됩니다. 

<figure><img src="https://2697870212-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhRPi87oM9ttlk5nyu7L7%2Fuploads%2FurrIcHoFSSufBqXDg14Z%2Fimage.png?alt=media&#x26;token=02b6dab8-4fc9-482d-b04a-fb7e285fea51" alt=""><figcaption></figcaption></figure>

플레이어는 표시된 입력 키를 눌러 오브젝트와 상호작용할 수 있으며, 입력 방식은 플랫폼에 따라 자동으로 전환됩니다.

* PC : 키보드 입력
* 모바일 : 화면 터치 입력

### 프로퍼티 구성

<table><thead><tr><th width="247">프로퍼티</th><th>설명</th></tr></thead><tbody><tr><td>Hold Duration</td><td>버튼을 누르고 있어야 하는 시간(초)을 설정합니다. HoldDuration이 0보다 크면 버튼을 일정 시간 동안 눌러야 상호작용이 실행됩니다.</td></tr><tr><td>Max Activation Distance</td><td>프롬프트가 표시되는 최대 거리입니다.</td></tr><tr><td>Object Text</td><td>상호작용 대상 오브젝트의 이름을 표시하는 텍스트입니다.</td></tr><tr><td>Action Text</td><td>플레이어에게 표시되는 상호작용 텍스트입니다. (예: Open, Talk, Mine)</td></tr><tr><td>Keyboard Key Code</td><td>PC 환경에서 상호작용에 사용할 키보드 입력 키를 지정합니다.</td></tr><tr><td>Exclusivity</td><td>동시에 표시되는 프롬프트의 표시 규칙을 설정합니다. Exclusivity 설정에 따라 여러 프롬프트가 동시에 표시되지 않을 수 있습니다.</td></tr><tr><td>Clickable Prompt</td><td>PC 환경에서 프롬프트 UI를 클릭해서 상호작용할 수 있는지 여부를 설정합니다.</td></tr><tr><td>Enabled</td><td>프롬프트의 표시 여부를 설정합니다.</td></tr><tr><td>UIOffset</td><td>프롬프트 UI의 화면 위치 오프셋을 설정합니다.</td></tr><tr><td>Requires Line Of Sight</td><td>카메라와 오브젝트 사이가 가려져 있으면 프롬프트를 숨길지 여부를 설정합니다.</td></tr></tbody></table>

### 스크립트 기능

스크립트를 사용하면 프롬프트가 트리거되었을 때 특정 동작을 실행할 수 있습니다.

```lua
local Prompt = script.Parent

local function OnTriggered(player)
    print(player.Name .. " Triggered")
end
Prompt.Triggered:Connect(OnTriggered)

local function OnTriggerEnded(player)
    print(player.Name .. " TriggerEnded")
end
Prompt.TriggerEnded:Connect(OnTriggerEnded)
```

자세히 알아보기

{% content-ref url="../../../development/api-reference/classes/proximityprompt" %}
[proximityprompt](https://docs.overdare.com/korean/development/api-reference/classes/proximityprompt)
{% endcontent-ref %}

{% content-ref url="../../../development/api-reference/classes/proximityprompservice" %}
[proximityprompservice](https://docs.overdare.com/korean/development/api-reference/classes/proximityprompservice)
{% endcontent-ref %}

## 주의 사항

* ProximityPrompt는 BasePart, Attachment, Model의 하위에 배치되어야 정상적으로 동작합니다.
* 프롬프트 표시 여부는 플레이어와 오브젝트 중심점 사이의 거리를 기준으로 계산됩니다.
* Studio에서 디바이스 에뮬레이터가 활성화된 경우 또는 모바일 디바이스에서 실행되는 경우, KeyboardKeyCode와 ClickablePrompt 설정은 동작에 영향을 주지 않습니다. 모바일 환경에서는 터치 입력 기반으로 프롬프트가 표시되고 상호작용이 이루어집니다.

## 활용 예시

* 플레이어가 월드에 배치된 보물 상자에 가까이 접근하면 Open 프롬프트가 표시되고, 입력 키를 눌러 상자를 열어 아이템이나 보상을 획득할 수 있습니다.
* 플레이어가 광석 오브젝트 앞에 다가가면 Mine 프롬프트가 표시되어 채광을 수행하고 자원을 획득할 수 있습니다.
* 플레이어가 NPC 근처에 접근하면 Talk 프롬프트가 표시되어 대화를 시작하거나 퀘스트, 상점 등의 상호작용을 진행할 수 있습니다.
* 플레이어가 문이나 장치 앞에 접근하면 Open 또는 Activate 프롬프트가 표시되어 문을 열거나 장치를 작동시킬 수 있습니다.