godot-input-handling

输入处理

妥善处理键盘、鼠标、游戏手柄和触控输入，并提供适当的缓冲和无障碍支持。

必须按场景加载的脚本

场景	编码前加载
跳跃／冲刺／土狼时间手感	input_buffer.gd（与物理帧同步衰减）+ advanced_input_buffer.gd，用于多动作优先级处理
设置重映射界面	safe_runtime_rebind.gd（使用 ConfigFile 持久化到 user://）
模拟摇杆移动	analog_deadzone_manager.gd——未经径向死区处理时，绝不可直接使用原始轴值
“按 X／按 E”提示	glyph_prompt_manager.gd
UI 导航与游戏内确认	input_echo_filter.gd——回显事件用于移动菜单，不用于确认／返回
游戏内点击与菜单点击	unhandled_input_priority.gd

按场景禁止加载的脚本

场景	加载	不要加载
设置重映射界面	safe_runtime_rebind.gd	multi_touch_gestures.gd、mouse_capture_manager.gd、连招／回放注入器
移动端／触控手势	multi_touch_gestures.gd	mouse_capture_manager.gd、桌面端重映射持久化脚本
仅用于跳跃／冲刺的缓冲	input_buffer.gd / advanced_input_buffer.gd	重映射器、多点触控、回放、连招验证器
FPS 鼠标视角	mouse_capture_manager.gd + 按需使用死区／按键图标	multi_touch_gestures.gd、连招／回放
连招／格斗序列	combo_validator.gd + 缓冲脚本	触控手势、鼠标捕获
回放／虚拟注入测试	input_replay_buffer.gd / virtual_input_injector.gd	重映射界面、多点触控

可用脚本

advanced_input_buffer.gd

帧级精准的输入缓冲系统，让跳跃、冲刺和连招衔接更加灵敏。

input_buffer.gd

定时动作缓冲，使用 _physics_process 衰减，使缓冲窗口与 CharacterBody 的消耗时机一致，而非受渲染帧率影响。

safe_runtime_rebind.gd

动态输入重映射，支持冲突检测，并持久化至 user://input_rebinds.cfg。

analog_deadzone_manager.gd

管理模拟摇杆的径向死区，在消除漂移的同时保留自然的跟手感。

multi_touch_gestures.gd

处理触控、拖动和双指缩放手势，兼容移动设备和触摸屏。

input_echo_filter.gd

过滤回显事件，区分按住导航（UI）和一次性游戏操作。

mouse_capture_manager.gd

为 FPS 和鼠标密集型系统提供可靠的鼠标捕获与灵敏度缩放逻辑。

hold_toggle_accessibility.gd

在软件层面支持用户自定义“按住”与“切换”无障碍偏好设置。

glyph_prompt_manager.gd

根据最后使用的设备，实时切换键盘和游戏手柄的 UI 按键提示。

action_state_machine.gd

跟踪动作的生命周期（“刚按下”“按住”“已释放”），用于复杂状态逻辑。

unhandled_input_priority.gd

演示正确使用 _unhandled_input，避免游戏逻辑影响 UI。

virtual_input_injector.gd

通过 Input.parse_input_event 注入输入，用于 CI 教程／AI 辅助——不适用于物理硬件。

combo_validator.gd

用于特殊招式验证（格斗／动作 RPG）的定时滚动序列缓冲。

input_replay_buffer.gd

带帧标签的输入捕获，以及通过 parse_input_event 实现的确定性回放。

输入处理中的禁忌

• 绝对不要在 _process() 中轮询游戏操作输入——请使用 _physics_process() 或 _unhandled_input()。_process() 依赖帧率，低 FPS 时会导致输入丢失 [22]。
• 绝对不要检查硬编码的按键（例如 KEY_W）——始终使用 InputMap 操作。硬编码按键会阻止重新绑定，并导致与非 QWERTY 键盘布局不兼容 [23]。
• 绝对不要忽略摇杆的模拟死区——幅度为 0.05 的摇杆漂移会导致意外移动。请在代码或设置中实现径向死区（而非轴向死区）[24]。
• 绝对不要假设只有一种输入设备——玩家可能在会话中途切换键盘和手柄。使用 Input.joy_connection_changed 动态更新 UI 提示 [25]。
• 绝对不要使用 _input() 处理游戏操作——_input() 会对所有事件触发（包括 UI 事件）。请使用 _unhandled_input()，这样点击菜单时就不会触发游戏逻辑 [26]。
• 快节奏游戏中绝对不要省略输入缓冲——如果玩家在落地前 50 ms 按下跳跃键，没有缓冲就会丢失该输入。请实现 100-150 ms 的缓冲，营造「紧凑」的手感 [27]。
• 绝对不要使用 Input.is_action_pressed() 触发一次性操作——按住按键时，它会在每一帧都返回 true。跳跃、攻击和切换操作请使用 _just_pressed，避免逻辑重复触发。
• 绝对不要在多个位置手动实现「按住或切换」逻辑——请将其集中在设置或输入封装中，确保整个游戏的无障碍体验保持一致。
• 绝对不要忘记在 UI 导航中处理 InputEvent.is_echo()——回显事件（键盘重复输入）应当用于移动菜单，但通常不应触发「确认」或「返回」操作。
• 绝对不要在没有「释放」快捷键的情况下捕获鼠标——如果游戏崩溃或阻断了 ui_cancel，用户就会被困住。请始终为鼠标捕获提供备用的退出方式。

---

输入传播与隔离

Godot 会按特定顺序传播输入事件。理解这一点是隔离 UI 与游戏操作的关键。

1. _input(event)：高优先级全局拦截。用于开发者控制台或调试覆盖层。
2. _gui_input(event)：由 Control 节点（UI） 处理。如果 UI 元素消耗了事件（例如点击按钮），就会调用 accept_event()，停止进一步传播。
3. _unhandled_input(event)：只有在没有 UI 元素消耗事件时才会触发。专家模式：将所有游戏逻辑（跳跃、射击）放在这里，避免与菜单交互时意外触发。

InputMap 最佳实践

避免检查物理按键。在 Project Settings > Input Map 中定义语义操作（例如 move_left、interact）。

1. 模拟死区

模拟摇杆可能发生漂移。必须使用：analog_deadzone_manager.gd。圆形死区请优先使用 Input.get_vector()——绝不要将各轴相减，形成方形死区。

2. 专家级轮询增量（无硬编码按键）

游戏操作应在 _physics_process / _unhandled_input 中采样操作——绝不要使用 KEY_* / MOUSE_BUTTON_* 分支。暂停/取消必须使用 InputMap 操作（例如 ui_cancel），以支持重新绑定和非 QWERTY 键盘布局。参见 unhandled_input_priority.gd。

多模态输入与 UI 图标

现代游戏必须流畅地处理手柄与键盘/鼠标的同步输入。

1. 处理输入模式

• 鼠标瞄准：在 _unhandled_input() 中处理 InputEventMouseMotion，实现相对移动（参见 mouse_capture_manager.gd）。
• 摇杆移动：在 _physics_process() 中轮询向量，随后应用 analog_deadzone_manager.gd。

2. 动态切换图标

必须使用：glyph_prompt_manager.gd 动态切换为最近使用设备的提示。不要在每个 HUD 控件中自行编写 event is InputEventJoypadButton 检测逻辑。

专家输入扩展（脚本为唯一来源）

• 输入缓冲 — 强制要求：input_buffer.gd + advanced_input_buffer.gd。不要在文中粘贴跳跃计时器教程。
• 土狼时间 — 由移动技能负责：godot-characterbody-2d（frame_perfect_coyote_time.gd）和 godot-genre-platformer。与本技能中的缓冲配合使用；不要在此处重新实现土狼时间。
• 多人游戏输入同步 — 不要在此处 RPC sync_input。 使用 godot-multiplayer-networking 处理权威操作快照和 get_remote_sender_id 验证。
• 虚拟输入注入 — 强制要求：virtual_input_injector.gd（Input.parse_input_event）。
• 连招序列 — 强制要求：combo_validator.gd；格斗题材内容归 godot-genre-fighting 负责。
• 确定性回放 — 强制要求：input_replay_buffer.gd。

深入指南（按需查阅）

主题	参考资料 / 脚本
缓冲 / 土狼时间 / 多人游戏同步	input-event-processing.md
虚拟输入注入 / 连招 / 回放	expert-input-extensions.md
InputMap 和设备 ID	inputmap-best-practices.md

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接；路由到相关领域时再加载相关技能，不要预先加载整个技能网络。

官方文档

• 使用 InputEvent — 事件传播顺序（_input → GUI → _unhandled_input），以及为什么应在 UI 处理完事件后再处理游戏逻辑。
• 输入示例 — 本技能基于的实用 InputMap 动作轮询、鼠标按键和键盘模式。
• 控制器、游戏手柄和操纵杆 — Joypad 连接、按键/轴事件，以及用于按键重映射和图标切换的多设备映射。
• 控制器振动和功能 — 发布主机风格反馈时可用的基础按键之外的扩展手柄功能。
• 鼠标和输入坐标 — 用于点击、瞄准和相对捕获移动的视口坐标与屏幕坐标。
• 自定义鼠标光标 — 与 Input.mouse_mode 捕获/释放流程配合使用的光标形状。
• 处理退出请求 — 安全处理 ESC / 返回 / 退出路径，避免鼠标捕获导致玩家无法脱身。
• Input — 单例 API：is_action_*、get_vector、mouse_mode、parse_input_event 和 Joy 连接信号。
• InputMap — 用于安全重新绑定的运行时 action_add_event / 擦除 / 冲突检查。
• InputEvent — 基础事件 API，包括 is_echo()、is_action_pressed() 和设备 ID。
• 空闲处理和物理处理 — 为什么应在 _physics_process 中处理按住/轮询的游戏输入，而不是在与帧同步的 _process 中处理。
• Control — 使用 _gui_input / accept_event，让菜单在 _unhandled_input 处理游戏逻辑前拦截事件。

相关技能

前置条件

• godot-project-foundations — 项目设置中的 Input Map、场景启动和 Autoload 注册，供按键重映射器和图标管理器使用。
• godot-gdscript-mastery — 缓冲区和设备路由器中使用的类型化 InputEvent 分支、StringName 动作，以及安全的信号/await 模式。

互补技能

• godot-ui-containers — 控制焦点和 _gui_input 的归属，让菜单在游戏玩法的 _unhandled_input 处理点击之前先拦截点击。
• godot-signal-architecture — device_changed 和重新绑定事件应向上发送信号给 HUD/提示词监听器，而不应硬引用 UI。
• godot-autoload-architecture — 为跨场景切换仍然存续的 InputBuffer / GlyphPrompt / Remapper 服务设置单例归属。
• godot-characterbody-2d — 在物理步骤中使用缓冲跳跃/冲刺输入和 get_vector 移动。
• godot-camera-systems — 鼠标视角灵敏度和捕获模式可与 FPS 摄像机装置配合使用。
• godot-state-machine-advanced — 动作的刚按下 / 按住 / 松开阶段可驱动 FSM 转换，避免频繁轮询。
• godot-save-load-systems — 将 InputMap 重新绑定设置以及按住/切换辅助功能偏好保存到 user:// 配置中。
• godot-adapt-desktop-to-mobile — 虚拟摇杆和触屏摄像机可扩展此技能的多点触控手势模式。

下游 / 使用方

• godot-genre-platformer — 土狼时间和跳跃缓冲是输入缓冲的主要使用场景。
• godot-genre-shooter-fps — 鼠标捕获瞄准、开火刚按下输入和手柄视角控制都依赖此技能的捕获/死区处理栈。
• godot-genre-fighting — 连招序列验证器和逐帧精准缓冲可用于特殊招式检测。
• godot-multiplayer-networking — 权威对等端需要经过净化的动作快照 / RPC 传输的输入，而非原始本地键码。

主技能

• godot-master — 库路由器和镜像模块入口；需要确定哪个领域技能负责跨领域输入问题时，请打开此项。