Mouse and keyboard input

A large percentage of Roblox sessions are played on devices with a mouse and keyboard, so it's important to properly support these inputs when designing an experience for a wide audience. Once you're comfortable with mouse and keyboard inputs, make your experience compatible across multiple platforms by setting up mobile and gamepad inputs.

For convenience, Roblox sets the most common mouse and keyboard inputs as default bindings which, except for the reserved bindings, you can overwrite.

Generic mouse input

Like all device inputs, you can capture mouse inputs using UserInputService. This service provides a scalable way to capture input changes and device input states for multiple devices at once. Roblox also supports legacy mouse input detection with PlayerMouse and ClickDetectors.

The following LocalScript, when placed in StarterPlayerScripts, captures mouse clicks and prints the mouse position to the Output window:

LocalScript - Output Mouse Click and Position
local UserInputService = game:GetService("UserInputService")

local function onInputEnded(inputObject, processedEvent)
	-- First check if the "processedEvent" is true
	-- This indicates that another script had already processed the input, so this one is ignored
	if processedEvent then return end

	-- Next, check that the input was a mouse event
	if inputObject.UserInputType == Enum.UserInputType.MouseButton1 then
		print("Left Mouse button was pressed:", inputObject.Position)
	elseif inputObject.UserInputType == Enum.UserInputType.MouseButton2 then
		print("Right Mouse button was pressed:", inputObject.Position)
	end
end

UserInputService.InputEnded:Connect(onInputEnded)

Generic keyboard input

To access keyboard events, use the UserInputService.InputEnded event to track whenever any keystroke or other input ends. Similar to mouse events, this event only works within a LocalScript.

The following LocalScript, when placed in StarterPlayerScripts, prints the Enum.KeyCode of a pressed key to the Output window:

local UserInputService = game:GetService("UserInputService")

local function onInputEnded(inputObject, processedEvent)
	-- First check if the "processedEvent" is true
	-- This indicates that another script had already processed the input, so this one is ignored.
	if processedEvent then return end

	-- Next, check that the input was a keyboard event
	if inputObject.UserInputType == Enum.UserInputType.Keyboard then
		print("A key was released: " .. inputObject.KeyCode.Name)
	end
end

UserInputService.InputEnded:Connect(onInputEnded)

Character movement modes

You can set mouse and keyboard movement controls schemes for Roblox experiences by changing the values of StarterPlayer.DevComputerMovementMode to one of the following:

Mouse icons

You can customize the appearance and behavior of a player's mouse icon within your experience to create a cohesive style across all of your UI elements. This includes temporarily changing the player's mouse icon in specific circumstances, such as hovering over a button.

Change the icon

You can change the player's mouse icon in a LocalScript by setting the MouseIcon property in UserInputService to a custom Roblox asset ID. For example, the following LocalScript changes the player's default mouse icon to a circle with a blue dot in the middle:

local UserInputService = game:GetService("UserInputService")

UserInputService.MouseIcon = "rbxassetid://3400146391"

Hide the icon

You can hide the player's mouse icon by setting the UserInputService.MouseIconEnabled to false in a LocalScript. For example, the following code switches the mouse icon from visible to invisible and back every two seconds:

local UserInputService = game:GetService("UserInputService")

while true do
	task.wait(2)
	UserInputService.MouseIconEnabled = false
	task.wait(2)
	UserInputService.MouseIconEnabled = true
end

Lock the icon

You can lock the mouse icon's position to the screen using UserInputService.MouseBehavior with a Enum.MouseBehavior value of LockCurrentPosition or LockCenter, then unlock it again with a value of Default.

If a player's mouse icon is locked in a position, UserInputService.InputChanged still fires when the player moves the mouse, passing in the distance the mouse has moved. For example, the following code sample locks the player's mouse icon after one second, then Studio prints the mouse delta whenever the player moves their mouse:

local UserInputService = game:GetService("UserInputService")

task.wait(5)

UserInputService.MouseBehavior = Enum.MouseBehavior.LockCurrentPosition

UserInputService.InputChanged:Connect(function(inputObject)
	if inputObject.UserInputType == Enum.UserInputType.MouseMovement then
		print("Mouse delta is (" .. tostring(inputObject.Delta.X) .. ", " ..  tostring(inputObject.Delta.Y) .. ")")
	end
end)

Roblox default bindings

Roblox provides default key bindings for all experiences. These are the most common inputs used for movement, camera control, and basic environment interaction.

Enum.CoreGuiType features, such as the Backpack or Chat, have a list of additional default inputs. You can't overwrite reserved inputs such as Esc (Roblox menu) or F9 (Developer Console).

These bindings are Roblox defaults, but you can override them with custom scripts. Most Roblox players are familiar with these controls, so you should only override them in specific cases.