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.
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 ignoredif gameProcessedEvent then return end-- Next, check that the input was a mouse eventif inputObject.UserInputType == Enum.UserInputType.MouseButton1 thenprint("Left Mouse button was pressed: ", inputObject.Position)elseif inputObject.UserInputType == Enum.UserInputType.MouseButton2 thenprint("Right Mouse button was pressed: ", inputObject.Position)endendUserInputService.InputEnded:Connect(onInputEnded)
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.LocalPlayerlocal mouse = player:GetMouse()local function onMouseClick()print(player.Name .. " clicked at position: " .. tostring(mouse.Hit.Position))if mouse.Target thenprint("Clicked part: " .. mouse.Target:GetFullName())elseprint("No part clicked")endendmouse.Button1Down:Connect(onMouseClick)
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 parentlocal clickDetector = Instance.new("ClickDetector")clickDetector.Parent = clickPartlocal function onPartClick(player)-- Output a message and randomly color the clicked partprint(player.Name .. " clicked me!")clickPart.BrickColor = BrickColor.random()endclickDetector.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 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 eventif inputObject.UserInputType == Enum.UserInputType.Keyboard thenprint("A key was released: " .. inputObject.KeyCode.Name)endendUserInputService.InputEnded:Connect(onInputEnded)
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).
These bindings are Roblox defaults, but you can override them with custom scripts.
|Key or Event||Action|
|W / Up Arrow||Move forward|
|S / Down Arrow||Move backward|
|Left||Rotate camera left|
|Right||Rotate camera right|
|Shift||Toggle mouselock (if EnableMouseLockOption is enabled)|
|Mouse.WheelForward / Mouse.WheelBackward||Zoom in/out|
|Backslash||Toggle UI navigation|
Some CoreGui features also have default bindings. These inputs are reserved by the features unless you disable the respective feature using SetCoreGuiEnabled().
|Key or Event||Feature||Action|
|Numbers 0-9||Backpack||Equip/unequip tools|
|Tab||Playerlist||Show/hide player list|
Roblox reserves system specific keyboard inputs that you can't change, disable, or override.
|Key or Event||Action|
|F12 (Windows)||Record video|
|Control+Shift+F7 (Windows) / Control+Alt+F7 (Mac)||Performance stats|
|Control+P||Pause Microprofiler, if displayed|
|Printscreen (Windows) / Control+Shift+3 (Mac)||Take Screenshot|
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!")endContextActionService: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.
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:
|ClickToMove||Users can only move through the experience by right-clicking a target location.|
|KeyboardMouse||User can only use default W A S D or the arrow keys to move and Space to jump. This is the default user setting for keyboard and mouse users if UserChoice is set.|
|Scriptable||Disables all default controls and allows you to bind your own controls.|
|UserChoice||Allows users to choose their desired control scheme from the in-experience Settings menu. This option is enabled by default.|