Mouse and Keyboard Input | Documentation - Roblox Creator Hub (2024)

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.

Additionally, you can use ContextActionService to handle multiple actions on a single input depending on context, such as using a tool when near a rock, or opening a door when inside a building. See Context Dependent Inputs for information on setting context specific input actions.

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
See Also
How to Change Keybinds Controls In Roblox [Step-By-Step Guide]LVNDMARK’s Gaming Setup: An In-Depth Look
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)

UI Input

Mouse and keyboard input automatically works with interactive UI elements such as TextButtons and ImageButtons, as well as TextBoxes which capture text input like a field in a form.

For more information on creating buttons and text input objects, see Buttons and Text Input.

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 user's mouse icon within your experience to create a cohesive style across all of your UI elements. This includes temporarily changing the user's mouse icon in specific circ*mstances, such as hovering over a button.

Changing the Icon

You can change the user'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 user's default mouse icon to a circle with a blue dot in the middle:

local UserInputService = game:GetService("UserInputService")
UserInputService.MouseIcon = "rbxassetid://3400146391"

Hiding the Icon

You can hide the user'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

Locking 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 user's mouse icon is locked in a position, UserInputService.InputChanged still fires when the user moves the mouse, passing in the distance the mouse has moved. For example, the following code sample locks the user's mouse icon after one second, then Studio prints the mouse delta whenever the user 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. Excluding the reserved bindings, you can use ContextActionService to create cross‑platform binds that prioritize multiple bindings to a single action, as described in Context-Dependent Inputs.

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 users are familiar with these controls, so you should only override them in specific cases.