Mouse

Show Deprecated
Not Creatable

Mouse has been superseded by UserInputService and ContextActionService, which cover a broader scope, are more feature rich, and support cross-platform patterns better. It remains supported because of its widespread use, but you should strongly consider using these alternatives.

The Mouse object houses various API for pointers, primarily for buttons and raycasting. It can be accessed through Player:GetMouse() called on the Players.LocalPlayer in a LocalScript. It is also passed by the Tool.Equipped event.

  • It is most notable for the Icon property, which changes the cursor's appearance.
  • It continually raycasts the screen mouse position into the 3D world using the TargetFilter property, storing the results of the raycast in the Hit, Target, and TargetSurface properties. These can be useful for simple cases, but WorldRoot:Raycast() should be used in more complicated scenarios (whitelists, etc).
  • Plugins can use use Plugin:GetMouse() to get a PluginMouse, which behaves similarly.

1-- From a LocalScript:
2local Players = game:GetService("Players")
3local player = Players.LocalPlayer
4local mouse = player:GetMouse()
5-- Setting the mouse icon
6mouse.Icon = "rbxasset://SystemCursors/Wait"
7

Note:

Summary

Properties

The CFrame of the mouse's position in 3D space.

READ ONLY
NOT REPLICATED

The content ID of the image used as the Mouse's icon.

A CFrame positioned at the Workspace.CurrentCamera and oriented toward the Mouse's 3D position.

READ ONLY
NOT REPLICATED

The object in 3D space the mouse is pointing to.

READ ONLY
NOT REPLICATED

Determines an object (and its descendants) to be ignored when determining Mouse.Hit and Mouse.Target.

Indicates the NormalId of the BasePart surface at which the mouse is pointing.

READ ONLY
NOT REPLICATED

A Ray directed towards the Mouse's world position, originating from the Camera's world position.

READ ONLY
NOT REPLICATED

Describes the width of the game window in pixels.

READ ONLY
NOT REPLICATED

Describes the height of the game window in pixels.

READ ONLY
NOT REPLICATED

Describes the X (horizontal) component of the mouse's position on the screen.

READ ONLY
NOT REPLICATED

Describes the Y (vertical) component of the mouse's screen position.

READ ONLY
NOT REPLICATED

Events


Fired when the left mouse button is pressed.


Fires when the left mouse button is released.


Fires when the right mouse button is pressed.


Fired when the right mouse button is released.


Fired during every heartbeat that the mouse isn't being passed to another mouse event.


Fired when the mouse is moved.


Fires when the mouse wheel is scrolled backwards.


Fires when the mouse wheel is scrolled forwards.

Methods

Properties

Read Only
Not Replicated

This property indicates CFrame of the mouse's position in 3D space. Note that Mouse.TargetFilter and its descendants will be ignored.

Developers can get obtain the position of Hit like so:


1local position = mouse.Hit.p
2

Hit is often used by Tools to fire a weapon towards the mouse in third person.

Developers looking for the BasePart the mouse is pointing at should use Mouse.Target.

How is Mouse.Hit calculated?

The position of the Hit CFrame is calculated as the point of intersection between the mouse's internal Ray (an extended version of Mouse.UnitRay) and an object in 3D space (such as a part).

The orientation of the Hit CFrame corresponds with the direction of the Mouse.UnitRay.


1local unitRayDirection = mouse.UnitRay.Direction
2local mouseHitDirection = mouse.Hit.lookVector
3-- unitRayDirection ≈ mouseHitDirection
4-- the vectors are approximately equal
5

Note, the roll of the Workspace.CurrentCamera is not used when calculating the orientation of the Hit CFrame.

The mouse's internal ray extends for 1000 studs. If the mouse is not pointing at an object in 3D space (for example when pointing at the sky), this property will be 1000 studs away from the Workspace.CurrentCamera.

Icon is a property that determines the image used as the pointer. If blank, a default arrow is used. While the cursor hovers over a GuiButton, this property is temporarily ignored.

To hide the cursor entirely, do not use a transparent image – instead, set UserInputService.MouseIconEnabled to false.

Designing a Cursor

The following guidelines may prove useful when creating your own mouse cursors:

  • The dimensions of the image used determines the size of the cursor.
  • The center of the image is where mouse inputs are issued.
  • The default mouse image is 64x64 pixels, with the mouse taking up 17x24 pixels of space.

System Cursors for PluginMouse

When using a PluginMouse retrieved from Plugin:GetMouse(), you can use the following icons similar to your system's default cursors, such as hands, arrows, I-beams, etc. You can use these with GUI events like MouseEnter, MouseLeave, and MouseButton1Down to provide a consistent studio experience when interacting with certain kinds of GUI components. Note that these only work for studio plugins; they will not work for other Mouse objects.

Look*AssetSuggested Use
rbxasset://SystemCursors/ArrowDefault clicking and selection.
rbxasset://SystemCursors/PointingHandHovering over an active link/button.
rbxasset://SystemCursors/OpenHandHovering over a draggable item.
rbxasset://SystemCursors/ClosedHandDragging an item.
rbxasset://SystemCursors/IBeamHovering in a text field.
rbxasset://SystemCursors/SizeNSHovering over a vertical resize handle.
rbxasset://SystemCursors/SizeEWHovering over a horizontal resize handle.
rbxasset://SystemCursors/SizeNESWHovering over a corner resize handle.
rbxasset://SystemCursors/SizeNWSEHovering over a corner resize handle.
rbxasset://SystemCursors/SizeAllHovering over a multi-direction resize handle.
rbxasset://SystemCursors/SplitNSHovering over a vertical "split" handle.
rbxasset://SystemCursors/SplitEWHovering over a horizontal "split" handle.
rbxasset://SystemCursors/ForbiddenHovering over a locked/forbidden item.
rbxasset://SystemCursors/WaitIndicating an action is in progress.
rbxasset://SystemCursors/BusyIndicating the system is busy.
rbxasset://SystemCursors/CrossHovering over a pinpoint selection area.

* These appearances are approximations – the actual look is dependent on your operating system.

Origin

Read Only
Not Replicated

The origin Mouse property is a CFrame indicating where the mouse originated from. It is positioned at the Workspace.CurrentCamera and oriented toward the Mouse's 3D position.

Mouse.UnitRay starts at the same position as Origin, and extends for a stud in the same direction.


1local unitRay = mouse.UnitRay
2local origin = mouse.Origin
3-- unitRay.Direction = origin.p
4-- unitRay.Direction ≈ origin.lookVector
5

For the position of the Mouse in 3D space, see Mouse.Hit.

Target

Read Only
Not Replicated

The object in 3D space the mouse is pointing to.

Note:

  • If Mouse.TargetFilter has been set, the target filter and its descendants will be ignored.
  • When the mouse is not pointing at a BasePart, for example when it is pointing at the sky, Target will be nil.
  • Developers looking for the position of the mouse in 3D space should use Mouse.Hit.

TargetFilter

This property determines an object to be ignored by the mouse when calculating Mouse.Hit and Mouse.Target. The descendants of the object are also ignored, so it is possible to ignore multiple objects so long as they are a descendant of the object to which this property is set. This property is useful when filtering models containing special effects or decorations that should not affect Mouse.Hit or Mouse.Target.

This property can be set to any Instance or nil, for example:


1local Players = game:GetService("Players")
2local player = Players.LocalPlayer
3local mouse = player:GetMouse()
4mouse.TargetFilter = workspace.Model
5
6-- Now, when the player hovers the cursor over the model, mouse.Target will be some object
7-- behind workspace.Model, if there is one.
8

This property is essentially a single-object blacklist for mouse raycasting. For more in-depth control on raycasting, see the following functions of Workspace: FindPartOnRay, FindPartOnRayWithWhitelist and FindPartOnRayWithIgnoreList.

The Character of the Players.LocalPlayer is ignored by the mouse automatically."

TargetSurface

Read Only
Not Replicated

This property indicates the NormalId of the BasePart surface at which the mouse is pointing. This property is derived from the world position of mouse (Mouse.Hit) and the part toward which the mouse is pointing (Mouse.Target).

This property isn't meaningful when the mouse is not pointing at a part, for example when the mouse is pointing at the sky. At the moment, this property is set to 'Right' under these circumstances. Before using this property, check that the mouse's target is not nil.


1local Players = game:GetService("Players")
2local player = Players.LocalPlayer
3local mouse = player:GetMouse()
4-- Check that there exists a part at which the mouse is pointing
5if mouse.Target then
6 print("The mouse is pointing to the " .. mouse.TargetSurface.Name .. " side of " .. mouse.Target.Name)
7else
8 print("The mouse is not pointing at anything.")
9end
10

UnitRay

Read Only
Not Replicated

The UnitRay property is a Ray directed toward the Mouse's position in 3D space (described by Mouse.Hit). It originates from the CFrame of the Workspace.CurrentCamera. Like all unit rays, it has a distance of 1.


1local Players = game:GetService("Players")
2local player = Players.LocalPlayer
3local mouse = player:GetMouse()
4print(mouse.UnitRay.Direction.magnitude) -- Always 1
5

ViewSizeX

Read Only
Not Replicated

The ViewSizeX property describes the horizontal component of the game window's size in pixels.

ViewSizeY

Read Only
Not Replicated

The ViewSizeY property describes the vertical component of the game window's size in pixels. This length includes the space used by the topbar.

Read Only
Not Replicated

When detecting changes in the mouse's position on-screen, it is recommended that you use ContextActionService:BindAction() with UserInputType.MouseMovement or UserInputService.InputChanged, which both describe the position of the mouse using the Position (a Vector3) of an InputObject, instead of using this and related properties.

The X property describes the horizontal component of the mouse's position on the screen. The position is measured in pixels relative to the top left corner, under the topbar. This property can be used in conjunction with Mouse.Y to produce a Vector2 representing the mouse's position:


1local position = Vector2.new(mouse.X, mouse.Y)
2

This property does not fire Changed or the signal returned from GetPropertyChangedSignal. Use the Mouse.Move event instead.

Read Only
Not Replicated

When detecting changes in the mouse's position on-screen, it is recommended that you use ContextActionService:BindAction() with UserInputType.MouseMovement or UserInputService.InputChanged, which both describe the position of the mouse using the Position (a Vector3) of an InputObject, instead of using this and related properties.

The Y property describes the vertical component of the mouse's position on the screen. The position is measured in pixels relative to the top left corner, under the topbar. This property can be used in conjunction with Mouse.X to produce a Vector2 representing the mouse's position:


1local position = Vector2.new(mouse.X, mouse.Y)
2

This property does not fire Changed or the signal returned from GetPropertyChangedSignal. Use the Mouse.Move event instead.

Events

Button1Down

The Button1Down even fires when the the player presses their left mouse button.

This can also be accessed from a Tool. For example, when placed in a LocalScript, the code below prints Button1Down whenever the left mouse button is pressed:


1local Tool = script.Parent --make sure this is a Tool object
2
3Tool.Equipped:Connect(function(Mouse)
4 Mouse.Button1Down:Connect(function()
5 print("Button1Down")
6 end)
7end)
8

Developers can find out the position of the mouse in world-space, and if it is pointing at any BasePart, using the Mouse.Hit and Mouse.Target properties.

For information on how to obtain the mouse object, please see the Mouse page.

Note, developers are recommended to use UserInputService instead of the Mouse object in new work.


Code Samples

Color Randomizer Tool

1local Players = game:GetService("Players")
2
3local localPlayer = Players.LocalPlayer
4local backpack = localPlayer:WaitForChild("Backpack")
5
6local tool = Instance.new("Tool")
7tool.RequiresHandle = false
8tool.CanBeDropped = false
9tool.Parent = backpack
10
11tool.Equipped:Connect(function(mouse)
12 mouse.Button1Down:Connect(function()
13 if mouse.Target and mouse.Target.Parent then
14 mouse.Target.BrickColor = BrickColor.random()
15 end
16 end)
17end)

Button1Up

Fires when the left mouse button is released.

For information on how to obtain the Mouse object, please see the Mouse page.

Developers can find out the position of the mouse in world-space, and if it is pointing at any BasePart using the Mouse.Hit and Mouse.Target properties.

Note, developers are recommended to use UserInputService instead of the Mouse object in new work.


Code Samples

Color Randomizer Tool (Button1Up)

1local Players = game:GetService("Players")
2
3local player = Players.LocalPlayer
4
5local mouse = player:GetMouse()
6local target = nil
7
8local function button1Down()
9 target = mouse.Target
10end
11
12local function button1Up()
13 if target == mouse.Target then
14 target.BrickColor = BrickColor.random()
15 end
16end
17
18mouse.Button1Down:Connect(button1Down)
19mouse.Button1Up:Connect(button1Up)

Button2Down

The Button2Down even fires when the the player presses their right mouse button.

This can also be accessed from a Tool. For example, when placed in a LocalScript, the code below prints Button2Down whenever the right mouse button is pressed:


1local Tool = script.Parent --make sure this is a Tool object
2
3Tool.Equipped:Connect(function(Mouse)
4 Mouse.Button2Down:Connect(function()
5 print("Button2Down")
6 end)
7end).
8

Developers can find out the position of the mouse in world-space, and if it is pointing at any BasePart, using the Mouse.Hit and Mouse.Target properties.

For information on how to obtain the mouse object, please see the Mouse page.

Note, developers are recommended to use UserInputService instead of the Mouse object in new work.


Code Samples

Color Randomizer Tool

1local Players = game:GetService("Players")
2
3local localPlayer = Players.LocalPlayer
4
5local backpack = localPlayer:WaitForChild("Backpack")
6
7local tool = Instance.new("Tool")
8tool.RequiresHandle = false
9tool.CanBeDropped = false
10tool.Parent = backpack
11
12tool.Equipped:Connect(function(mouse)
13 mouse.Button2Down:Connect(function()
14 if mouse.Target and mouse.Target.Parent then
15 mouse.Target.BrickColor = BrickColor.random()
16 end
17 end)
18end)

Button2Up

Fired when the right mouse button is released.


1mouse.Button2Up:Connect(function()
2print("button 2 up!")
3end
4

For information on how to obtain the Mouse object, please see the Mouse page.

Developers can find out the position of the mouse in world-space, and if it is pointing at any BasePart using the Mouse.Hit and Mouse.Target properties.

Note, developers are recommended to use UserInputService instead of the Mouse object in new work.


Code Samples

Color Randomizer Tool (Button2Up)

1local Players = game:GetService("Players")
2
3local mouse = Players.LocalPlayer:GetMouse()
4local target = nil
5
6mouse.Button2Down:Connect(function()
7 target = mouse.Target
8end)
9
10mouse.Button2Up:Connect(function()
11 if target == mouse.Target then
12 target.BrickColor = BrickColor.random()
13 end
14end)

Idle

Fired during every heartbeat that the mouse isn't being passed to another mouse event.

Note, this event should not be used to determine when the mouse is still. As it fires every heartbeat it will fire between Mouse.Move events.

For information on how to obtain the Mouse object, please see the Mouse page.

Developers can find out the position of the mouse in world-space, and if it is pointing at any BasePart using the Mouse.Hit and Mouse.Target properties.

Note, developers are recommended to use UserInputService instead of the Mouse object in new work.


Code Samples

Mouse.Idle

1local Players = game:GetService("Players")
2local RunService = game:GetService("RunService")
3
4local player = Players.LocalPlayer
5
6local mouse = player:GetMouse()
7
8local events = {
9 "Button1Down",
10 "Button1Up",
11 "Button2Down",
12 "Button2Up",
13 "Idle",
14 "Move",
15 "WheelBackward",
16 "WheelForward",
17 "KeyDown",
18 "KeyUp",
19}
20
21local currentEvent
22local frame = 0
23
24local function processInput()
25 frame = frame + 1
26 print("Frame", frame, "- mouse event was passed to", currentEvent)
27end
28
29for _, event in pairs(events) do
30 mouse[event]:Connect(function()
31 currentEvent = event
32 end)
33end
34
35RunService:BindToRenderStep("ProcessInput", Enum.RenderPriority.Input.Value, processInput)

Move

Fired when the mouse is moved.

Note, this event is fired when the mouse's position is updated, therefore it will fire repeatedly while being moved.

For information on how to obtain the Mouse object, please see the Mouse page.

Developers can find out the position of the mouse in world-space, and if it is pointing at any BasePart using the Mouse.Hit and Mouse.Target properties.


1mouse.Move:Connect(function()
2 local position = mouse.Hit.p
3 local target = mouse.Target
4 print(target, position)
5end)
6

Note, developers are recommended to use UserInputService instead of the Mouse object in new work.


Code Samples

Move Parts with the Mouse

1local Players = game:GetService("Players")
2
3local player = Players.LocalPlayer
4
5local mouse = player:GetMouse()
6
7local point
8local down
9
10local function selectPart()
11 if mouse.Target and not mouse.Target.Locked then
12 point = mouse.Target
13 mouse.TargetFilter = point
14 down = true
15 end
16end
17
18local function movePart()
19 if down and point then
20 local posX, posY, posZ = mouse.Hit.X, mouse.Hit.Y, mouse.Hit.Z
21 point.Position = Vector3.new(posX, posY, posZ)
22 end
23end
24
25local function deselectPart()
26 down = false
27 point = nil
28 mouse.TargetFilter = nil
29end
30
31mouse.Button1Down:Connect(selectPart)
32mouse.Button1Up:Connect(deselectPart)
33mouse.Move:Connect(movePart)

WheelBackward

The WheelBackward event fires when the mouse wheel is scrolled backwards. Possible uses for this event include toggling a gun's scope in a first person shooter (FPS) or zooming the player's camera.

This can be used alongside the scrolling forward event, Mouse.WheelForward.

For information on how to obtain the Mouse object, please see the Mouse page.

Note, developers are recommended to use UserInputService instead of the Mouse object in new work.


Code Samples

Mouse.WheelBackward

1local Players = game:GetService("Players")
2
3local player = Players.LocalPlayer
4
5local mouse = player:GetMouse()
6
7local function onWheelBackward()
8 print("Wheel went backwards!")
9end
10
11mouse.WheelBackward:Connect(onWheelBackward)

WheelForward

The WheelForward event fires when the mouse wheel is scrolled forwards. Possible uses for this event include toggling a gun's scope in a first person shooter (FPS) or zooming the player's camera.

This can be used alongside the scrolling backward event, Mouse.WheelBackward.

For information on how to obtain the Mouse object, please see the Mouse page.

Note, developers are recommended to use UserInputService instead of the Mouse object in new work.


Code Samples

Mouse.WheelForward

1local Players = game:GetService("Players")
2
3local player = Players.LocalPlayer
4
5local mouse = player:GetMouse()
6
7local function onWheelBackward()
8 print("Wheel went forward!")
9end
10
11mouse.WheelForward:Connect(onWheelBackward)

Methods