UserInputService

Show Deprecated
Not Creatable
Service
Not Replicated

Summary

Properties

Events

Properties

AccelerometerEnabled

Read Only
Not Replicated
Read Parallel

Code Samples

Move a Ball using the Accelerometer

local Workspace = game:GetService("Workspace")
local UserInputService = game:GetService("UserInputService")
local ball = script.Parent:WaitForChild("Ball")
local mass = ball:GetMass()
local gravityForce = ball:WaitForChild("GravityForce")
local function moveBall(gravity)
gravityForce.Force = gravity.Position * Workspace.Gravity * mass
end
if UserInputService.AccelerometerEnabled then
UserInputService.DeviceGravityChanged:Connect(moveBall)
end

GamepadEnabled

Read Only
Not Replicated
Read Parallel

GyroscopeEnabled

Read Only
Not Replicated
Read Parallel

KeyboardEnabled

Read Only
Not Replicated
Read Parallel

MouseBehavior

Read Parallel

MouseDeltaSensitivity

Not Replicated
Read Parallel

MouseEnabled

Read Only
Not Replicated
Read Parallel

MouseIcon

ContentId
Read Parallel

Code Samples

Custom Mouse Icon

local UserInputService = game:GetService("UserInputService")
-- In order to restore the cursor to what it was set to previously, it will need to be saved to a variable
local savedCursor = nil
local function setTemporaryCursor(cursor: string)
-- Only update the saved cursor if it's not currently saved
if not savedCursor then
savedCursor = UserInputService.MouseIcon
end
UserInputService.MouseIcon = cursor
end
local function clearTemporaryCursor()
-- Only restore the mouse cursor if there's a saved cursor to restore
if savedCursor then
UserInputService.MouseIcon = savedCursor
-- Don't restore the same cursor twice (might overwrite another script)
savedCursor = nil
end
end
setTemporaryCursor("http://www.roblox.com/asset?id=163023520")
print(UserInputService.MouseIcon)
clearTemporaryCursor()

MouseIconEnabled

Read Parallel

OnScreenKeyboardPosition

Read Only
Not Replicated
Read Parallel

OnScreenKeyboardSize

Read Only
Not Replicated
Read Parallel

OnScreenKeyboardVisible

Read Only
Not Replicated
Read Parallel

PreferredInput

Read Only
Not Replicated
Read Parallel

Code Samples

Preferred Input Detection

local UserInputService = game:GetService("UserInputService")
local function preferredInputChanged()
local preferredInput = UserInputService.PreferredInput
if preferredInput == Enum.PreferredInput.Touch then
-- Player is on touch-enabled device with no other input types available/connected
print("Touch")
elseif preferredInput == Enum.PreferredInput.Gamepad then
-- Player has connected or most recently interacted with a gamepad
print("Gamepad")
elseif preferredInput == Enum.PreferredInput.KeyboardAndMouse then
-- Player has connected or most recently interacted with a keyboard or mouse
print("KeyboardAndMouse")
end
end
preferredInputChanged()
UserInputService:GetPropertyChangedSignal("PreferredInput"):Connect(function()
preferredInputChanged()
end)

TouchEnabled

Read Only
Not Replicated
Read Parallel

VREnabled

Read Only
Not Replicated
Read Parallel

Methods

GamepadSupports

Parameters

gamepadNum: Enum.UserInputType
Default Value: ""
gamepadKeyCode: Enum.KeyCode
Default Value: ""

Returns

GetConnectedGamepads


Returns

GetDeviceAcceleration


Returns

Code Samples

Output Device Acceleration

local UserInputService = game:GetService("UserInputService")
if UserInputService.AccelerometerEnabled then
local acceleration = UserInputService:GetDeviceAcceleration().Position
print(acceleration)
else
warn("Cannot get device acceleration because device does not have an enabled accelerometer!")
end

GetDeviceGravity


Returns

Code Samples

Moving Objects with the Gyroscope

local UserInputService = game:GetService("UserInputService")
local bubble = script.Parent:WaitForChild("Bubble")
local camera = workspace.CurrentCamera
camera.CameraType = Enum.CameraType.Scriptable
camera.CFrame = CFrame.new(0, 20, 0) * CFrame.Angles(-math.pi / 2, 0, 0)
if UserInputService.GyroscopeEnabled then
-- Bind event to when gyroscope detects change
UserInputService.DeviceGravityChanged:Connect(function(accel)
-- Move the bubble in the world based on the gyroscope data
bubble.Position = Vector3.new(-8 * accel.Position.X, 1.8, -8 * accel.Position.Z)
end)
end

GetDeviceRotation


Returns

Code Samples

Output Device Rotation

local UserInputService = game:GetService("UserInputService")
if UserInputService.GyroscopeEnabled then
local _, cf = UserInputService:GetDeviceRotation()
print(cf)
else
warn("Cannot get device rotation because device does not have an enabled gyroscope!")
end

GetFocusedTextBox


Returns

GetGamepadConnected

Parameters

gamepadNum: Enum.UserInputType
Default Value: ""

Returns

GetGamepadState

Parameters

gamepadNum: Enum.UserInputType
Default Value: ""

Returns

GetImageForKeyCode

ContentId

Parameters

keyCode: Enum.KeyCode
Default Value: ""

Returns

ContentId

Code Samples

UserInputService - Get Image For KeyCode

local UserInputService = game:GetService("UserInputService")
local imageLabel = script.Parent
local key = Enum.KeyCode.ButtonA
local mappedIconImage = UserInputService:GetImageForKeyCode(key)
imageLabel.Image = mappedIconImage

GetKeysPressed


Returns

GetLastInputType


Returns

Code Samples

Detect Last Input Type

local UserInputService = game:GetService("UserInputService")
if UserInputService:GetLastInputType() == Enum.UserInputType.Keyboard then
print("Most recent input was keyboard!")
end

GetMouseButtonsPressed


Returns

Code Samples

Check Pressed Mouse Buttons

local UserInputService = game:GetService("UserInputService")
UserInputService.InputBegan:Connect(function(input, gameProcessedEvent)
-- Return an array of the pressed mouse buttons
local buttonsPressed = UserInputService:GetMouseButtonsPressed()
local m1, m2 = false, false
for _, button in buttonsPressed do
if button.UserInputType == Enum.UserInputType.MouseButton1 then
print("MouseButton1 pressed!")
m1 = true
end
if button.UserInputType == Enum.UserInputType.MouseButton2 then
print("MouseButton2 pressed!")
m2 = true
end
if m1 and m2 then
print("Both mouse buttons pressed!")
end
end
end)

GetMouseDelta


Returns

Code Samples

Getting Mouse Delta

local RunService = game:GetService("RunService")
local UserInputService = game:GetService("UserInputService")
UserInputService.MouseBehavior = Enum.MouseBehavior.LockCenter
local function onRenderStep()
local delta = UserInputService:GetMouseDelta()
if delta ~= Vector2.new(0, 0) then
print("The mouse has moved", delta, "since the last step")
end
end
RunService:BindToRenderStep("MeasureMouseMovement", Enum.RenderPriority.Input.Value, onRenderStep)

GetMouseLocation


Returns

GetNavigationGamepads


Returns

GetStringForKeyCode

Parameters

keyCode: Enum.KeyCode
Default Value: ""

Returns

GetSupportedGamepadKeyCodes

Parameters

gamepadNum: Enum.UserInputType
Default Value: ""

Returns

IsGamepadButtonDown

Parameters

gamepadNum: Enum.UserInputType
Default Value: ""
gamepadKeyCode: Enum.KeyCode
Default Value: ""

Returns

IsKeyDown

Parameters

keyCode: Enum.KeyCode
Default Value: ""

Returns

IsMouseButtonPressed

Parameters

mouseButton: Enum.UserInputType
Default Value: ""

Returns

IsNavigationGamepad

Parameters

gamepadEnum: Enum.UserInputType
Default Value: ""

Returns

RecenterUserHeadCFrame

()

Returns

()

SetNavigationGamepad

()

Parameters

gamepadEnum: Enum.UserInputType
Default Value: ""
enabled: boolean
Default Value: ""

Returns

()

Events

DeviceAccelerationChanged

Parameters

acceleration: InputObject

Code Samples

Control Players Using the Accelerometer

local UserInputService = game:GetService("UserInputService")
local Players = game:GetService("Players")
local SENSITIVITY = 0.2
local player = Players.LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()
local humanoid = character:WaitForChild("Humanoid")
local ready = true
local function changeAcceleration(acceleration)
if ready then
ready = false
local accel = acceleration.Position
if accel.Y >= SENSITIVITY then
humanoid.Jump = true
end
if accel.Z <= -SENSITIVITY then
humanoid:Move(Vector3.new(-1, 0, 0))
end
if accel.Z >= SENSITIVITY then
humanoid:Move(Vector3.new(1, 0, 0))
end
if accel.X <= -SENSITIVITY then
humanoid:Move(Vector3.new(0, 0, 1))
end
if accel.X >= SENSITIVITY then
humanoid:Move(Vector3.new(0, 0, -1))
end
task.wait(1)
ready = true
end
end
if UserInputService.AccelerometerEnabled then
UserInputService.DeviceAccelerationChanged:Connect(changeAcceleration)
end

DeviceGravityChanged

Parameters

gravity: InputObject

Code Samples

Move a Ball using the Accelerometer

local Workspace = game:GetService("Workspace")
local UserInputService = game:GetService("UserInputService")
local ball = script.Parent:WaitForChild("Ball")
local mass = ball:GetMass()
local gravityForce = ball:WaitForChild("GravityForce")
local function moveBall(gravity)
gravityForce.Force = gravity.Position * Workspace.Gravity * mass
end
if UserInputService.AccelerometerEnabled then
UserInputService.DeviceGravityChanged:Connect(moveBall)
end

DeviceRotationChanged

Parameters

rotation: InputObject
cframe: CFrame

GamepadConnected

Parameters

gamepadNum: Enum.UserInputType

GamepadDisconnected

Parameters

gamepadNum: Enum.UserInputType

InputBegan

Parameters

gameProcessedEvent: boolean

InputChanged

Parameters

gameProcessedEvent: boolean

InputEnded

Parameters

gameProcessedEvent: boolean

JumpRequest


Code Samples

Disable Default Jumping

local UserInputService = game:GetService("UserInputService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()
local humanoid = character:WaitForChild("Humanoid")
humanoid:SetStateEnabled(Enum.HumanoidStateType.Jumping, false)
local processJumpRequest = false
local COOLDOWN_TIME = 0.5
local function jumpRequest()
if processJumpRequest == false then
processJumpRequest = true
-- Process custom jump request
print("Jump requested!")
-- Reset debounce variable after cooldown
task.wait(COOLDOWN_TIME)
processJumpRequest = false
end
end
UserInputService.JumpRequest:Connect(jumpRequest)

LastInputTypeChanged

Parameters

lastInputType: Enum.UserInputType

PointerAction

Parameters

wheel: number
pan: Vector2
pinch: number
gameProcessedEvent: boolean

TextBoxFocusReleased

Parameters

textboxReleased: TextBox

Code Samples

TextBox Modification on Focused and FocusReleased

local UserInputService = game:GetService("UserInputService")
local function textBoxFocused(textBox)
textBox.BackgroundTransparency = 0
end
local function textBoxFocusReleased(textBox)
textBox.BackgroundTransparency = 0.5
end
UserInputService.TextBoxFocused:Connect(textBoxFocused)
UserInputService.TextBoxFocusReleased:Connect(textBoxFocusReleased)

TextBoxFocused

Parameters

textboxFocused: TextBox

Code Samples

TextBox Modification on Focused and FocusReleased

local UserInputService = game:GetService("UserInputService")
local function textBoxFocused(textBox)
textBox.BackgroundTransparency = 0
end
local function textBoxFocusReleased(textBox)
textBox.BackgroundTransparency = 0.5
end
UserInputService.TextBoxFocused:Connect(textBoxFocused)
UserInputService.TextBoxFocusReleased:Connect(textBoxFocusReleased)

TouchDrag

Parameters

dragDirection: Enum.SwipeDirection
numberOfTouches: number
gameProcessedEvent: boolean

TouchEnded

Parameters

gameProcessedEvent: boolean

TouchLongPress

Parameters

touchPositions: Array
gameProcessedEvent: boolean

TouchMoved

Parameters

gameProcessedEvent: boolean

TouchPan

Parameters

touchPositions: Array
totalTranslation: Vector2
velocity: Vector2
gameProcessedEvent: boolean

TouchPinch

Parameters

touchPositions: Array
scale: number
velocity: number
gameProcessedEvent: boolean

TouchRotate

Parameters

touchPositions: Array
rotation: number
velocity: number
gameProcessedEvent: boolean

TouchStarted

Parameters

gameProcessedEvent: boolean

TouchSwipe

Parameters

swipeDirection: Enum.SwipeDirection
numberOfTouches: number
gameProcessedEvent: boolean

TouchTap

Parameters

touchPositions: Array
gameProcessedEvent: boolean

TouchTapInWorld

Parameters

position: Vector2
processedByUI: boolean

WindowFocusReleased


Code Samples

Window Focus Away Script (LocalScript)

local UserInputService = game:GetService("UserInputService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local awayEvent = ReplicatedStorage:WaitForChild("AwayEvent")
local function focusGained()
awayEvent:FireServer(false)
end
local function focusReleased()
awayEvent:FireServer(true)
end
UserInputService.WindowFocused:Connect(focusGained)
UserInputService.WindowFocusReleased:Connect(focusReleased)
Window Focus Away Script (Script)

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local awayEvent = Instance.new("RemoteEvent")
awayEvent.Name = "AwayEvent"
awayEvent.Parent = ReplicatedStorage
local function manageForceField(player, away)
if away then
local forceField = Instance.new("ForceField")
forceField.Parent = player.Character
else
local forceField = player.Character:FindFirstChildOfClass("ForceField")
if forceField then
forceField:Destroy()
end
end
end
awayEvent.OnServerEvent:Connect(manageForceField)

WindowFocused