godot-input-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Godot Input Patterns

Godot 输入模式

Purpose

用途

Implement Godot input through InputMap actions with correct event propagation, device support, and rebinding.

通过InputMap动作实现Godot输入，确保正确的事件传播、设备支持与按键重绑定。

Use When

适用场景

adding or unifying input handling for a Godot game
gameplay scripts read raw keycodes, scancodes, or joypad button indices directly
input behaves differently between gameplay, UI, and pause states and the propagation order is unclear

为Godot游戏添加或统一输入处理逻辑
游戏玩法脚本直接读取原始键码、扫描码或手柄按钮索引
输入在游戏玩法、UI与暂停状态下表现不一致，且事件传播顺序不明确

Inputs

输入项

list of gameplay actions (move, jump, fire, pause, confirm)
supported devices (keyboard/mouse, joypad, touch) per platform target
UI flow and pause/overlay states that consume input
rebinding and accessibility requirements

游戏玩法动作列表（移动、跳跃、射击、暂停、确认）
各目标平台支持的设备（键盘/鼠标、手柄、触控）
会消耗输入的UI流程与暂停/覆盖状态
按键重绑定与无障碍需求

Process

流程

define every action in the InputMap (project settings or at startup) and bind devices to actions; gameplay code calls
```
Input.is_action_*
```
or handles
```
InputEvent
```
actions, never raw keycodes
choose polling versus events deliberately: poll continuous state (movement axes via
```
Input.get_vector
```
) in
```
_physics_process
```
, and handle discrete edges (just pressed/released) through events or
```
is_action_just_pressed
```
respect the propagation order —
```
_input
```
, then Control
```
_gui_input
```
, then
```
_unhandled_input
```
— and put gameplay input in
```
_unhandled_input
```
so UI consumes events first; call
```
set_input_as_handled()
```
explicitly when a layer swallows an event
handle joypads through actions with deadzone configured per action, listen to
```
joy_connection_changed
```
for hot-plug, and verify mappings on each exported platform
for touch targets, decide between
```
InputEventScreenTouch
```
handling and
```
emulate_mouse_from_touch
```
, and keep on-screen controls as a separate Control layer bound to the same actions
implement rebinding by editing InputMap at runtime (
```
action_erase_events
```
/
```
action_add_event
```
), persist bindings to user settings, and expose them through the accessibility options
define how paused state affects input: which nodes keep processing via
```
process_mode
```
, and which actions (pause/menu) must work while the tree is paused

在InputMap中定义所有动作（通过项目设置或启动时配置），并为动作绑定设备；游戏玩法代码调用
```
Input.is_action_*
```
或处理
```
InputEvent
```
动作，绝不直接使用原始键码
谨慎选择轮询与事件两种方式：在
```
_physics_process
```
中轮询持续状态（通过
```
Input.get_vector
```
获取移动轴），通过事件或
```
is_action_just_pressed
```
处理离散触发（刚按下/释放）
遵循事件传播顺序——
```
_input
```
→ Control的
```
_gui_input
```
→
```
_unhandled_input
```
——将游戏玩法输入放在
```
_unhandled_input
```
中，确保UI优先消耗事件；当某个层级需要拦截事件时，显式调用
```
set_input_as_handled()
```
通过配置了死区的动作处理手柄输入，监听
```
joy_connection_changed
```
事件处理热插拔，并在每个导出平台上验证映射
对于触控目标，在
```
InputEventScreenTouch
```
处理与
```
emulate_mouse_from_touch
```
之间做出选择，并将屏幕控件作为独立的Control层绑定到相同动作
通过运行时编辑InputMap实现按键重绑定（使用
```
action_erase_events
```
/
```
action_add_event
```
），将绑定设置持久化到用户配置中，并通过无障碍选项暴露给玩家
定义暂停状态对输入的影响：哪些节点通过
```
process_mode
```
保持处理，哪些动作（暂停/菜单）必须在树体暂停时仍能生效

Outputs

输出项

InputMap action inventory with device bindings and deadzones
propagation rules: which layer handles what, in which callback
rebinding and persistence design
device and platform test scenarios (hot-plug, focus loss, touch emulation)

包含设备绑定与死区设置的InputMap动作清单
传播规则：哪些层级处理哪些输入，使用哪个回调函数
按键重绑定与持久化设计方案
设备与平台测试场景（热插拔、焦点丢失、触控模拟）

Quality Bar

质量标准

no gameplay script references keycodes, scancodes, or joypad indices outside the InputMap setup
UI reliably consumes events before gameplay, and nothing double-handles an event after
```
set_input_as_handled()
```
movement uses
```
Input.get_vector
```
(or equivalent) with per-action deadzones, not per-frame keycode checks
pause/menu actions keep working while the tree is paused, and nothing else does
rebinds survive a restart and are reflected in any input prompts shown to the player

游戏玩法脚本除InputMap配置外，不得引用键码、扫描码或手柄索引
UI能可靠地优先于游戏玩法消耗事件，调用
```
set_input_as_handled()
```
后不会有重复处理事件的情况
移动操作使用带动作级死区的
```
Input.get_vector
```
（或等效方法），而非逐帧检查键码
暂停/菜单动作在树体暂停时仍能生效，其他动作则不能
按键重绑定设置在重启后仍保留，并能反映在向玩家展示的所有输入提示中

Common Failure Modes

常见失败模式

mixing
```
_input
```
and
```
_process
```
polling for the same action, double-counting presses across frames
gameplay input in
```
_input
```
so UI clicks also fire gameplay actions underneath
hardcoded joypad button indices that differ between controller types and platforms
pause menus that cannot be closed because their own input stopped processing with the tree
touch handled through mouse emulation only, breaking multi-touch (move plus fire) on mobile

对同一动作同时使用
```
_input
```
与
```
_process
```
轮询，导致跨帧重复计数按键按下事件
将游戏玩法输入放在
```
_input
```
中，导致UI点击同时触发下层的游戏玩法动作
硬编码手柄按钮索引，导致在不同控制器类型与平台上表现不一致
暂停菜单因树体暂停而停止处理输入，无法关闭
仅通过鼠标模拟处理触控，破坏移动端的多点触控（如移动+射击）功能

Related Agents

关联Agent

godot-reviewer
gameplay-programmer
ui-programmer

godot-reviewer
gameplay-programmer
ui-programmer

Related Commands

关联命令

input-review
godot-review
verify

input-review
godot-review
verify

Related Skills

关联技能

godot-signals-patterns
godot-scene-architecture

godot-signals-patterns
godot-scene-architecture

Notes

注意事项

Keep this skill aligned with the relevant rules layer and current project documentation.
The engine-neutral action-abstraction policy lives in
```
engineering-common/input-abstraction
```
; this skill is the Godot-specific implementation of it.

保持本技能与相关规则层及当前项目文档一致
引擎无关的动作抽象策略位于
```
engineering-common/input-abstraction
```
；本技能是该策略在Godot中的具体实现