PcoWSkbVqDnWTu_dm2ix
We use cookies on this site to enhance your user experience
Collapse Sidebar

UserInputService

Show deprecated

UserInputService

Show deprecated

The UserInputService is a service used to detect and capture the different types of input available on a user’s device.

The primary purpose of this service is to allow for games to cooperate with multiple forms of available input - such as gamepads, touch screens, and keyboards. It allows a LocalScript to perform different actions depending on the device, and in turn, helps developers provide the best experience for the end user.

Some usages of this service include detecting user input when they interact with GUIs, tools, and other game instances. In order to detect user input, the service must look for a service event. For example, the service can detect events such as when the user touches the screen of a mobile device using UserInputService/TouchStarted, or connects a gamepad such as an Xbox controller to their device using UserInputService/GamepadConnected.

Since this service is client-side only, it will only work when used in a LocalScript or a ModuleScript required by a LocalScript. As UserInputService is client-side only, users in the game can only detect their own input - and not the input of others.

See also

  • ContextActionService, a service which allows you to bind functions to multiple user inputs

Properties

bool

AccelerometerEnabled

[ReadOnly] [NotReplicated]

Describes whether the user’s device has an accelerometer

bool

GamepadEnabled

[ReadOnly] [NotReplicated]

Describes whether the device being used by a user has an available gamepad

bool

GyroscopeEnabled

[ReadOnly] [NotReplicated]

Indicates if the user’s device has a gyroscope

bool

KeyboardEnabled

[ReadOnly] [NotReplicated]

Becomes true if the device being used by a user has a keyboard available

bool

ModalEnabled

Toggles whether Roblox’s mobile controls are hidden on mobile devices

MouseBehavior

MouseBehavior

Determines whether the user’s mouse can be moved freely or is locked

float

MouseDeltaSensitivity

[NotReplicated]

Scales the delta (change) output of the user’s Mouse

bool

MouseEnabled

[ReadOnly] [NotReplicated]

Describes whether the user’s device has a mouse available

bool

MouseIconEnabled

Determines whether the Mouse|Mouse’s icon is visible

Vector2

OnScreenKeyboardPosition

[ReadOnly] [NotReplicated]

Determines the position of the on-screen keyboard

Vector2

OnScreenKeyboardSize

[ReadOnly] [NotReplicated]

Determines the size of the on-screen keyboard

bool

OnScreenKeyboardVisible

[ReadOnly] [NotReplicated]

Describes whether an on-screen keyboard is currently visible on the user’s screen

bool

TouchEnabled

[ReadOnly] [NotReplicated]

Describes whether the user’s current device has a touch-screen available

bool

VREnabled

[ReadOnly] [NotReplicated]

Indicates whether the user is using a virtual reality headset

Inherited from Instance: Show Hide

int

DataCost

[ReadOnly] [NotReplicated]
The cost of saving the instance using data persistence.
Instance

Parent

Determines the hierarchical parent of the `Instance`.
bool

RobloxLocked

If true, the `Instance` and its descendants cannot be indexed or edited by a `Script` or `LocalScript` and will throw an error if it is attempted.
string

ClassName

[ReadOnly] [NotReplicated]
A read-only string representing the class this `Instance` belongs to.
string

Name

A non-unique identifier of the `Instance`.
bool

Archivable

Determines if an `Instance` can be cloned using `/Instance/Clone` or saved to file.

Functions

bool

GamepadSupports ( UserInputType gamepadNum , KeyCode gamepadKeyCode )

Returns if specified gamepad supports the corresponding Enum/KeyCode button

Array

GetConnectedGamepads ( )

Returns an array of Enum/UserInputType gamepads currently connected

Instance

GetDeviceAcceleration ( )

Returns an InputObject that describes the device’s current acceleration

Instance

GetDeviceGravity ( )

Returns an InputObject describing the device’s current gravity vector

Tuple

GetDeviceRotation ( )

Returns an InputObject and a DataType/CFrame that describes the device’s current rotation vector

Instance

GetFocusedTextBox ( )

Returns the currently selected TextBox, or nil if none is selected

bool

GetGamepadConnected ( UserInputType gamepadNum )

Returns true if ‘‘gamepadNum’’ is connected to the client

Array

GetGamepadState ( UserInputType gamepadNum )

Returns an array of InputObject for each input on the gamepad with each input’s last input state

Array

GetKeysPressed ( )

Returns a table of InputObject|InputObjects, whoseEnum/KeyCodes` are currently being pressed

UserInputType

GetLastInputType ( )

Returns the most recent 'EnumUserInputType` that the used by the client

Array

GetMouseButtonsPressed ( )

Returns an array of InputObject|InputObjects that corresponds to all the mouse buttons being currently pressed down

Vector2

GetMouseDelta ( )

Returns the change, in pixels, of the position of the player’s Mouse in the last rendered frame. Only works if the mouse is locked

Vector2

GetMouseLocation ( )

Returns the current screen location of the player’s Mouse

Array

GetNavigationGamepads ( )

Returns an array of Enum/UserInputType|gamepads connected and enabled for GUI navigation in descending order of priority

Array

GetSupportedGamepadKeyCodes ( UserInputType gamepadNum )

Returns the Enum/KeyCode that the connected gamepadNum supports

CFrame

GetUserCFrame ( UserCFrame type )

Returns a DataType/CFrame describing the position and orientation of a specified virtual reality device

bool

IsGamepadButtonDown ( UserInputType gamepadNum , KeyCode gamepadKeyCode )

Returns whether the given Enum/KeyCode|button is currently held down on the given Enum/UserInputType/gamepad

bool

IsKeyDown ( KeyCode keyCode )

Returns whether the given Enum/KeyCode|key is currently held down

bool

IsMouseButtonPressed ( UserInputType mouseButton )

Returns whether the given Enum/UserInputType|mouse button is currently held down

bool

IsNavigationGamepad ( UserInputType gamepadEnum )

Returns true if the specified Enum/UserInputTypeGamepad is allowed to control the navigation GuiObject|GUIs

void

RecenterUserHeadCFrame ( )

Recenters the DataType/CFrame to the current location of the VR headset being worn by the user

void

SetNavigationGamepad ( UserInputType gamepadEnum , bool enabled )

Sets whether or not the specified Gamepad is allowed to move the GuiObject|GUI navigator around

Inherited from Instance: Show Hide

string

GetFullName ( )

Returns a string describing the `Instance`'s ancestry.
RBXScriptSignal

GetPropertyChangedSignal ( string property )

Get an event that fires when a given property of an object changes.
Instance

FindFirstChildWhichIsA ( string className , bool recursive )

Returns the first child of the `Instance` for whom `Instance/IsA` returns true for the given className.
Array

GetDescendants ( )

[CustomLuaState]
Returns an array containing all of the `Instance`'s descendants.
bool

IsAncestorOf ( Instance descendant )

Returns true if an `Instance` is an ancestor of the given descendant.
bool

IsDescendantOf ( Instance ancestor )

Returns true if an `Instance` is a descendant of the given ancestor.
Instance

FindFirstChildOfClass ( string className )

Returns the first child of the `Instance` whose `Instance/ClassName|ClassName` is equal to the given className.
Instance

FindFirstChild ( string name , bool recursive )

Returns the first child of the `Instance` found with the given name.
Instance

FindFirstAncestorWhichIsA ( string className )

Returns the first ancestor of the `Instance` for whom `Instance/IsA` returns true for the given className.
Instance

FindFirstAncestorOfClass ( string className )

Returns the first ancestor of the `Instance` whose `Instance/ClassName` is equal to the given className.
Instance

FindFirstAncestor ( string name )

Returns the first ancestor of the `Instance` whose `Instance/Name` is equal to the given name.
bool

IsA ( string className )

Returns true if an `Instance`'s class matches or inherits from a given class
Instance

WaitForChild ( string childName , double timeOut )

[CustomLuaState] [CanYield]
Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.
string

GetDebugId ( int scopeLength )

[NotBrowsable]
Returns a coded string of the `Instance`s DebugId used internally by Roblox.
Objects

GetChildren ( )

Returns an array containing all of the `Instance`'s children.
void

Destroy ( )

Sets the `Instance/Parent` property to nil, locks the `Instance/Parent` property, disconnects all connections and calls Destroy on all children.
Instance

Clone ( )

Create a deep copy of a Roblox instance and descendants where `Archivable = true`.
void

ClearAllChildren ( )

This function destroys all of an `Instance`'s children.

Events

RBXScriptSignal

DeviceAccelerationChanged ( Instance acceleration )

Fired when a user moves a device that has an accelerometer. Used to track real-world device movement within a Roblox game

RBXScriptSignal

DeviceGravityChanged ( Instance gravity )

Fired when the force of gravity changes on a device that has an enabled accelerometer - such as a mobile device

RBXScriptSignal

DeviceRotationChanged ( Instance rotation , CFrame cframe )

Fired when a user rotates a device that has a gyroscope

RBXScriptSignal

GamepadConnected ( UserInputType gamepadNum )

Fires when a gamepad is connected to the client. Passes the ‘‘gamepadNum’’ of the gamepad that was connected

RBXScriptSignal

GamepadDisconnected ( UserInputType gamepadNum )

Fires when a gamepad is disconnected from the client. Passes the Enum/UserInputType of the gamepad that was disconnected

RBXScriptSignal

InputBegan ( Instance input , bool gameProcessedEvent )

Fired when a user begins interacting via a Human-Computer Interface device - such as a mouse or gamepad

RBXScriptSignal

InputChanged ( Instance input , bool gameProcessedEvent )

Fired when a user changes how they’re interacting via a Human-Computer Interface device

RBXScriptSignal

InputEnded ( Instance input , bool gameProcessedEvent )

Fires when a user stops interacting via a Human-Computer Interface device

RBXScriptSignal

JumpRequest ( )

Fires whenever the client makes a request for their character to jump

RBXScriptSignal

LastInputTypeChanged ( UserInputType lastInputType )

Fires when the client’s UserInputService/UserInputType is changed

RBXScriptSignal

TextBoxFocusReleased ( Instance textboxReleased )

Fired when the client loses focus on a TextBox

RBXScriptSignal

TextBoxFocused ( Instance textboxFocused )

Fired when the client focuses on a TextBox

RBXScriptSignal

TouchEnded ( Instance touch , bool gameProcessedEvent )

Fired when a user releases their finger from the screen on a TouchEnabled device - such as the screen of a mobile device

RBXScriptSignal

TouchLongPress ( Array touchPositions , UserInputState state , bool gameProcessedEvent )

Fired when a user holds at least one finger for a short amount of time on the same screen position on a TouchEnabled device - such as the screen of a mobile device

RBXScriptSignal

TouchMoved ( Instance touch , bool gameProcessedEvent )

Fired when a user moves their finger on a TouchEnabled device - such as the screen of an Apple iPad or iPhone or a Google Android phone

RBXScriptSignal

TouchPan ( Array touchPositions , Vector2 totalTranslation , Vector2 velocity , UserInputState state , bool gameProcessedEvent )

Fired when a user drags at least one finger on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of an mobile device

RBXScriptSignal

TouchPinch ( Array touchPositions , float scale , float velocity , UserInputState state , bool gameProcessedEvent )

Fired when a user pinches their fingers on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of a mobile device

RBXScriptSignal

TouchRotate ( Array touchPositions , float rotation , float velocity , UserInputState state , bool gameProcessedEvent )

Fires when a user rotates two fingers on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of a mobile device

RBXScriptSignal

TouchStarted ( Instance touch , bool gameProcessedEvent )

Fired when a user places their finger on a TouchEnabled device - such as the screen of an Apple iPad or iPhone or a Google Android phone

RBXScriptSignal

TouchSwipe ( SwipeDirection swipeDirection , int numberOfTouches , bool gameProcessedEvent )

Fired when a user swipes their fingers on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of a mobile device

RBXScriptSignal

TouchTap ( Array touchPositions , bool gameProcessedEvent )

Fired when a user taps their finger on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of a mobile device

RBXScriptSignal

TouchTapInWorld ( Vector2 position , bool processedByUI )

Fires when a user taps the game world on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of a mobile device

RBXScriptSignal

UserCFrameChanged ( UserCFrame type , CFrame value )

Fires when the DataType/CFrame of a specified Virtual Reality device changes

RBXScriptSignal

WindowFocusReleased ( )

Fires when the window of the Roblox client loses focus on the user’s screen

RBXScriptSignal

WindowFocused ( )

Fires when the window of the Roblox client gains focus on the user’s screen

Inherited from Instance: Show Hide

RBXScriptSignal

DescendantRemoving ( Instance descendant )

Fires immediately before a descendant of the `Instance` is removed.
RBXScriptSignal

AncestryChanged ( Instance child , Instance parent )

Fires when the `Instance/Parent` property of the object or one of its ancestors is changed.
RBXScriptSignal

ChildAdded ( Instance child )

Fires when an object is parented to this `Instance`.
RBXScriptSignal

ChildRemoved ( Instance child )

Fires when a child is removed from this `Instance`.
RBXScriptSignal

DescendantAdded ( Instance descendant )

Fires when a descendant is added to the `Instance`.
RBXScriptSignal

Changed ( string property )

Fired immediately after a property of an object changes.