Skip to Content
Kinemium
Services

UserInputService

Read keyboard, mouse, touch, and focus state, and listen for raw input events.

UserInputService gives you access to raw device input. It's where you check whether a key is held, where the pointer is, and what kind of input the player used last. For input targeted at a specific GUI element, use the events on GuiObject instead.

Getting started

local UserInputService = game:GetService("UserInputService")

UserInputService.InputBegan:Connect(function(input, gameProcessedEvent)
    if gameProcessedEvent then
        return
    end

    if input.KeyCode == Enum.KeyCode.E then
        print("Interact")
    end
end)

gameProcessedEvent is true when the input was already consumed, by the GUI or by another input handler. Checking it first is what keeps a keyboard shortcut from firing while a text box has focus.

Properties

PropertyTypeAccessDefaultDescription
KeyboardEnabledbooleanRead-onlytrueWhether a keyboard is considered available.
MouseEnabledbooleanRead-onlytrueWhether a mouse is considered available.
TouchEnabledbooleanRead-onlytrue on Android and webWhether touch input is available. TouchScreenEnabled is an alias.
GamepadEnabledbooleanRead-onlyfalseWhether a gamepad is considered connected. Stays false in this build.
AccelerometerEnabledbooleanRead-onlyfalseWhether an accelerometer is available.
GyroscopeEnabledbooleanRead-onlyfalseCurrently always false.
VREnabledbooleanRead-onlyfalseCurrently always false.
OnScreenKeyboardVisiblebooleanRead-onlyfalseCurrently always false.
MouseIconEnabledbooleanRead/writetrueWhether the system cursor is shown.
MouseDeltaSensitivitynumberRead/write1Multiplier for mouse movement deltas, clamped between 0 and 10.
MouseBehaviorEnum.MouseBehaviorRead/writeEnum.MouseBehavior.DefaultMouse capture mode. Setting anything other than Default enables relative mouse mode.
InputBegansignalRead-onlyN/AFires when an input starts.
InputChangedsignalRead-onlyN/AFires when an input changes, such as pointer movement or a wheel scroll.
InputEndedsignalRead-onlyN/AFires when an input ends.

The availability properties describe the device, not your permission to read it. GamepadEnabled stays false because gamepad detection isn't implemented, and the three "always false" properties are placeholders.

MouseBehavior is the standard way to lock the pointer for first-person controls. Set it back to Default to release the pointer:

UserInputService.MouseBehavior = Enum.MouseBehavior.LockCenter
-- Later:
UserInputService.MouseBehavior = Enum.MouseBehavior.Default

Methods

SignatureDescription
IsKeyDown(keyCode: Enum.KeyCode): booleanWhether the key is currently held.
IsMouseButtonPressed(button: Enum.UserInputType): booleanWhether a mouse button is held. Other input types return false.
GetLastInputType(): Enum.UserInputTypeThe device type that produced the most recent input.
GetKeysPressed(): {InputObject}One input object per key currently down.
GetMouseButtonsPressed(): {InputObject}One input object per mouse button currently down.
GetMouseLocation(): Vector2Pointer position in screen space.
GetMouseDelta(): Vector2Accumulated pointer movement for the current frame.
GetTouches(): {InputObject}One input object per active touch.
GetFocusedTextBox(): TextBox?The text box with focus, or nil.
GetImageForKeyCode(keyCode: Enum.KeyCode): stringCurrently always an empty string; this runtime ships no key images.
GetPlatform(): Enum.PlatformThe platform the game is running on.

GetPlatform() is callable even though it isn't listed in the class's method metadata. Its value comes from the build target, not from runtime detection.

GetMouse() also exists, but it requires internal studio access and can raise an insufficient-capabilities error from a normal script. Use GetMouseLocation() and GetMouseDelta() for pointer data instead.

Polling held keys

local UserInputService = game:GetService("UserInputService")
local RunService = game:GetService("RunService")

RunService.Heartbeat:Connect(function(deltaTime)
    local direction = Vector3.new(0, 0, 0)

    if UserInputService:IsKeyDown(Enum.KeyCode.W) then
        direction += Vector3.new(0, 0, -1)
    end
    if UserInputService:IsKeyDown(Enum.KeyCode.S) then
        direction += Vector3.new(0, 0, 1)
    end

    -- Apply direction somewhere.
end)

Polling is the right approach for held keys; the events tell you when a key goes down or up, but not that it's still held on a later frame.

Events

All three input events pass (input: InputObject, gameProcessedEvent: boolean).

EventWhen it fires
InputBeganA key goes down, a mouse button is pressed, or a touch starts.
InputChangedThe pointer moves, a wheel scrolls, or an active touch moves.
InputEndedA key is released, a mouse button is released, or a touch ends.

InputObject carries UserInputType, UserInputState, KeyCode, Position, and Delta. The objects are temporary: read the fields you need inside the callback instead of storing the object.

UserInputService.InputChanged:Connect(function(input, gameProcessedEvent)
    if input.UserInputType == Enum.UserInputType.MouseWheel then
        print("Scrolled", input.Position.Z)
    end
end)

Keyboard and mouse input arrives on desktop builds, touch on Android and web. On a platform without a device, the matching events simply don't fire.

Notes

  • Key repeat is filtered out for keyboard input, so holding a key fires InputBegan once.
  • The engine creates fresh input objects for each event and destroys them afterward.
  • Input that belongs to a GUI element is delivered there as well; gameProcessedEvent tells you whether it was consumed.

See also

  • GuiObject, input events scoped to a GUI element.
  • RunService, per-frame polling for held keys.
  • ContextActionService, binding actions instead of individual keys.

On this page