# ProximityPrompt

ProximityPrompt : `Instance`

## Overview

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

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

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

## Properties

### ActionText

`string`

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

#### Code Samples

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

Prompt.ActionText = "Open"
```

### AutoLocalize

`boolean`

이 ProximityPrompt의 ActionText와 ObjectText에 자동 로컬라이제이션(Auto Translation)을 적용할지 여부를 지정하는 속성으로, AutoLocalize가 true이면 자동 텍스트 수집(ATC) 대상에도 포함됩니다.

기본값은 true이며, false로 설정하면 해당 프롬프트의 텍스트가 번역되지 않습니다.

#### Code Samples

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

Prompt.AutoLocalize = false
```

### 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
```

### Exclusivity

`Enum.ProximityPromptExclusivity`

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

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

#### Code Samples

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

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

### HoldDuration

`number`

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

#### Code Samples

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

Prompt.HoldDuration = 1.5
```

### KeyboardKeyCode

`Enum.KeyCode`

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

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

#### Code Samples

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

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

### 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"
```

### RequiresLineOfSight

`boolean`

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

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

#### Code Samples

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

Prompt.RequiresLineOfSight = true
```

### UIOffset

`Vector2`

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

#### Code Samples

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

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

## 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

### 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)
```

### 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)
```

### 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)
```

### 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)
```

## See also

{% content-ref url="/pages/E4q9fDIX1izygGrINmOv" %}
[ProximityPrompt](/korean/manual/studio-manual/object/proximityprompt.md)
{% endcontent-ref %}


---

# Agent Instructions: 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:

```
GET https://docs.overdare.com/korean/development/api-reference/classes/proximityprompt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.