git:20260727.58fdb8e to git:20260823.ea762f2

---

name: roblox-input

description: "Use when handling Roblox keyboard, mouse, gamepad, touch, motion input, or cross-platform action binding."

sources:

- https://create.roblox.com/docs/reference/engine/classes/UserInputService

- https://create.roblox.com/docs/projects/server-authority

---

# Roblox Input

## When to Load

Load for keyboard, mouse, gamepad, touch, motion, or cross-platform action binding. Client-side only. For simulation-affecting input in a Server Authority project, use the Input Action System rather than traditional input events.

## Quick Reference

**Core events** (`UserInputService`): `InputBegan`, `InputChanged`, `InputEnded` fire as `(input: InputObject, gameProcessedEvent: boolean)`. `InputBegan` does NOT fire for mouse wheel. Events only fire while the client window is focused.

```luau

local CAS = game:GetService("ContextActionService")

local function onAction(name, state, _input)

if name == "Jump" and state == Enum.UserInputState.Begin then

humanoid.Jump = true

end

end

CAS:BindAction("Jump", onAction, true,

Enum.KeyCode.Space, Enum.KeyCode.ButtonA)

```

`BindAction(name, handler, createTouchButton, ...inputTypes)`. Handler returns `ContextActionResult.Sink` to consume, `.Pass` to fall through.

**Server Authority:** use `InputAction`/`InputContext` for inputs that affect the core simulation, store the input state where the synchronized simulation can read it, and process it through `RunService:BindToSimulation()` (requires `Workspace.UseFixedSimulation` enabled in Studio). `ContextActionService` remains appropriate for UI-only or classic-project actions.

**Gamepad UI focus:** separate gameplay bindings from menu selection. Set `GuiService.SelectedObject`, mark controls `Selectable`, and test nested/modal navigation.

**Gamepad:** use `GetConnectedGamepads()` and listen to connection changes.

**Touch:** use high-level gesture events or raw `TouchStarted`/`TouchMoved`/`TouchEnded` when tracking fingers.

**Pitfalls**:

- `gameProcessedEvent=true` in InputBegan → UI consumed it. Filter for gameplay.

- `BindAction` is stack-based: most-recent wins. Use `BindActionAtPriority`.

- Client-only. Server scripts silently no-op.

- Mouse wheel only fires `InputChanged`.

Full event tables and polling methods: `references/full.md`.