PlayerMouse

Show Deprecated
Not Creatable

The PlayerMouse behaves identically to the Mouse object that is obtained using Tool.Equipped. It can be accessed from LocalScripts using the local player's Player:GetMouse() method. Both PlayerMouse and Mouse are legacy APIs, superseded by UserInputService.

The only difference between the PlayerMouse and the Mouse object is the PlayerMouse can be obtained using the Player:GetMouse() method.

In most cases developers are advised to use the new UserInputService. However the PlayerMouse and Mouse objects remain supported for a number of reasons. See Input and Camera for more information on customizing inputs in your experience.

Code Samples

This code sample includes a simple example of how the local player's PlayerMouse can be retrieved using the Player:GetMouse() function in a LocalScript. This code should be placed in a LocalScript in StarterPlayerScripts.

PlayerMouse
local Players = game:GetService("Players")



local player = Players.LocalPlayer



local mouse = player:GetMouse()



local function onMouseMove()

	print("mouse screen position: ", mouse.X, mouse.Y)

end



mouse.Move:Connect(onMouseMove)

Summary

Properties

Properties inherited from Mouse
  • Hit:CFrame
    Read Only
    Not Replicated
    Read Parallel

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

  • Icon:ContentId
    Read Parallel

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

  • Origin:CFrame
    Read Only
    Not Replicated
    Read Parallel

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

  • Target:BasePart
    Read Only
    Not Replicated
    Read Parallel

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

  • TargetFilter:Instance
    Read Parallel

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

  • TargetSurface:Enum.NormalId
    Read Only
    Not Replicated
    Read Parallel

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

  • UnitRay:Ray
    Read Only
    Not Replicated
    Read Parallel

    A Ray directed towards the mouse's world position, originating from the Workspace.CurrentCamera world position.

  • ViewSizeX:number
    Read Only
    Not Replicated
    Read Parallel

    Describes the width of the game window in pixels.

  • ViewSizeY:number
    Read Only
    Not Replicated
    Read Parallel

    Describes the height of the game window in pixels.

  • X:number
    Read Only
    Not Replicated
    Read Parallel

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

  • Y:number
    Read Only
    Not Replicated
    Read Parallel

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

View all inherited from Instance
View all inherited from Object

Events

Events inherited from Mouse
View all inherited from Instance
View all inherited from Object

Properties

Properties inherited from Mouse

Hit

CFrame
Read Only
Not Replicated
Read Parallel

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)

Icon

ContentId
Read Parallel

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

CFrame
Read Only
Not Replicated
Read Parallel

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

BasePart
Read Only
Not Replicated
Read Parallel

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

Instance
Read Parallel

TargetSurface

Enum.NormalId
Read Only
Not Replicated
Read Parallel

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

Ray
Read Only
Not Replicated
Read Parallel

ViewSizeX

number
Read Only
Not Replicated
Read Parallel

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

number
Read Only
Not Replicated
Read Parallel

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)

X

number
Read Only
Not Replicated
Read Parallel

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)

Y

number
Read Only
Not Replicated
Read Parallel

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)
View all inherited from Instance
View all inherited from Object

Methods

View all inherited from Instance
View all inherited from Object

Events

View all inherited from Instance
View all inherited from Object