roblox-input

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Load

加载时机

Load when handling keyboard, mouse, gamepad, touch, accelerometer, or gyroscope input; binding actions across platforms; or detecting what input devices the player has. Client-only — both services require

LocalScript

or client

RunContext

当处理键盘、鼠标、游戏手柄、触摸、加速度计或陀螺仪输入；跨平台绑定操作；或检测玩家拥有的输入设备时加载。仅适用于客户端——这两个服务都需要

LocalScript

或客户端

RunContext

。

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.

Platform detection (cache at startup):

KeyboardEnabled

MouseEnabled

TouchEnabled

GamepadEnabled

AccelerometerEnabled

GyroscopeEnabled

VREnabled

PreferredInput

(the device the player is currently using most).

Polling queries (cheaper than events for held-state):

luau

UIS:IsKeyDown(Enum.KeyCode.W)
UIS:IsMouseButtonPressed(Enum.UserInputType.MouseButton1)
UIS:IsGamepadButtonDown(Enum.UserInputType.Gamepad1, Enum.KeyCode.ButtonA)
local dx, dy = UIS:GetMouseDelta()

Prefer
ContextActionService
over
InputBegan
for gameplay — free conflict resolution (chat won't steal H) and free mobile buttons:

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.

Touch buttons:

createTouchButton=true

auto-creates an

ImageButton

under

PlayerGui.ContextActionGui.ContextButtonFrame

(max 7). Customize via

CAS:GetButton(name)

→

SetTitle

SetImage

SetPosition

SetDescription

Gamepad:

GetConnectedGamepads()

→

Gamepad1

Gamepad8

. Listen to

GamepadConnected

Disconnected

Touch gestures:

TouchTap

TouchTapInWorld

(world pos),

TouchPan

TouchPinch

TouchRotate

TouchSwipe

TouchLongPress

TouchDrag

. Raw:

TouchStarted

TouchMoved

TouchEnded

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.
```
JumpRequest
```
fires multiple times per jump — debounce.
Mouse wheel only fires
```
InputChanged
```
.

See

references/full.md

for full event tables,

ContextActionResult

, mobile buttons, sensors.

核心事件（

UserInputService

）：

InputBegan

、

InputChanged

、

InputEnded

会以

(input: InputObject, gameProcessedEvent: boolean)

的形式触发。

InputBegan

不会对鼠标滚轮触发。仅当客户端窗口处于焦点状态时，事件才会触发。

平台检测（启动时缓存）：

KeyboardEnabled

、

MouseEnabled

、

TouchEnabled

、

GamepadEnabled

、

AccelerometerEnabled

、

GyroscopeEnabled

、

VREnabled

、

PreferredInput

（玩家当前最常使用的设备）。

轮询查询（对于持续按下状态，比事件更高效）：

luau

UIS:IsKeyDown(Enum.KeyCode.W)
UIS:IsMouseButtonPressed(Enum.UserInputType.MouseButton1)
UIS:IsGamepadButtonDown(Enum.UserInputType.Gamepad1, Enum.KeyCode.ButtonA)
local dx, dy = UIS:GetMouseDelta()

对于游戏玩法，优先使用
ContextActionService
而非
InputBegan
——免费提供冲突解决（聊天不会占用H键）和免费移动按钮：

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)

。处理器返回

ContextActionResult.Sink

表示消费该输入，

.Pass

表示让输入继续传递。

触摸按钮：

createTouchButton=true

会在

PlayerGui.ContextActionGui.ContextButtonFrame

下自动创建一个

ImageButton

（最多7个）。可通过

CAS:GetButton(name)

调用

SetTitle

SetImage

SetPosition

SetDescription

进行自定义。

游戏手柄：

GetConnectedGamepads()

Gamepad1

Gamepad8

。监听

GamepadConnected

Disconnected

事件。

触摸手势：

TouchTap

、

TouchTapInWorld

（世界坐标）、

TouchPan

、

TouchPinch

、

TouchRotate

、

TouchSwipe

、

TouchLongPress

、

TouchDrag

。原始事件：

TouchStarted

TouchMoved

TouchEnded

。

注意事项：

```
InputBegan
```
中的
```
gameProcessedEvent=true
```
表示UI已消费该输入。游戏玩法中需过滤此类情况。
```
BindAction
```
基于栈结构：最近绑定的获胜。使用
```
BindActionAtPriority
```
来设置优先级。
仅适用于客户端。服务器脚本会静默无操作。
```
JumpRequest
```
每次跳跃会触发多次——需要防抖处理。
鼠标滚轮仅触发
```
InputChanged
```
事件。

完整事件表、

ContextActionResult

、移动按钮、传感器相关内容请查看

references/full.md

。