ProximityPrompt

ProximityPrompt : Instance

Overview

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

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

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

Properties

ActionText

string

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

Code Samples

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

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

Prompt.AutoLocalize = false

ClickablePrompt

boolean

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

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

Code Samples

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

Prompt.ClickablePrompt = true

Enabled

boolean

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

Code Samples

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

Prompt.Enabled = false

Exclusivity

Enum.ProximityPromptExclusivity

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

• OnePerButton: 동일한 키에 대해 하나의 프롬프트만 표시됩니다.

• OneGlobally: 전역적으로 하나의 프롬프트만 표시됩니다.

• AlwaysShow: 항상 표시됩니다.

Code Samples

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

Prompt.Exclusivity = Enum.ProximityPromptExclusivity.OnePerButton

HoldDuration

number

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

Code Samples

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

Prompt.HoldDuration = 1.5

KeyboardKeyCode

Enum.KeyCode

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

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

Code Samples

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

Prompt.KeyboardKeyCode = Enum.KeyCode.E

MaxActivationDistance

number

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

여러 ProximityPrompt가 겹쳐 있는 경우, 플레이어와의 거리가 아닌 먼저 감지된 Prompt를 기준으로 UI 표시 및 상호작용을 처리합니다. Prompt 중첩 시 의도하지 않은 대상이 선택될 수 있으므로 중첩 배치를 피하는 것을 권장합니다.

Code Samples

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

Prompt.MaxActivationDistance = 5

ObjectText

string

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

Code Samples

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

Prompt.ObjectText = "Treasure chest"

RequiresLineOfSight

boolean

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

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

Code Samples

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

Prompt.RequiresLineOfSight = true

UIOffset

Vector2

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

Code Samples

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

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

Methods

InputHoldBegin

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

Parameters

Return

void

Code Samples

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

Prompt:InputHoldBegin()

InputHoldEnd

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

Parameters

Return

void

Code Samples

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

Prompt:InputHoldEnd()

Events

PromptButtonHoldBegan

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

Parameters

Player player	버튼을 누르기 시작한 플레이어입니다.

Code Samples

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

Prompt.PromptButtonHoldBegan:Connect(function(player)
    print("Hold began.", player.Name)
end)

PromptButtonHoldEnded

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

Parameters

Player player	버튼에서 손을 뗀 플레이어입니다.

Code Samples

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

Prompt.PromptButtonHoldEnded:Connect(function(player)
    print("Hold ended.", player.Name)
end)

PromptHidden

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

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

Parameters

Code Samples

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

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

PromptShown

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

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

Parameters

Enum.ProximityPromptInputType inputType	프롬프트를 표시시킨 입력 유형입니다.

Code Samples

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

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

Triggered

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

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

Parameters

Player player	프롬프트를 활성화한 플레이어입니다.

Code Samples

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

Prompt.Triggered:Connect(function(player)
    print("Prompt triggered!", player.Name)
end)

TriggerEnded

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

Parameters

Player player	트리거를 진행하고 있던 플레이어입니다.

Code Samples

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

Prompt.TriggerEnded:Connect(function(player)
    print("Trigger ended.", player.Name)
end)

See also

ProximityPrompt