InputObject

InputObject : Instance

Overview

This object is created whenever user inputs, such as screen touches, mouse actions, or keyboard presses, occur.

Details of the input, including its type (UserInputType), state (UserInputState), key (KeyCode), and position (Position), can be checked through the object’s properties.

This object is created in the following events:

• UserInputService events: TouchStarted, TouchMoved, TouchEnded

• UserInputService events: InputBegan, InputChanged, InputEnded

• Functions bound via ContextActionService’s BindAction()

• GuiButton events: InputBegan, InputChanged, InputEnded

This object persists as a single instance from the start to the end of an input, with state changes during the input detectable via the Changed event. This enables tracking and managing active inputs in a list, facilitating continuous control and differentiation of individual touch inputs in mobile environments.

InputObject is utilized in conjunction with UserInputService events or GuiObject input handling.

Properties

Delta

Vector3

This property represents the degree of changes in input position and can be used alongside the Position property to track input paths, proving valuable for implementations like camera movement or character control.

For input types lacking positional data, such as keyboard inputs, Delta and Position properties can only be accessed during input start and end events.

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            
    
    print("KeyCode : ", keyCode)
    print("InputState : ", inputState)
    print("InputType : ", inputType)
    print("Delta : ", delta)
    print("Position : ", pos)
end
UserInputService.TouchStarted:Connect(OnScreenTouchStart)

KeyCode

Enum.KeyCode

This value represents the key used for input and can also distinguish between touch and virtual joystick inputs in mobile environments.

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            
    
    print("KeyCode : ", keyCode)
    print("InputState : ", inputState)
    print("InputType : ", inputType)
    print("Delta : ", delta)
    print("Position : ", pos)
end
UserInputService.TouchStarted:Connect(OnScreenTouchStart)

Position

Vector3

This value indicates the input location, with X and Y coordinates representing screen positions for mouse or touch inputs.

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            
    
    print("KeyCode : ", keyCode)
    print("InputState : ", inputState)
    print("InputType : ", inputType)
    print("Delta : ", delta)
    print("Position : ", pos)
end
UserInputService.TouchStarted:Connect(OnScreenTouchStart)

UserInputState

Enum.UserInputState

This value represents the input’s progress (e.g., start, change, end, or cancel), facilitating the tracking of input flow or state-specific processing.

Code Samples

local UserInputService = game:GetService("UserInputService")

local function OnScreenTouchStart(input, _gameProcessed)
    local inputState = input.UserInputState 
    
    print("InputState : ", inputState) -- Begin
end
UserInputService.TouchStarted:Connect(OnScreenTouchStart)

local function OnScreenTouchMove(input, _gameProcessed)
    local inputState = input.UserInputState

    print("InputState : ", inputState) -- Change
end
UserInputService.TouchMoved:Connect(OnScreenTouchMove)

local function OnScreenTouchEnd(input, _gameProcessed)
    local inputState = input.UserInputState

    print("InputState : ", inputState) -- End
end
UserInputService.TouchEnded:Connect(OnScreenTouchEnd)

UserInputType

Enum.UserInputType

This value identifies various input methods (e.g., touch, keyboard, mouse), used independently of KeyCode to distinguish input types.

Code Samples

local UserInputService = game:GetService("UserInputService")

local function OnScreenTouchStart(input, _gameProcessed)
    local inputType = input.UserInputType   

    print("InputType : ", inputType) -- Touch
end
UserInputService.TouchStarted:Connect(OnScreenTouchStart)

Methods

Events

See also

Mobile Input Handling