ClickDetector
ClickDetector allows Scripts and LocalScripts to receive pointer input on 3D objects through their MouseClick event. They work when parented to BasePart, Model, or Folder objects. They detect basic mouse events: enter, leave, left click and right click. Touch input on TouchEnabled devices also fires click events.
The default control scripts bind ButtonR2 to interact with ClickDetectors using ContextActionService:BindActivate(), which can also be used to override this. When using gamepads, the center dot triggers MouseHoverEnter and MouseHoverLeave. The bound activation button fires MouseClick.
MaxActivationDistance can be used to limit the distance a player may be from a click detector before it is no longer clickable.
ClickDetector events fire on both the client and the server. Since a LocalScript will only run if it descends from a Player or player Character, it's usually not useful to put a LocalScript inside a ClickDetector, since the script won't run or the object won't be clickable. If you need a LocalScript to detect ClickDetector events, StarterPlayerScripts may be a better place instead.
Input Priority
If multiple ClickDetectors may detect user input, only the deepest will fire events. If two ClickDetectors are siblings, the first will take priority.
If an action bound with ContextActionService uses the same input as a ClickDetector, the action bound with ContextActionService will take priority over the click detector's events.
UserInputService.InputBegan will fire before ClickDetector events.
Code Samples
Place this code inside a Script inside a ClickDetector. The code sample creates a reference to the parent and defines a function to show a message that greets a player. Finally, it connects the MouseClick event to the defined function.
local clickDetector = script.Parent
local function onClicked(player)
-- Show a message to the player
local msg = Instance.new("Message")
msg.Parent = player:FindFirstChild("PlayerGui")
msg.Text = "Hello, " .. player.Name
wait(2.5)
msg:Destroy()
end
-- Connect the function to the MouseClick event
clickDetector.MouseClick:Connect(onClicked)This code sample will allow a part to be clicked to toggle its anchored property. When toggled, the visual appearance of the part is updated (red means anchored, yellow means free).
local part = script.Parent
-- Create a ClickDetector so we can tell when the part is clicked
local cd = Instance.new("ClickDetector", part)
-- This function updates how the part looks based on its Anchored state
local function updateVisuals()
if part.Anchored then
-- When the part is anchored...
part.BrickColor = BrickColor.new("Bright red")
part.Material = Enum.Material.DiamondPlate
else
-- When the part is unanchored...
part.BrickColor = BrickColor.new("Bright yellow")
part.Material = Enum.Material.Wood
end
end
local function onToggle()
-- Toggle the anchored property
part.Anchored = not part.Anchored
-- Update visual state of the brick
updateVisuals()
end
-- Update, then start listening for clicks
updateVisuals()
cd.MouseClick:Connect(onToggle)Summary
Properties
Sets the cursor icon to display when the mouse is hovered over the parent of this ClickDetector or DragDetector.
Maximum distance between a character and the ClickDetector or DragDetector for the player to be able to interact with it.
Events
Fires when a player interacts with the parent of a ClickDetector or DragDetector.
Fires when the parent of a ClickDetector or DragDetector is hovered over by a player.
Fires when a player's cursor hovers off the parent of a ClickDetector or DragDetector.
Fires when a player right clicks their mouse cursor on a ClickDetector or DragDetector.
Properties
CursorIcon
Sets the cursor icon to display when the mouse is hovered over the parent of this ClickDetector or DragDetector. If this property is left blank, the detector will use the default icon.
To change the cursor icon, set this property to the asset ID of the image you'd like to use.
MaxActivationDistance
This property controls the maximum distance, in studs, between a Character and the ClickDetector or DragDetector for the player to be able to interact with it. For instance, a character within 10 studs of a ClickDetector or DragDetector with a max activation distance of 5 would not be able to use the detector because they are out of range.
Methods
Events
MouseClick
This event fires from either a Script or LocalScript when a player interacts with a ClickDetector or DragDetector via the following inputs:
- On platforms with a mouse, when the player left mouse clicks.
- On TouchEnabled platforms, when the player taps.
- On GamepadEnabled platforms, when the center dot is over the same model and the A button is pressed and released.
Note that the player's Character must be within the MaxActivationDistance of the detector.
Parameters
The Player who clicked on the parent of a ClickDetector or DragDetector.
MouseHoverEnter
This event fires from either a Script or LocalScript when the parent of a ClickDetector or DragDetector is hovered over by a player. This does not entail explicit interaction with the detector, for which you can listen to either MouseClick and RightMouseClick events.
Due to the nature of user input, you should not depend on all MouseHoverEnter events firing a corresponding MouseHoverLeave event.
Parameters
The Player who started hovering over the parent of a ClickDetector or DragDetector.
Code Samples
The following code will print "[PlayerName] hovered over my parent!" when a player's cursor hovers over the ClickDetector parent. It will also print "[PlayerName] hovered off my parent!" when the player's cursor moves off the ClickDetector parent.
In order for this example to work as expected, it must be placed in a Script or LocalScript whose parent is a ClickDetector.
local clickDetector = script.Parent:FindFirstChildOfClass("ClickDetector")
clickDetector.MouseHoverEnter:Connect(function(player)
print(player.Name .. " hovered over my parent!")
end)
clickDetector.MouseHoverLeave:Connect(function(player)
print(player.Name .. " hovered off my parent!")
end)MouseHoverLeave
This event fires from either a Script or LocalScript when a player's cursor hovers off the parent of a ClickDetector or DragDetector. This does not entail explicit interaction with the detector, for which you can listen to either MouseClick and RightMouseClick events.
Due to the nature of user input, you should not depend on all MouseHoverLeave events firing after a corresponding MouseHoverEnter event.
Parameters
The Player whose cursor hovered off the parent of a ClickDetector or DragDetector.
Code Samples
The following code will print "[PlayerName] hovered over my parent!" when a player's cursor hovers over the ClickDetector parent. It will also print "[PlayerName] hovered off my parent!" when the player's cursor moves off the ClickDetector parent.
In order for this example to work as expected, it must be placed in a Script or LocalScript whose parent is a ClickDetector.
local clickDetector = script.Parent:FindFirstChildOfClass("ClickDetector")
clickDetector.MouseHoverEnter:Connect(function(player)
print(player.Name .. " hovered over my parent!")
end)
clickDetector.MouseHoverLeave:Connect(function(player)
print(player.Name .. " hovered off my parent!")
end)RightMouseClick
This event fires from either a Script or LocalScript when a player right clicks their mouse cursor on a ClickDetector or DragDetector. Note that the player's Character must be within the MaxActivationDistance of the detector.
Parameters
The Player who right clicked their mouse cursor on the parent of a ClickDetector or DragDetector.