# ProximityPrompt

ProximityPrompt : `Instance`

## Overview

ProximityPrompt는 플레이어가 오브젝트에 가까이 접근했을 때 상호작용 가능한 행동과 입력을 화면에 안내하는 클래스입니다.

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

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

## Properties

### HoldDuration

`number`

프롬프트를 활성화하기 위해 버튼을 눌러야 하는 시간(초)입니다. 0으로 설정하면 버튼을 누르는 즉시 활성화됩니다.

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.HoldDuration = 1.5
```

### MaxActivationDistance

`number`

플레이어 캐릭터가 프롬프트를 활성화할 수 있는 최대 거리입니다.

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.MaxActivationDistance = 5
```

### ObjectText

`string`

프롬프트 UI에 표시되는 오브젝트 이름 텍스트입니다.

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.ObjectText = "Treasure chest"
```

### ActionText

`string`

프롬프트 UI에 표시되는 동작 안내 텍스트입니다.

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.ActionText = "Open"
```

### KeyboardKeyCode

`Enum.KeyCode`

프롬프트를 활성화할 키보드 키를 지정합니다.

모바일 환경에서는 표시되지 않으므로, 스튜디오의 플레이 테스트 환경에서 테스트 편의를 위한 용도로만 사용하는 것을 권장합니다.

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.KeyboardKeyCode = Enum.KeyCode.E
```

### Exclusivity

`Enum.ProximityPromptExclusivity`

같은 버튼에 여러 프롬프트가 존재할 때 동시에 표시 가능한 범위를 지정합니다.

* `OnePerButton`: 동일한 키에 대해 하나의 프롬프트만 표시됩니다.
* `OneGlobally`: 전역적으로 하나의 프롬프트만 표시됩니다.
* `AlwaysShow`: 항상 표시됩니다.

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.Exclusivity = Enum.ProximityPromptExclusivity.OnePerButton
```

### ClickablePrompt

`boolean`

마우스 클릭으로 프롬프트를 활성화할 수 있는지 여부를 지정합니다.

모바일 환경에서는 동작되지 않으며, 스튜디오의 플레이 테스트 환경에서 테스트 편의용으로만 사용하는 것을 권장합니다.

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.ClickablePrompt = true
```

### Enabled

`boolean`

프롬프트의 활성화 여부를 지정합니다. false로 설정하면 프롬프트가 표시되지 않습니다.

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.Enabled = false
```

### UIOffset

`Vector2`

프롬프트 UI의 화면 오프셋(픽셀)을 지정합니다.

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.UIOffset = Vector2.new(0, 50)
```

### RequiresLineOfSight

`boolean`

프롬프트를 활성화하기 위해 오브젝트와의 시선이 확보되어야 하는지 여부를 지정합니다. 

true이면 장애물에 가려진 오브젝트의 프롬프트는 활성화되지 않습니다.

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.RequiresLineOfSight = true
```

## Methods

### InputHoldBegin

홀드 입력이 시작될 때 호출되는 메서드입니다.

#### Parameters

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt:InputHoldBegin()
```

### InputHoldEnd

홀드 입력이 종료될 때 호출되는 메서드입니다.

#### Parameters

#### Return

| `void` |   |
| ------ | - |

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt:InputHoldEnd()
```

## Events

### Triggered

플레이어가 프롬프트를 성공적으로 활성화했을 때 발생하는 이벤트입니다.

프롬프트가 실제로 실행될 때 필요한 로직을 처리하기 위해 사용됩니다.

#### Parameters

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.Triggered:Connect(function()
    print("Prompt triggered!")
end)
```

### TriggerEnded

진행 중이던 프롬프트 트리거가 완료되거나 취소되었을 때 발생하는 이벤트입니다.

#### Parameters

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.TriggerEnded:Connect(function()
    print("Trigger ended.")
end)
```

### PromptButtonHoldBegan

플레이어가 프롬프트 버튼을 누르기 시작했을 때 발생하는 이벤트입니다.

#### Parameters

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.PromptButtonHoldBegan:Connect(function()
    print("Hold began.")
end)
```

### PromptButtonHoldEnded

플레이어가 프롬프트 버튼에서 손을 뗐을 때 발생하는 이벤트입니다.

#### Parameters

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.PromptButtonHoldEnded:Connect(function()
    print("Hold ended.")
end)
```

### PromptShown

프롬프트 UI가 화면에 표시될 때 발생하는 이벤트입니다.

이 이벤트는 클라이언트 환경에서만 동작합니다.

#### Parameters

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.PromptShown:Connect(function()
    print("Prompt is now visible.")
end)
```

### PromptHidden

프롬프트 UI가 화면에서 숨겨질 때 발생하는 이벤트입니다.

이 이벤트는 클라이언트 환경에서만 동작합니다.

#### Parameters

#### Code Samples

```lua
local Workspace = game:GetService("Workspace")
local Prompt = Workspace.Part.ProximityPrompt

Prompt.PromptHidden:Connect(function()
    print("Prompt is now hidden.")
end)
```

## See also

{% content-ref url="../../../manual/studio-manual/object/proximityprompt" %}
[proximityprompt](https://docs.overdare.com/korean/manual/studio-manual/object/proximityprompt)
{% endcontent-ref %}