SuperAPI AI 工具集

bevy-input-handling

编程与开发

查看项目

更新于 10-16 10:37

技能介绍

用途

本技能用于在 Bevy 0.20 中处理玩家输入。当某个系统需要读取键盘、鼠标或手柄状态时加载它。技能中的名称均以 Bevy 0.20 的 bevy::input 模块为准。

主要能力

  • 插件与调度:InputPlugin 提供键盘、鼠标、手柄和触摸输入,通常包含在常规 app 插件中;InputSystems 标记刷新这些数据的系统。输入资源应在 Update(或已链接的调度)中的系统里读取。
  • 键盘:Res<ButtonInput<KeyCode>> 表示物理按键(布局稳定),Res<ButtonInput<Key>> 表示逻辑按键。示例使用 pressed、just_pressed、just_released。
  • 鼠标:mouse_button_input_system 从 MouseButtonInput 写入 ButtonInput<MouseButton>;AccumulatedMouseMotion 与 AccumulatedMouseScroll 是每帧重置的资源;MouseMotion 与 MouseWheel 是底层事件。
  • 手柄:Gamepad 保存已连接手柄的元数据(GamepadButton、GamepadAxis);连接与轴变化以 GamepadConnectionEvent、GamepadAxisChangedEvent、GamepadButtonChangedEvent 到达;GamepadRumbleRequest 是力反馈事件。
  • 从 Godot 迁移:提供对照表,例如“动作刚按下”对应 ButtonInput::just_pressed,“动作按住”对应 ButtonInput::pressed,物理 WASD 与符号键分别用 KeyCode 和 Key,鼠标视角增量用 AccumulatedMouseMotion,手柄用 Gamepad 及相关事件。

使用方式

依赖声明为 bevy = "0.20"。在 Update 中读取边沿,因为 FixedUpdate 每帧可能运行零次或多次,在那里采样按键可能被丢弃或重复;应把边沿存到意图组件上,让固定步长消费。

示例包括:

  • 读取键盘方向与跳跃,写入 MoveIntent 组件。
  • 用 AccumulatedMouseMotion 旋转相机。
  • 手柄摇杆的径向死区:丢弃漂移后重新缩放剩余范围,使满偏仍达到长度 1。
  • 跳跃缓冲:保留提前几帧落地的按键。
  • 追踪最后活跃设备(键盘或手柄)。
  • 通过 InputHandlingPlugin 注册资源与系统,并用 .chain() 排序。

适用场景

适用于需要在 Bevy ECS 中读取键盘、鼠标、手柄输入的游戏系统,例如角色移动、相机视角、跳跃缓冲、设备切换等。技能还说明状态归属:单个实体的数据用 Component,全应用的值用 Resource,生成用 Commands,不可竞争的顺序用 .chain(),插件边界用 Plugin。

限制

  • 目标为 Bevy 0.20+。
  • 不要在文档 URL 中固定 /0.20.0/。
  • 不要从两个无序系统可变查询同一组件;调度默认并行运行系统,除非用 .chain() 排序。
  • 不要在本技能中发明物理、导航、网络或 XR crate。
  • 不使用 Godot 输入映射、事件或设备类型。
  • 不使用本文件未打开的 API(仅引用 pressed、just_pressed、just_released 等按钮方法)。
  • 不使用第三方输入 crate。
  • 命名动作、跳跃缓冲、径向摇杆死区和最后活跃设备是需要自行定义的资源;字形美术属于 UI 关注点。
  • 消息与观察者属于所有权槽位,其 API 见 bevy-events-messaging。