Mouse¶
Legacy object that contains members useful for pointer input.
Description¶
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 raycasting scenarios.
- Plugins can use Plugin.GetMouse() to get a PluginMouse, which behaves similarly.
-- 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:
- This object does not control/restrict pointer movement. For this, see UserInputService.MouseBehavior and UserInputService.MouseDeltaSensitivity.
- If two functions are connected to same input event, such as Button1Down, both functions will run when the event fires. There is no concept of sinking/passing input, as events don't support this behavior. However, ContextActionService does have this behavior through BindAction.
- While a mouse may not be available on all platforms, Mouse will still function on mobile (touch) and console (gamepad), which don't typically have mice or pointer hardware. For explicit cross-platform behaviors, use UserInputService and ContextActionService.
See Input and Camera for more information on customizing inputs in your experience.
Inheritance¶
Nova inheritance: Instance → Mouse
Known subclasses: PlayerMouse, PluginMouse
Properties¶
Hit Supported Property The CFrame of the mouse's position in 3D space.
The CFrame of the mouse's position in 3D space.
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:
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 1,000 studs. If the mouse is not pointing at an object in 3D space (for example when pointing at the sky), this property will be 1,000 studs away from the Workspace.CurrentCamera.
hit Supported Property Deprecated
No description available.
Icon Supported Property The content ID of the image used as the Mouse icon.
The content ID of the image used as the Mouse icon.
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 dimensions of the image should not exceed 256 pixels on any axis.
- 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¶
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* | Asset | Suggested Use |
|---|---|---|
 |
rbxasset://SystemCursors/Arrow |
Default clicking and selection. |
 |
rbxasset://SystemCursors/PointingHand |
Hovering over an active link/button. |
 |
rbxasset://SystemCursors/OpenHand |
Hovering over a draggable item. |
 |
rbxasset://SystemCursors/ClosedHand |
Dragging an item. |
 |
rbxasset://SystemCursors/IBeam |
Hovering in a text field. |
 |
rbxasset://SystemCursors/SizeNS |
Hovering over a vertical resize handle. |
 |
rbxasset://SystemCursors/SizeEW |
Hovering over a horizontal resize handle. |
 |
rbxasset://SystemCursors/SizeNESW |
Hovering over a corner resize handle. |
 |
rbxasset://SystemCursors/SizeNWSE |
Hovering over a corner resize handle. |
 |
rbxasset://SystemCursors/SizeAll |
Hovering over a multi-direction resize handle. |
 |
rbxasset://SystemCursors/SplitNS |
Hovering over a vertical "split" handle. |
 |
rbxasset://SystemCursors/SplitEW |
Hovering over a horizontal "split" handle. |
 |
rbxasset://SystemCursors/Forbidden |
Hovering over a locked/forbidden item. |
 |
rbxasset://SystemCursors/Wait |
Indicating an action is in progress. |
 |
rbxasset://SystemCursors/Busy |
Indicating the system is busy. |
 |
rbxasset://SystemCursors/Cross |
Hovering over a pinpoint selection area. |
Origin Supported Property A CFrame positioned at the Workspace.CurrentCamera and oriented toward the mouse's 3D position.
A CFrame positioned at the Workspace.CurrentCamera and oriented toward the mouse's 3D position.
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
Target Supported Property The object in 3D space the mouse is pointing to.
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.
target Supported Property Deprecated
No description available.
TargetFilter Supported Property Determines an object (and its descendants) to be ignored when determining Mouse.Hit and Mouse.Target.
Determines an object (and its descendants) to be ignored when determining Mouse.Hit and Mouse.Target.
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 Workspace = game:GetService("Workspace")
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 Supported Property Indicates the NormalId of the BasePart surface at which the mouse is pointing.
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.
UnitRay Supported Property A Ray directed towards the mouse's world position, originating from the Workspace.CurrentCamera world position.
A Ray directed towards the mouse's world position, originating from the Workspace.CurrentCamera world position.
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.
ViewSizeX Supported Property Describes the width of the game window in pixels.
Describes the width of the game window in pixels.
The ViewSizeX property describes the horizontal component of the game window's size in pixels.
ViewSizeY Supported Property Describes the height of the game window in pixels.
Describes the height of the game window in pixels.
The ViewSizeY property describes the vertical component of the game window's size in pixels. This length includes the space used by the topbar.
X Supported Property Describes the X (horizontal) component of the mouse's position on the screen.
Describes the X (horizontal) component of the mouse's position on the screen.
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:
This property does not fire Changed or the signal returned from GetPropertyChangedSignal. Use the Mouse.Move event instead.
Y Supported Property Describes the Y (vertical) component of the mouse's screen position.
Describes the Y (vertical) component of the mouse's screen position.
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:
This property does not fire Changed or the signal returned from GetPropertyChangedSignal. Use the Mouse.Move event instead.
Events¶
Button1Down Supported Event Fires when the left mouse button is pressed.
Fires when the left mouse button is pressed.
This event fires when the player presses their left mouse button. Note
that this can 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)
You can find out the position of the mouse in world space and if it's pointing at any BasePart using the Hit and Target properties.
Button1Up Supported Event Fires when the left mouse button is released.
Fires when the left mouse button is released.
This event fires when the player releases their left mouse button. Note
that this can be accessed from a Tool; for example, when placed in
a LocalScript, the code below prints Button1Up whenever the left
mouse button is released.
local tool = script.Parent -- Make sure this is a Tool object
tool.Equipped:Connect(function(mouse)
mouse.Button1Up:Connect(function()
print("Button1Up")
end)
end)
You can find out the position of the mouse in world space and if it's pointing at any BasePart using the Hit and Target properties.
Button2Down Supported Event Fires when the right mouse button is pressed.
Fires when the right mouse button is pressed.
This event fires when the player presses their right mouse button. Note
that this can 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)
You can find out the position of the mouse in world space and if it's pointing at any BasePart using the Hit and Target properties.
Button2Up Supported Event Fired when the right mouse button is released.
Fired when the right mouse button is released.
This event fires when the player releases their right mouse button. Note
that this can be accessed from a Tool; for example, when placed in
a LocalScript, the code below prints Button2Up whenever the
right mouse button is released.
local tool = script.Parent -- Make sure this is a Tool object
tool.Equipped:Connect(function(mouse)
mouse.Button2Up:Connect(function()
print("Button2Up")
end)
end)
You can find out the position of the mouse in world space and if it's pointing at any BasePart using the Hit and Target properties.
Idle Supported Event Fired during every heartbeat that the mouse isn't being passed to another mouse event.
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.
KeyDown Supported Event Deprecated Fires when a Key is pressed.
Fires when a Key is pressed.
This event fires when a Key is pressed, with the passed argument being the key that was pressed.
Note:
- Not all keys generate this event. However, you can get around this with a few of the keys, "/" for example, by using the Mouse.KeyUp event.
- Some keys generate the same string as other keys.
- It's possible for the string to be empty (possibly due to "\0" key code).
keyDown Supported Event Deprecated
No description available.
KeyUp Supported Event Deprecated Fires when a Key is released.
Fires when a Key is released.
This event is fired when a Key is released, with the passed argument being the key that was released.
Note:
- Not all keys generate this event. However, you can get around this with a few of the keys, "/" for example, by using the [[API:Class/Mouse/KeyUp|KeyUp]] event.
- Some keys generate the same string as other keys.
- It's possible for the string to be empty (possibly due to "\0" key code).
Move Supported Event Fired when the mouse is moved.
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.
WheelBackward Supported Event Fires when the mouse wheel is scrolled backwards.
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.
WheelForward Supported Event Fires when the mouse wheel is scrolled forwards.
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.
Inherited members¶
Inherited from Instance: 8 properties, 36 methods, 7 events. They are documented on the base class page.
1 modern Roblox member(s) are not implemented yet — expand to inspect
Members declared by Roblox's Mouse class (or by a missing base class) that Nova does not expose. Use this list to scope a migration; the compatibility guide has the recommended workaround.
Properties¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
IconContent |
IconContent: Content |
Not yet | The content of the image used as the Mouse icon. Only supports asset URIs. | — |
Roblox reference: Mouse
Generated from Nova's API dump and Roblox creator-docs. Nova-only members come from the engine's reflection metadata.