Engine

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.


-- From a LocalScript:
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
-- Setting the mouse icon
mouse.Icon = "rbxasset://SystemCursors/Wait"

Note:

Summary

Properties

Events

Properties

read only
not replicated
read parallel

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:


local position = mouse.Hit.p

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.


local unitRayDirection = mouse.UnitRay.Direction
local mouseHitDirection = mouse.Hit.lookVector
-- unitRayDirection ≈ mouseHitDirection
-- the vectors are approximately equal

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.

Code Samples

Mouse.Hit Laser Beam

local Players = game:GetService("Players")
local RunService = game:GetService("RunService")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
local beam = Instance.new("Beam")
beam.Segments = 1
beam.Width0 = 0.2
beam.Width1 = 0.2
beam.Color = ColorSequence.new(Color3.new(1, 0, 0))
beam.FaceCamera = true
local attachment0 = Instance.new("Attachment")
local attachment1 = Instance.new("Attachment")
beam.Attachment0 = attachment0
beam.Attachment1 = attachment1
beam.Parent = workspace.Terrain
attachment0.Parent = workspace.Terrain
attachment1.Parent = workspace.Terrain
local function onRenderStep()
local character = player.Character
if not character then
beam.Enabled = false
return
end
local head = character:FindFirstChild("Head")
if not head then
beam.Enabled = false
return
end
beam.Enabled = true
local origin = head.Position
local finish = mouse.Hit.Position
attachment0.Position = origin
attachment1.Position = finish
end
RunService.RenderStepped:Connect(onRenderStep)
Mouse Origin vs Mouse Hit vs CurrentCamera Position

local Players = game:GetService("Players")
local Workspace = game:GetService("Workspace")
local player = Players.LocalPlayer
local camera = Workspace.CurrentCamera
local mouse = player:GetMouse()
local camPos = camera.CFrame.Position
local function onButton1Down()
print("Mouse.Hit:", mouse.Hit.Position)
print("camPos:", camPos)
print("Mouse.Origin:", mouse.Origin.Position)
print("Magnitude:", (mouse.Origin.Position - camPos).Magnitude)
end
mouse.Button1Down:Connect(onButton1Down)
read parallel

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.

For getting/setting the user mouse icon in experiences, you should use UserInputService.MouseIcon. Mouse.Icon will be deprecated after the new API for plugins to set the mouse cursor is released.

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.

Code Samples

Dragon Mouse Icon

local Players = game:GetService("Players")
local mouse = Players.LocalPlayer:GetMouse()
mouse.Icon = "http://www.roblox.com/asset?id=163023520"

Origin

read only
not replicated
read parallel

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.


local unitRay = mouse.UnitRay
local origin = mouse.Origin
-- unitRay.Direction = origin.p
-- unitRay.Direction ≈ origin.lookVector

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

Code Samples

Mouse Origin vs Mouse Hit vs CurrentCamera Position

local Players = game:GetService("Players")
local Workspace = game:GetService("Workspace")
local player = Players.LocalPlayer
local camera = Workspace.CurrentCamera
local mouse = player:GetMouse()
local camPos = camera.CFrame.Position
local function onButton1Down()
print("Mouse.Hit:", mouse.Hit.Position)
print("camPos:", camPos)
print("Mouse.Origin:", mouse.Origin.Position)
print("Magnitude:", (mouse.Origin.Position - camPos).Magnitude)
end
mouse.Button1Down:Connect(onButton1Down)

Target

read only
not replicated
read parallel

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.

Code Samples

Color Randomizer Tool

local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local backpack = localPlayer:WaitForChild("Backpack")
local tool = Instance.new("Tool")
tool.RequiresHandle = false
tool.CanBeDropped = false
tool.Parent = backpack
tool.Equipped:Connect(function(mouse)
mouse.Button1Down:Connect(function()
if mouse.Target and mouse.Target.Parent then
mouse.Target.BrickColor = BrickColor.random()
end
end)
end)

TargetFilter

read parallel

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:


local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
mouse.TargetFilter = workspace.Model

Note that the Character of the Players.LocalPlayer is ignored by the mouse automatically.

TargetSurface

read only
not replicated
read parallel

This property indicates the Enum.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.


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

Code Samples

Surface Randomizer

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
local surfaceTypes = {
Enum.SurfaceType.Smooth,
Enum.SurfaceType.Glue,
Enum.SurfaceType.Weld,
Enum.SurfaceType.Studs,
Enum.SurfaceType.Inlet,
Enum.SurfaceType.Universal,
Enum.SurfaceType.Hinge,
Enum.SurfaceType.Motor,
}
local function onMouseClick()
-- make sure the mouse is pointing at a part
local target = mouse.Target
if not target then
return
end
local surfaceType = surfaceTypes[math.random(1, #surfaceTypes)]
local surface = mouse.TargetSurface
local propertyName = surface.Name .. "Surface"
mouse.Target[propertyName] = surfaceType
end
mouse.Button1Down:Connect(onMouseClick)

UnitRay

read only
not replicated
read parallel

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.


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

ViewSizeX

read only
not replicated
read parallel

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

Code Samples

Normalized Mouse Position

local Players = game:GetService("Players")
-- Note: You should use ContextActionService or UserInputService instead of
-- the Mouse object for accomplishing this task.
local player = Players.LocalPlayer
local mouse = player:GetMouse()
local function onMouseMove()
-- Construct Vector2 objects for the mouse's position and screen size
local position = Vector2.new(mouse.X, mouse.Y)
local size = Vector2.new(mouse.ViewSizeX, mouse.ViewSizeY)
-- A normalized position will map the top left (just under the topbar)
-- to (0, 0) the bottom right to (1, 1), and the center to (0.5, 0.5).
-- This is calculated by dividing the position by the total size.
local normalizedPosition = position / size
print(normalizedPosition)
end
mouse.Move:Connect(onMouseMove)

ViewSizeY

read only
not replicated
read parallel

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

Code Samples

Normalized Mouse Position

local Players = game:GetService("Players")
-- Note: You should use ContextActionService or UserInputService instead of
-- the Mouse object for accomplishing this task.
local player = Players.LocalPlayer
local mouse = player:GetMouse()
local function onMouseMove()
-- Construct Vector2 objects for the mouse's position and screen size
local position = Vector2.new(mouse.X, mouse.Y)
local size = Vector2.new(mouse.ViewSizeX, mouse.ViewSizeY)
-- A normalized position will map the top left (just under the topbar)
-- to (0, 0) the bottom right to (1, 1), and the center to (0.5, 0.5).
-- This is calculated by dividing the position by the total size.
local normalizedPosition = position / size
print(normalizedPosition)
end
mouse.Move:Connect(onMouseMove)
read only
not replicated
read parallel

When detecting changes in the mouse's position on-screen, it is recommended that you use ContextActionService:BindAction() with Enum.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:


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

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

Code Samples

Normalized Mouse Position

local Players = game:GetService("Players")
-- Note: You should use ContextActionService or UserInputService instead of
-- the Mouse object for accomplishing this task.
local player = Players.LocalPlayer
local mouse = player:GetMouse()
local function onMouseMove()
-- Construct Vector2 objects for the mouse's position and screen size
local position = Vector2.new(mouse.X, mouse.Y)
local size = Vector2.new(mouse.ViewSizeX, mouse.ViewSizeY)
-- A normalized position will map the top left (just under the topbar)
-- to (0, 0) the bottom right to (1, 1), and the center to (0.5, 0.5).
-- This is calculated by dividing the position by the total size.
local normalizedPosition = position / size
print(normalizedPosition)
end
mouse.Move:Connect(onMouseMove)
read only
not replicated
read parallel

When detecting changes in the mouse's position on-screen, it is recommended that you use ContextActionService:BindAction() with Enum.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:


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

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

Code Samples

Normalized Mouse Position

local Players = game:GetService("Players")
-- Note: You should use ContextActionService or UserInputService instead of
-- the Mouse object for accomplishing this task.
local player = Players.LocalPlayer
local mouse = player:GetMouse()
local function onMouseMove()
-- Construct Vector2 objects for the mouse's position and screen size
local position = Vector2.new(mouse.X, mouse.Y)
local size = Vector2.new(mouse.ViewSizeX, mouse.ViewSizeY)
-- A normalized position will map the top left (just under the topbar)
-- to (0, 0) the bottom right to (1, 1), and the center to (0.5, 0.5).
-- This is calculated by dividing the position by the total size.
local normalizedPosition = position / size
print(normalizedPosition)
end
mouse.Move:Connect(onMouseMove)

Methods

Events

Button1Down

The Button1Down even fires when 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:


local Tool = script.Parent --make sure this is a Tool object
Tool.Equipped:Connect(function(Mouse)
Mouse.Button1Down:Connect(function()
print("Button1Down")
end)
end)

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

local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local backpack = localPlayer:WaitForChild("Backpack")
local tool = Instance.new("Tool")
tool.RequiresHandle = false
tool.CanBeDropped = false
tool.Parent = backpack
tool.Equipped:Connect(function(mouse)
mouse.Button1Down:Connect(function()
if mouse.Target and mouse.Target.Parent then
mouse.Target.BrickColor = BrickColor.random()
end
end)
end)

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)

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
local target = nil
local function button1Down()
target = mouse.Target
end
local function button1Up()
if target == mouse.Target then
target.BrickColor = BrickColor.random()
end
end
mouse.Button1Down:Connect(button1Down)
mouse.Button1Up:Connect(button1Up)

Button2Down

The Button2Down even fires when 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:


local Tool = script.Parent --make sure this is a Tool object
Tool.Equipped:Connect(function(Mouse)
Mouse.Button2Down:Connect(function()
print("Button2Down")
end)
end).

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

local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local backpack = localPlayer:WaitForChild("Backpack")
local tool = Instance.new("Tool")
tool.RequiresHandle = false
tool.CanBeDropped = false
tool.Parent = backpack
tool.Equipped:Connect(function(mouse)
mouse.Button2Down:Connect(function()
if mouse.Target and mouse.Target.Parent then
mouse.Target.BrickColor = BrickColor.random()
end
end)
end)

Button2Up

Fired when the right mouse button is released.


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

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)

local Players = game:GetService("Players")
local mouse = Players.LocalPlayer:GetMouse()
local target = nil
mouse.Button2Down:Connect(function()
target = mouse.Target
end)
mouse.Button2Up:Connect(function()
if target == mouse.Target then
target.BrickColor = BrickColor.random()
end
end)

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

local Players = game:GetService("Players")
local RunService = game:GetService("RunService")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
local events = {
"Button1Down",
"Button1Up",
"Button2Down",
"Button2Up",
"Idle",
"Move",
"WheelBackward",
"WheelForward",
"KeyDown",
"KeyUp",
}
local currentEvent
local frame = 0
local function processInput()
frame = frame + 1
print("Frame", frame, "- mouse event was passed to", currentEvent)
end
for _, event in pairs(events) do
mouse[event]:Connect(function()
currentEvent = event
end)
end
RunService: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.


mouse.Move:Connect(function()
local position = mouse.Hit.p
local target = mouse.Target
print(target, position)
end)

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


Code Samples

Move Parts with the Mouse

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
local point
local down
local function selectPart()
if mouse.Target and not mouse.Target.Locked then
point = mouse.Target
mouse.TargetFilter = point
down = true
end
end
local function movePart()
if down and point then
local posX, posY, posZ = mouse.Hit.X, mouse.Hit.Y, mouse.Hit.Z
point.Position = Vector3.new(posX, posY, posZ)
end
end
local function deselectPart()
down = false
point = nil
mouse.TargetFilter = nil
end
mouse.Button1Down:Connect(selectPart)
mouse.Button1Up:Connect(deselectPart)
mouse.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

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
local function onWheelBackward()
print("Wheel went backwards!")
end
mouse.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

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()
local function onWheelBackward()
print("Wheel went forward!")
end
mouse.WheelForward:Connect(onWheelBackward)