We use cookies on this site to enhance your user experience

Intro to Player Input

Intro to Player Input

Oct 09 2019, 11:06 AM PST 10 min

Every game needs to receive player input in some way. On Roblox, there are various ways to process input using articles/events|events. Before continuing, you should be fairly comfortable with using articles/events|events since input processing is almost entirely event-based.

Input on 3D Objects

The ClickDetector object is perhaps the simplest form of input on Roblox. It detects mouse clicks (or taps) on 3D objects and fires its ClickDetector/MouseClick|MouseClick event. You can insert a click detector in Studio or use Instance.new() to begin detecting player clicks on a Model or Part:

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

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

Click detectors work in either a Script or LocalScript. They also have three other events:

Event Description
ClickDetector/MouseHoverEnter|MouseHoverEnter Fires when the mouse pointer hovers over the detector object. On mobile devices, 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.
ClickDetector/MouseHoverLeave|MouseHoverLeave Fires when the mouse pointer hovers off the detector object. On mobile, 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.
ClickDetector/RightMouseClick|RightMouseClick Fires when the player right-clicks the mouse over the detector object. This event does not function on mobile devices.

Generic Mouse Input

Perhaps you need generic mouse input instead of one object in particular. For this, you can use the Player/GetMouse|Player:GetMouse() function which returns a PlayerMouse object. This houses a handful of useful mouse properties and events.

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

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

Keyboard Input

The keyboard is a wonderful tool for exposing many options to the player at once. The easiest way to access keyboard events is through the UserInputService/InputEnded event which fires when any general user input ends. Like mouse events, this only works inside a LocalScript.

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 can be 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)

User Interface Input

All on-screen user interfaces house their own input events. Button-type objects like TextButton|TextButtons and ImageButton|ImageButtons are particularly useful for single-action input. See /articles/Creating GUI Buttons|Creating GUI Buttons for details and examples.

Text Input

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

  1. Insert a new ScreenGui into the StarterGui folder.
  2. Insert a TextBox into the ScreenGui, then create a new LocalScript as a child of the TextBox.
  3. Paste the following code into the script — this will set the background color of the TextBox to a valid user-typed /datatype/BrickColor|BrickColor, for instance “Bright red” or “Electric blue.”
local textBox = script.Parent

local function onFocusLost(enterPressed)
	if enterPressed then
		print("The player typed: " .. textBox.Text)
		-- Color the text box according to the typed color
		local brickColor = BrickColor.new(textBox.Text)
		textBox.BackgroundColor3 = brickColor.Color
  • input
  • interactivity
  • mouse
  • click
  • tap
  • button