Proximity Prompts

In the Interactive Buttons course, you learned how to create on-screen buttons for menus, interface actions, and more. Interactivity can also be handled through prompts that appear when users approach in-game objects like doors, switches, or even non-playable characters.

Starter Project

The remainder of this tutorial uses the Dungeon Delve project as a showcase. To follow along, open it in Studio before proceeding.

Creating a Prompt

On-screen prompts are generated by a ProximityPrompt object parented to an Attachment, BasePart, or Model.

  1. Select the PrisonDoor model in the 3D view or from the Explorer (WorkspacePromptObjectsPrisonDoor).

  2. Expand its tree and select the Door object.

  3. Placing a prompt on an Attachment gives you more control on where the point of interaction occurs, versus placing it directly on the part/model. Insert a new Attachment and rename it to PromptAttachment.

  4. Locate the new attachment's Position property and set it to -2.25, -0.5, -0.5. This will move it in front of the door's key hole.

  5. Hover over PromptAttachment and insert a new ProximityPrompt object.

Prompt Appearance

Prompts consist of three primary elements, each of which can be controlled by the following properties:

  • ObjectText — An optional name for the object being interacted with.
  • ActionText — An optional action name shown to the user.
  • KeyboardKeyCode — The keyboard key which will trigger the prompt.
  • GamepadKeyCode — The gamepad button which will trigger the prompt.

To customize the appearance of the prison door prompt, make the following changes:

  1. In the Properties window, locate the ObjectText property and type in Door.

  2. For the ActionText property, type in Pick Lock.

Activation Distance

Prompts appear when the user's character moves within the defined MaxActivationDistance range of the prompt object's parent.

The default value works well in most cases, but you can push user interaction closer to the lock by changing MaxActivationDistance to 4.

Hold Duration

The HoldDuration property value determines how quickly the prompt's action is triggered, in seconds. Since this door must be picked to unlock it, change the HoldDuration property to 4.

Responding to User Input

The best way to detect prompt events is through ProximityPromptService — this lets you detect events centrally without attaching a script to each prompt object.

A basic framework is as follows:

1local ProximityPromptService = game:GetService("ProximityPromptService")
3-- Detect when prompt is triggered
4local function onPromptTriggered(promptObject, player)
8-- Detect when prompt hold begins
9local function onPromptHoldBegan(promptObject, player)
13-- Detect when prompt hold ends
14local function onPromptHoldEnded(promptObject, player)
18-- Connect prompt events to handling functions
Event Description
PromptTriggered Fires when a user interacts with a prompt (after the duration for a prompt with non-zero HoldDuration).
PromptButtonHoldBegan Fires when a user begins interacting with a prompt of non-zero HoldDuration.
PromptButtonHoldEnded Fires when a user stops interacting with a prompt of non-zero HoldDuration

In the Dungeon Delve project, these events are managed by the PromptEvents script within ServerScriptService.

Inside the script, the events above simply call functions within the ObjectActions ModuleScript, also located in ServerScriptService.

1local ProximityPromptService = game:GetService("ProximityPromptService")
2local ServerScriptService = game:GetService("ServerScriptService")
4local ObjectActions = require(ServerScriptService.ObjectActions)
6-- Detect when prompt is triggered
7local function onPromptTriggered(promptObject, player)
8 ObjectActions.promptTriggeredActions(promptObject, player)
11-- Detect when prompt hold begins
12local function onPromptHoldBegan(promptObject, player)
13 ObjectActions.promptHoldBeganActions(promptObject, player)
16-- Detect when prompt hold ends
17local function onPromptHoldEnded(promptObject, player)
18 ObjectActions.promptHoldEndedActions(promptObject, player)
21-- Connect prompt events to handling functions

Proximity prompts are a convenient and customizable solution for in-game object interaction. Check out the ProximityPrompt and ProximityPromptService reference pages for even more ways to control prompt behavior, and explore other interactive objects in Dungeon Delve for creative inspiration.