Mouse and Keyboard

You can create unique experiences and provide users with additional functionality with custom inputs. Mouse and keyboards are the most common input devices, so it is important to test and develop your custom input behavior on these devices first. Once you're comfortable with mouse and keyboard inputs, make your experience compatible with multiple platforms by setting up mobile and gamepad inputs.

For convenience, Roblox sets the most common mouse and keyboard inputs as default key binds. Except for the reserved bindings, you can overwrite these default key binds.

Mouse Input

You can detect mouse position and button clicks using the UserInputService to capture generic mouse inputs. Roblox also supports legacy mouse input detection with PlayerMouse and ClickDetectors.

Mouse inputs also automatically work with interactive UI elements, such as TextBoxes or ImageButtons.

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.

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.

To capture mouse clicks and print the position of the mouse to the output, use the following script in a LocalScript in StarterPlayerScripts:

local UserInputService = game:GetService("UserInputService")

local function onInputEnded(inputObject, gameProcessedEvent)
	-- First check if the "gameProcessedEvent" is true
	-- This indicates that another script had already processed the input, so this one is ignored
	if gameProcessedEvent 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)

PlayerMouse

You can also use the legacy Player:GetMouse() function to return a PlayerMouse object that handles general mouse properties and events.

Since Player:GetMouse() only works when using a LocalScript, access Players.LocalPlayer to get a reference to the local player and, in StarterPlayer, parent the script to StarterPlayerScripts so that it later runs when copied to PlayerScripts.

Use the following script in a LocalScript in StarterPlayerScripts to print the mouse coordinates whenever the mouse is clicked:

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local mouse = player:GetMouse()

local function onMouseClick()
	print(player.Name .. " clicked at position: " .. tostring(mouse.Hit.Position))
	if mouse.Target then
		print("Clicked part: " .. mouse.Target:GetFullName())
	else
		print("No part clicked")
	end
end

mouse.Button1Down:Connect(onMouseClick)

ClickDetector

A ClickDetector object is a simple way of detecting mouse events on a specific 3D object in an experience. You can add a ClickDetector instance to any existing Model or Part to begin detecting player clicks.

To create a new ClickDetector on a part and change the color of its parent when the part is clicked, use the following code sample in a Script or LocalScript:

local clickPart = script.Parent
-- Create a ClickDetector and set its parent
local clickDetector = Instance.new("ClickDetector")
clickDetector.Parent = clickPart

local function onPartClick(player)
	-- Output a message and randomly color the clicked part
	print(player.Name .. " clicked me!")
	clickPart.BrickColor = BrickColor.random()
end

clickDetector.MouseClick:Connect(onPartClick)

ClickDetector also has three other events that you can use to track mouse inputs:

• MouseHoverEnter: Fires when the mouse pointer hovers over the detector object. If on a mobile device, this only fires when the player initially taps the detector object to "activate" it, and when they drag their finger off and back over the detector during a subsequent touch.
• MouseHoverLeave: Fires when the mouse pointer hovers off the detector object. If on a mobile device, this only fires when the player initially taps the detector object to "activate" it and then either taps somewhere off the detector, or drags their finger off the detector following a subsequent touch.
• RightMouseClick: Fires when the player right-clicks the mouse over the detector object. This event does not function on mobile devices.

Keyboard Input

Keyboard inputs provide the largest variety of inputs for users. You can listen for generic keyboard inputs, such as a specific key being pressed, or set up a TextBox to capture a user's text input.

Roblox has several preset key bindings which are enabled by default.

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.

Use the following sample code in a LocalScript to print the keycode of a pressed key:

local UserInputService = game:GetService("UserInputService")

local function onInputEnded(inputObject, gameProcessedEvent)
	-- First check if the "gameProcessedEvent" is true
	-- This indicates that another script had already processed the input, so this one is ignored.
	if gameProcessedEvent 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)

Text Input

A TextBox is a special UI object designed to capture text input, like a text field in a form. Its Text property is changed as the player types into it, and the FocusLost event fires after the player is done typing.

For more information on creating a TextBox and other clickable UI elements, see Buttons and Text.

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.

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

Global

These bindings are Roblox defaults, but you can override them with custom scripts.

Feature Specific

Some CoreGui features also have default bindings. These inputs are reserved by the features unless you disable the respective feature using SetCoreGuiEnabled().

Reserved

Roblox reserves system specific keyboard inputs that you can't change, disable, or override.

Binding and Unbinding Actions

All supported inputs can have an action bound to them using ContextActionService. Excluding reserved bindings, you can use ContextActionService to edit the actions of the Roblox default bindings.

While testing an experience, F9 opens up a Developer Console where current bindings and action names are listed under ActionBindings. You can use this to see the current active binds in your experience.

To unbind Roblox's default moveForwardAction from the W key, use the following sample code in a LocalScript in StarterGui:

local ContextActionService = game:GetService("ContextActionService")

ContextActionService:UnbindAction("moveForwardAction")

To bind the W key to another function, use the following sample code in a LocalScript in StarterGui:

local ContextActionService = game:GetService("ContextActionService")

local function warnUserPrompt()
	print("No moving forward!")
end

ContextActionService:BindAction("warnUser",warnUserPrompt,false, Enum.KeyCode.W)

For more information on implementing using ContextActionService to create cross-platform binds and prioritizing multiple bindings to a single input, see Context Dependent Inputs.

Movement Modes

Roblox offers several StarterPlayer properties you can set to change how users on desktop devices can move through your experience.

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