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

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 input

An object containing detailed information about the input, which remains the same instance from the start to the end of a single input. Enum.KeyCode KeyCode: The key that was pressed Enum.UserInputState UserInputState: The input state Enum.UserInputType UserInputType: The type of input device Vector3 Delta: The movement delta (Z value is fixed at 0) Vector3 Position: The screen position where the input occurred (Z value is fixed at 0)

boolean gameProcessedEvent

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 input

An object containing detailed information about the input, which remains the same instance from the start to the end of a single input. Enum.KeyCode KeyCode: The key that was pressed Enum.UserInputState UserInputState: The input state Enum.UserInputType UserInputType: The type of input device Vector3 Delta: The movement delta (Z value is fixed at 0) Vector3 Position: The screen position where the input occurred (Z value is fixed at 0)

boolean gameProcessedEvent

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 input

An object containing detailed information about the input, which remains the same instance from the start to the end of a single input. Enum.KeyCode KeyCode: The key that was pressed Enum.UserInputState UserInputState: The input state Enum.UserInputType UserInputType: The type of input device Vector3 Delta: The movement delta (Z value is fixed at 0) Vector3 Position: The screen position where the input occurred (Z value is fixed at 0)

boolean gameProcessedEvent

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)

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 touch

An object containing detailed information about the input, which remains the same instance from the start to the end of a single touch input. Therefore, in the case of multi-touch, you can distinguish between inputs by comparing these objects. Enum.KeyCode KeyCode: The key that was pressed Enum.UserInputState UserInputState: The input state Enum.UserInputType UserInputType: The type of input device Vector3 Delta: The movement delta (Z value is fixed at 0) Vector3 Position: The screen position where the input occurred (Z value is fixed at 0)

boolean gameProcessedEvent

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)

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 touch

An object containing detailed information about the input, which remains the same instance from the start to the end of a single touch input. Therefore, in the case of multi-touch, you can distinguish between inputs by comparing these objects. Enum.KeyCode KeyCode: The key that was pressed Enum.UserInputState UserInputState: The input state Enum.UserInputType UserInputType: The type of input device Vector3 Delta: The movement delta (Z value is fixed at 0) Vector3 Position: The screen position where the input occurred (Z value is fixed at 0)

boolean gameProcessedEvent

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)

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 touch

An object containing detailed information about the input, which remains the same instance from the start to the end of a single touch input. Therefore, in the case of multi-touch, you can distinguish between inputs by comparing these objects. Enum.KeyCode KeyCode: The key that was pressed Enum.UserInputState UserInputState: The input state Enum.UserInputType UserInputType: The type of input device Vector3 Delta: The movement delta (Z value is fixed at 0) Vector3 Position: The screen position where the input occurred (Z value is fixed at 0)

boolean gameProcessedEvent

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)

See also

Mobile Input Handling