UserInputService

UserInputService : Instance

Overview

A client-only service that detects input from the user's device.

It allows you to tailor behavior based on different input devices such as keyboard, mouse, and touchscreen, delivering a platform-optimized user experience.

This service can only be used in client-side environments like LocalScript.

Properties

Methods

Events

TouchStarted

This event is triggered when the user touches the screen.

It's useful for detecting the start of touch-based interactions, and when used alongside TouchMoved and TouchEnded, it allows you to effectively track the entire touch interaction from beginning, movement, to end.

Parameters

InputObject InputObject

This Object contains detailed information about an input, and remains the same instance from the start to the end of a single touch. This means you can track and distinguish multiple touches by comparing these Objects. Enum.KeyCode KeyCode: Key input Enum.UserInputState UserInputState: Input state Enum.UserInputType UserInputType: Input device type Vector3 Delta: Movement delta (Z-axis is always 0) Vector3 Position: Input position on screen (Z-axis is always 0)

bool bGameProcessed

Indicates whether the input has already been handled by a UI element on the screen. UI elements that can affect input include: System UI such as the chat window or menu buttons Buttons bound through ContextActionService GUI buttons within ScreenGui or SurfaceGui that have Active set to true

Code Samples

local UserInputService = game:GetService("UserInputService")

local function OnScreenTouchStart(input, _gameProcessed)
    local keyCode = input.KeyCode        
    local inputState = input.UserInputState 
    local inputType = input.UserInputType   
    local delta = input.Delta
    local pos = input.Position    
end
UserInputService.TouchStarted:Connect(OnScreenTouchStart)

TouchMoved

This event is triggered when the user moves their finger on the screen.

It tracks the finger's position in real-time, making it useful for detecting gesture-based inputs like dragging or swiping.

Parameters

InputObject InputObject

This Object contains detailed information about an input, and remains the same instance from the start to the end of a single touch. This means you can track and distinguish multiple touches by comparing these Objects. Enum.KeyCode KeyCode: Key input Enum.UserInputState UserInputState: Input state Enum.UserInputType UserInputType: Input device type Vector3 Delta: Movement delta (Z-axis is always 0) Vector3 Position: Input position on screen (Z-axis is always 0)

bool bGameProcessed

Indicates whether the input has already been handled by a UI element on the screen. UI elements that can affect input include: System UI such as the chat window or menu buttons Buttons bound through ContextActionService GUI buttons within ScreenGui or SurfaceGui that have Active set to true

Code Samples

local UserInputService = game:GetService("UserInputService")

local function OnScreenTouchMove(input, _gameProcessed)
    local keyCode = input.KeyCode        
    local inputState = input.UserInputState 
    local inputType = input.UserInputType   
    local delta = input.Delta
    local pos = input.Position 
end
UserInputService.TouchMoved:Connect(OnScreenTouchMove)

TouchEnded

This event is triggered the moment the user lifts their finger off the screen.

It's used to detect when a touch input has ended.

Parameters

InputObject InputObject

This Object contains detailed information about an input, and remains the same instance from the start to the end of a single touch. This means you can track and distinguish multiple touches by comparing these Objects. Enum.KeyCode KeyCode: Key input Enum.UserInputState UserInputState: Input state Enum.UserInputType UserInputType: Input device type Vector3 Delta: Movement delta (Z-axis is always 0) Vector3 Position: Input position on screen (Z-axis is always 0)

bool bGameProcessed

Indicates whether the input has already been handled by a UI element on the screen. UI elements that can affect input include: System UI such as the chat window or menu buttons Buttons bound through ContextActionService GUI buttons within ScreenGui or SurfaceGui that have Active set to true

Code Samples

local UserInputService = game:GetService("UserInputService")

local function OnScreenTouchEnd(input, _gameProcessed)
    local keyCode = input.KeyCode        
    local inputState = input.UserInputState 
    local inputType = input.UserInputType   
    local delta = input.Delta
    local pos = input.Position 
end
UserInputService.TouchEnded:Connect(OnScreenTouchEnd)

InputBegan

This event is triggered when the user initiates an input, such as clicking the screen or pressing a key or mouse button.

When used alongside InputChanged and InputEnded, it allows you to effectively track the entire input interaction from beginning, movement, to end.

However, it's not recommended for use in mobile environments. Instead, it's better suited for testing or simulation purposes in Studio. For mobile, it's recommended to use the TouchStarted, TouchMoved, and TouchEnded events.

Parameters

InputObject InputObject	This Object contains detailed information about an input, and remains the same instance from the start to the end of a single input. Enum.KeyCode KeyCode: Key input Enum.UserInputState UserInputState: Input state Enum.UserInputType UserInputType: Input device type Vector3 Delta: Movement delta (Z-axis is always 0) Vector3 Position: Input position on screen (Z-axis is always 0)
bool bGameProcessed	Indicates whether the input has already been handled by a UI element on the screen. UI elements that can affect input include: System UI such as the chat window or menu buttons Buttons bound through ContextActionService GUI buttons within ScreenGui or SurfaceGui that have Active set to true

Code Samples

local UserInputService = game:GetService("UserInputService")

local function OnScreenTouchStart(input, _gameProcessed)
    local keyCode = input.KeyCode        
    local inputState = input.UserInputState 
    local inputType = input.UserInputType   
    local delta = input.Delta
    local pos = input.Position    
end
UserInputService.InputBegan:Connect(OnScreenTouchStart)

InputChanged

This event is triggered when the user moves the mouse cursor while holding down a click.

It tracks the cursor's position in real-time, making it useful for detecting gesture-based inputs like dragging or swiping.

However, it's not recommended for use in mobile environments. Instead, it's better suited for testing or simulation purposes in Studio. For mobile, it's recommended to use the TouchStarted, TouchMoved, and TouchEnded events.

Parameters

InputObject InputObject	This Object contains detailed information about an input, and remains the same instance from the start to the end of a single input. Enum.KeyCode KeyCode: Key input Enum.UserInputState UserInputState: Input state Enum.UserInputType UserInputType: Input device type Vector3 Delta: Movement delta (Z-axis is always 0) Vector3 Position: Input position on screen (Z-axis is always 0)
bool bGameProcessed	Indicates whether the input has already been handled by a UI element on the screen. UI elements that can affect input include: System UI such as the chat window or menu buttons Buttons bound through ContextActionService GUI buttons within ScreenGui or SurfaceGui that have Active set to true

Code Samples

local UserInputService = game:GetService("UserInputService")

local function OnScreenTouchMove(input, _gameProcessed)
    local keyCode = input.KeyCode        
    local inputState = input.UserInputState 
    local inputType = input.UserInputType   
    local delta = input.Delta
    local pos = input.Position 
end
UserInputService.InputChanged:Connect(OnScreenTouchMove)

InputEnded

This event is triggered when the user ends an input, such as releasing a mouse click or lifting a key.

It's used to detect when an input has ended.

However, it's not recommended for use in mobile environments. Instead, it's better suited for testing or simulation purposes in Studio. For mobile, it's recommended to use the TouchStarted, TouchMoved, and TouchEnded events.

Parameters

InputObject InputObject	This Object contains detailed information about an input, and remains the same instance from the start to the end of a single input. Enum.KeyCode KeyCode: Key input Enum.UserInputState UserInputState: Input state Enum.UserInputType UserInputType: Input device type Vector3 Delta: Movement delta (Z-axis is always 0) Vector3 Position: Input position on screen (Z-axis is always 0)
bool bGameProcessed	Indicates whether the input has already been handled by a UI element on the screen. UI elements that can affect input include: System UI such as the chat window or menu buttons Buttons bound through ContextActionService GUI buttons within ScreenGui or SurfaceGui that have Active set to true

Code Samples

local UserInputService = game:GetService("UserInputService")

local function OnScreenTouchEnd(input, _gameProcessed)
    local keyCode = input.KeyCode        
    local inputState = input.UserInputState 
    local inputType = input.UserInputType   
    local delta = input.Delta
    local pos = input.Position 
end
UserInputService.InputEnded:Connect(OnScreenTouchEnd)

See also

Mobile Input Handling