Skip to main content

Mouse

This item only works when running on the client. Client

The Mouse class is part of the Input package.

local Mouse = require(packages.Input).Mouse

Properties​

LeftDown​

Event
</>
Mouse.LeftDown: Signal

LeftUp​

Event
</>
Mouse.LeftUp: Signal

RightDown​

Event
</>
Mouse.RightDown: Signal

RightUp​

Event
</>
Mouse.RightUp: Signal

MiddleDown​

Event
</>
Mouse.MiddleDown: Signal

MiddleUp​

Event
</>
Mouse.MiddleUp: Signal

Moved​

Event
</>
Mouse.Moved: Signal<Vector2>
mouse.Moved:Connect(function(position) ... end)

Scrolled​

Event
</>
Mouse.Scrolled: Signal<number>
mouse.Scrolled:Connect(function(scrollAmount) ... end)

Functions​

new​

</>
Mouse.new() → Mouse

Constructs a new mouse input capturer.

local mouse = Mouse.new()

IsLeftDown​

</>
Mouse:IsLeftDown() → boolean

Checks if the left mouse button is down.

IsRightDown​

</>
Mouse:IsRightDown() → boolean

Checks if the right mouse button is down.

IsMiddleDown​

</>
Mouse:IsMiddleDown() → boolean

Checks if the middle mouse button is down.

GetPosition​

</>
Mouse:GetPosition() → Vector2

Gets the screen position of the mouse.

GetDelta​

</>
Mouse:GetDelta() → Vector2

Gets the delta screen position of the mouse. In other words, the distance the mouse has traveled away from its locked position in a given frame (see note about mouse locking below).

Only When Mouse Locked

Getting the mouse delta is only intended for when the mouse is locked. If the mouse is not locked, this will return a zero Vector2. The mouse can be locked using the mouse:Lock() and mouse:LockCenter() method.

GetRay​

</>
Mouse:GetRay(overridePos: Vector2?) → Ray

Returns the viewport point ray for the mouse at the current mouse position (or the override position if provided).

Raycast​

</>
Mouse:Raycast(
raycastParams: RaycastParams,
distance: number?,
overridePos: Vector2?
) → RaycastResult?

Performs a raycast operation out from the mouse position (or the overridePos if provided) into world space. The ray will go distance studs forward (or 1000 studs if not provided).

Returns the RaycastResult if something was hit, else returns nil.

Use Raycast if it is important to capture any objects that could be hit along the projected ray. If objects can be ignored and only the final position of the ray is needed, use Project instead. 

local params = RaycastParams.new()
local result = mouse:Raycast(params)
if result then
	print(result.Instance)
else
	print("Mouse raycast did not hit anything")
end

Project​

</>
Mouse:Project(
distance: number?,
overridePos: Vector2?
) → Vector3

Gets the 3D world position of the mouse when projected forward. This would be the end-position of a raycast if nothing was hit. Similar to Raycast, optional distance and overridePos arguments are allowed.

Use Project if you want to get the 3D world position of the mouse at a given distance but don't care about any objects that could be in the way. It is much faster to project a position into 3D space than to do a full raycast operation. 

local params = RaycastParams.new()
local distance = 200

local result = mouse:Raycast(params, distance)
if result then
	-- Do something with result
else
	-- Raycast failed, but still get the world position of the mouse:
	local worldPosition = mouse:Project(distance)
end

Lock​

</>
Mouse:Lock() → ()

Locks the mouse in its current position on screen. Call mouse:Unlock() to unlock the mouse.

Must explicitly unlock

Be sure to explicitly call mouse:Unlock() before cleaning up the mouse. The Destroy method does not unlock the mouse since there is no way to guarantee who "owns" the mouse lock.

LockCenter​

</>
Mouse:LockCenter() → ()

Locks the mouse in the center of the screen. Call mouse:Unlock() to unlock the mouse.

Must explicitly unlock

See cautionary in Lock method above.

Unlock​

</>
Mouse:Unlock() → ()

Unlocks the mouse.

Destroy​

</>
Mouse:Destroy() → ()

Destroys the mouse.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new mouse input capturer.\n\n```lua\nlocal mouse = Mouse.new()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Mouse"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 81,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "IsLeftDown",
            "desc": "Checks if the left mouse button is down.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 139,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "IsRightDown",
            "desc": "Checks if the right mouse button is down.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 146,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "IsMiddleDown",
            "desc": "Checks if the middle mouse button is down.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 153,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "GetPosition",
            "desc": "Gets the screen position of the mouse.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Vector2\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 160,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "GetDelta",
            "desc": "Gets the delta screen position of the mouse. In other words, the\ndistance the mouse has traveled away from its locked position in\na given frame (see note about mouse locking below).\n\n:::info Only When Mouse Locked\nGetting the mouse delta is only intended for when the mouse is locked. If the\nmouse is _not_ locked, this will return a zero Vector2. The mouse can be locked\nusing the `mouse:Lock()` and `mouse:LockCenter()` method.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Vector2\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 174,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "GetRay",
            "desc": "Returns the viewport point ray for the mouse at the current mouse\nposition (or the override position if provided).",
            "params": [
                {
                    "name": "overridePos",
                    "desc": "",
                    "lua_type": "Vector2?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Ray\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 182,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "Raycast",
            "desc": "Performs a raycast operation out from the mouse position (or the\n`overridePos` if provided) into world space. The ray will go\n`distance` studs forward (or 1000 studs if not provided).\n\nReturns the `RaycastResult` if something was hit, else returns `nil`.\n\nUse `Raycast` if it is important to capture any objects that could be\nhit along the projected ray. If objects can be ignored and only the\nfinal position of the ray is needed, use `Project` instead.\n\n```lua\nlocal params = RaycastParams.new()\nlocal result = mouse:Raycast(params)\nif result then\n\tprint(result.Instance)\nelse\n\tprint(\"Mouse raycast did not hit anything\")\nend\n```",
            "params": [
                {
                    "name": "raycastParams",
                    "desc": "",
                    "lua_type": "RaycastParams"
                },
                {
                    "name": "distance",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "overridePos",
                    "desc": "",
                    "lua_type": "Vector2?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "RaycastResult?\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 209,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "Project",
            "desc": "Gets the 3D world position of the mouse when projected forward. This would be the\nend-position of a raycast if nothing was hit. Similar to `Raycast`, optional\n`distance` and `overridePos` arguments are allowed.\n\nUse `Project` if you want to get the 3D world position of the mouse at a given\ndistance but don't care about any objects that could be in the way. It is much\nfaster to project a position into 3D space than to do a full raycast operation.\n\n```lua\nlocal params = RaycastParams.new()\nlocal distance = 200\n\nlocal result = mouse:Raycast(params, distance)\nif result then\n\t-- Do something with result\nelse\n\t-- Raycast failed, but still get the world position of the mouse:\n\tlocal worldPosition = mouse:Project(distance)\nend\n```",
            "params": [
                {
                    "name": "distance",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "overridePos",
                    "desc": "",
                    "lua_type": "Vector2?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Vector3\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 241,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "Lock",
            "desc": "Locks the mouse in its current position on screen. Call `mouse:Unlock()`\nto unlock the mouse.\n\n:::caution Must explicitly unlock\nBe sure to explicitly call `mouse:Unlock()` before cleaning up the mouse.\nThe `Destroy` method does _not_ unlock the mouse since there is no way\nto guarantee who \"owns\" the mouse lock.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 255,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "LockCenter",
            "desc": "Locks the mouse in the center of the screen. Call `mouse:Unlock()`\nto unlock the mouse.\n\n:::caution Must explicitly unlock\nSee cautionary in `Lock` method above.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 266,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "Unlock",
            "desc": "Unlocks the mouse.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 273,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "Destroy",
            "desc": "Destroys the mouse.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 280,
                "path": "modules/input/Mouse.lua"
            }
        }
    ],
    "properties": [
        {
            "name": "LeftDown",
            "desc": "",
            "lua_type": "Signal",
            "tags": [
                "Event"
            ],
            "source": {
                "line": 30,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "LeftUp",
            "desc": "",
            "lua_type": "Signal",
            "tags": [
                "Event"
            ],
            "source": {
                "line": 35,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "RightDown",
            "desc": "",
            "lua_type": "Signal",
            "tags": [
                "Event"
            ],
            "source": {
                "line": 40,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "RightUp",
            "desc": "",
            "lua_type": "Signal",
            "tags": [
                "Event"
            ],
            "source": {
                "line": 45,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "MiddleDown",
            "desc": "",
            "lua_type": "Signal",
            "tags": [
                "Event"
            ],
            "source": {
                "line": 50,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "MiddleUp",
            "desc": "",
            "lua_type": "Signal",
            "tags": [
                "Event"
            ],
            "source": {
                "line": 55,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "Moved",
            "desc": "```lua\nmouse.Moved:Connect(function(position) ... end)\n```",
            "lua_type": "Signal<Vector2>",
            "tags": [
                "Event"
            ],
            "source": {
                "line": 63,
                "path": "modules/input/Mouse.lua"
            }
        },
        {
            "name": "Scrolled",
            "desc": "```lua\nmouse.Scrolled:Connect(function(scrollAmount) ... end)\n```",
            "lua_type": "Signal<number>",
            "tags": [
                "Event"
            ],
            "source": {
                "line": 71,
                "path": "modules/input/Mouse.lua"
            }
        }
    ],
    "types": [],
    "name": "Mouse",
    "desc": "The Mouse class is part of the Input package.\n\n```lua\nlocal Mouse = require(packages.Input).Mouse\n```",
    "realm": [
        "Client"
    ],
    "source": {
        "line": 22,
        "path": "modules/input/Mouse.lua"
    }
}