PcoWSkbVqDnWTu_dm2ix
Collapse Sidebar

ClickDetector

Show deprecated

ClickDetector

Show deprecated

ClickDetector allows Script|Scripts and LocalScript|LocalScripts to receive pointer input on 3D objects through their ClickDetector/MouseClick|MouseClick event. They work when parented to BasePart|BasePart, Model|Model or Folder|Folder objects. They detect basic mouse events: enter, leave, left click and right click. Touch input on UserInputService/TouchEnabled|TouchEnabled devices also fires click events.

The default control scripts bind the ButtonR2 enum/KeyCode to interact with ClickDetectors using ContextActionService/BindActivate, which can also be used to override this. When using gamepads, the center dot triggers ClickDetector/MouseHoverEnter|MouseHoverEnter/ClickDetector/MouseHoverLeave|MouseHoverLeave. The bound activation button fires ClickDetector/MouseClick|MouseClick.

Below is a simple template script for working with ClickDetectors. Paste it into a Script or a LocalScript.

local clickDetector = workspace.Part.ClickDetector

function onMouseClick()
	print("You clicked me!")
end

clickDetector.MouseClick:connect(onMouseClick)

ClickDetector/MaxActivationDistance|MaxActivationDistance can be used to limit the distance a player may be from a ClickDetector object before it is no longer clickable.

ClickDetector events fire on both the client and the server, even when Workspace/FilteringEnabled|FilteringEnabled is on. Since a LocalScript will only run if descends from a Player or Player’s Player/Character|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 would detect a user input, only the deepest ClickDetector will fire events. If an action bound with ContextActionService uses the same input as a ClickDetector, the action bound with ContextActionService will take priority over ClickDetector events. If two ClickDetectors are siblings, the first ClickDetector will take priority. UserInputService/InputBegan will fire before ClickDetector events. Due to the nature of user input, you ought not depend on all ClickDetector/MouseHoverEnter|MouseHoverEnter events to fire a matching ClickDetector/MouseHoverLeave|MouseHoverLeave event.

Properties

Content

CursorIcon

Sets the mouse icon that will be displayed when the mouse is hovered over this ClickDetector

float

MaxActivationDistance

Maximum distance between a character and the ClickDetector for the character to be able to click it

Inherited from Instance: Show Hide

bool

Archivable

Determines if an Instance can be cloned using /Instance/Clone or saved to file.

string

ClassName

[ReadOnly] [NotReplicated]

A read-only string representing the class this Instance belongs to

int

DataCost

[Hidden] [ReadOnly] [NotReplicated] [Deprecated]

The cost of saving the instance using data persistence.

string

Name

A non-unique identifier of the Instance

Instance

Parent

[NotReplicated]

Determines the hierarchical parent of the Instance

bool

RobloxLocked

[Hidden]

A deprecated property that used to protect CoreGui objects

bool

archivable

[Hidden] [NotReplicated] [Deprecated]
string

className

[ReadOnly] [NotReplicated] [Deprecated]

Functions

Inherited from Instance: Show Hide

void

ClearAllChildren ( )

This function destroys all of an Instance’s children.

Instance

Clone ( )

Create a copy of an object and all its descendants, ignoring objects that are not Instance/Archivable|Archivable

void

Destroy ( )

Sets the Instance/Parent property to nil, locks the Instance/Parent property, disconnects all connections and calls Destroy on all children.

Instance

FindFirstAncestor ( string name )

Returns the first ancestor of the Instance whose Instance/Name is equal to the given name.

Instance

FindFirstAncestorOfClass ( string className )

Returns the first ancestor of the Instance whose Instance/ClassName is equal to the given className.

Instance

FindFirstAncestorWhichIsA ( string className )

Returns the first ancestor of the Instance for whom Instance/IsA returns true for the given className.

Instance

FindFirstChild ( string name , bool recursive )

Returns the first child of the Instance found with the given name.

Instance

FindFirstChildOfClass ( string className )

Returns the first child of the Instance whose Instance/ClassName|ClassName is equal to the given className.

Instance

FindFirstChildWhichIsA ( string className , bool recursive )

Returns the first child of the Instance for whom Instance/IsA returns true for the given className.

Instance

FindFirstDescendant ( string name )

Actor

GetActor ( )

Variant

GetAttribute ( string attribute )

Returns the attribute which has been assigned to the given name

RBXScriptSignal

GetAttributeChangedSignal ( string attribute )

Returns an event that fires when the given attribute changes

Dictionary

GetAttributes ( )

Returns a dictionary of string → variant pairs for each of the Instance|Instance’s attributes

Objects

GetChildren ( )

Returns an array containing all of the Instance’s children.

string

GetDebugId ( int scopeLength )

[NotBrowsable]

Returns a coded string of the Instances DebugId used internally by Roblox.

Array

GetDescendants ( )

[CustomLuaState]

Returns an array containing all of the descendants of the instance

string

GetFullName ( )

Returns a string describing the Instance’s ancestry.

RBXScriptSignal

GetPropertyChangedSignal ( string property )

Get an event that fires when a given property of an object changes.

bool

IsA ( string className )

[CustomLuaState]

Returns true if an Instance’s class matches or inherits from a given class

bool

IsAncestorOf ( Instance descendant )

Returns true if an Instance is an ancestor of the given descendant.

bool

IsDescendantOf ( Instance ancestor )

Returns true if an Instance is a descendant of the given ancestor.

void

Remove ( )

[Deprecated]

Sets the object’s Parent to nil, and does the same for all its descendants.

void

SetAttribute ( string attribute , Variant value )

Sets the attribute with the given name to the given value

Instance

WaitForChild ( string childName , double timeOut )

[CustomLuaState] [CanYield]

Returns the child of the Instance with the given name. If the child does not exist, it will yield the current thread until it does.

Objects

children ( )

[Deprecated]

Returns an array of the object’s children.

Instance

clone ( )

[Deprecated]
void

destroy ( )

[Deprecated]
Instance

findFirstChild ( string name , bool recursive )

[Deprecated]
Objects

getChildren ( )

[Deprecated]
bool

isA ( string className )

[Deprecated] [CustomLuaState]
bool

isDescendantOf ( Instance ancestor )

[Deprecated]
void

remove ( )

[Deprecated]

Events

RBXScriptSignal

MouseClick ( Player playerWhoClicked )

Fires when a player left clicks on the ClickDetector

RBXScriptSignal

MouseHoverEnter ( Player playerWhoHovered )

Fired when the ClickDetector’s parent is hovered upon by a player

RBXScriptSignal

MouseHoverLeave ( Player playerWhoHovered )

Fired when a player’s mouse moves off of the ClickDetector’s parent

RBXScriptSignal

RightMouseClick ( Player playerWhoClicked )

Fires when a player right clicks on the ClickDetector

RBXScriptSignal

mouseClick ( Player playerWhoClicked )

[Deprecated]

Deprecated in favor of /ClickDetector/MouseClick

Inherited from Instance: Show Hide

RBXScriptSignal

AncestryChanged ( Instance child , Instance parent )

Fires when the Instance/Parent property of the object or one of its ancestors is changed.

RBXScriptSignal

AttributeChanged ( string attribute )

Fires whenever an attribute is changed on the Instance

RBXScriptSignal

Changed ( string property )

Fired immediately after a property of an object changes.

RBXScriptSignal

ChildAdded ( Instance child )

Fires when an object is parented to this Instance.

RBXScriptSignal

ChildRemoved ( Instance child )

Fires when a child is removed from this Instance.

RBXScriptSignal

DescendantAdded ( Instance descendant )

Fires when a descendant is added to the Instance

RBXScriptSignal

DescendantRemoving ( Instance descendant )

Fires immediately before a descendant of the Instance is removed.

RBXScriptSignal

childAdded ( Instance child )

[Deprecated]

Code Samples


ClickDetector Example

Place this code inside a Script inside a ClickDetector. The code sample first creates a reference to the ClickDetector parent and defines a function to show a message that greets a player. Finally, it connects the ClickDetector/MouseClick|MouseClick event of the ClickDetector 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)

Part Anchored Toggle

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)

Creating a ClickDetector Door

The code sample below demonstrates the functionality of a ClickDetector and its properties and events.

First the code creates a ClickDetector and set’s its Instance/Parent|parent to the door. It also sets the ClickDetector/MaxActivationDistance|maximum distance players can interact with the ClickDetector to 10 studs and set’s the ClickDetector’s ClickDetector/CursorImage|CursorImage to:

Custom cursor image

Then, the code connects the ClickDetector to several events, including changing the door’s BasePart/Transparency when the player’s mouse hovers ClickDetector/MouseHoverEnter|on and ClickDetector/MouseHoverLeave|off off the door. The player opens the door by ClickDetector/MouseClick|left clicking their mouse while over the ClickDetector and closes the door by ClickDetector/RightMouseClick|right clicking their mouse while over the ClickDetector.

This code works in a Script and a LocalScript as long as the script’s parent is the door BasePart|Part.

-- The door 'BasePart'
local door = script.Parent

-- Asset ID of the image you want the to set the cursor to
local CursorId = "2287179355"

-- Create a ClickDetector
local ClickDetector = Instance.new("ClickDetector")
ClickDetector.Parent = door
ClickDetector.MaxActivationDistance = 10
ClickDetector.CursorIcon = "rbxassetid://"..CursorId

-- Make door slightly transparent when mouse hovers over it
ClickDetector.MouseHoverEnter:Connect(function()
	door.Transparency = 0.1
end)

-- Door is not transparent when mouse is not hovering over it
ClickDetector.MouseHoverLeave:Connect(function()
	door.Transparency = 0
end)

-- Open door on left mouse click
ClickDetector.MouseClick:Connect(function()
	door.Transparency = 0.8
	door.CanCollide = false
end)

-- Close door on right mouse click
ClickDetector.RightMouseClick:Connect(function()
	door.Transparency = 0.1
	door.CanCollide = true
end)