From 2119838e2719951890d9495a48602481addf60b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kristoffer=20S=C3=B8holm?= Date: Wed, 18 Jun 2025 22:15:03 +0200 Subject: [PATCH] Add support for ButtonInput (#19684) # Objective While `KeyCode` is very often the correct way to interact with keyboard input there are a bunch of cases where it isn't, notably most of the symbols (e.g. plus, minus, different parentheses). Currently the only way to get these is to read from `EventReader`, but then you'd have to redo the `ButtonInput` logic for pressed/released to e.g. make zoom functionality that depends on plus/minus keys. This has led to confusion previously, like https://github.com/bevyengine/bevy/issues/3278 ## Solution Add a `ButtonInput` resource. ## Testing Modified the `keyboard_input` example to test it. ## Open questions I'm not 100% sure this is the right way forward, since it duplicates the key processing logic and might make people use the shorter `ButtonInput` even when it's not appropriate. Another option is to add a new struct with both `Key` and `KeyCode`, and use `ButtonInput` with that instead. That would make it more explanatory, but that is a lot of churn. The third alternative is to not do this because it's too niche. I'll add more documentation and take it out of draft if we want to move forward with it. --- crates/bevy_input/src/button_input.rs | 8 +-- crates/bevy_input/src/keyboard.rs | 58 ++++++++++++++----- crates/bevy_input/src/lib.rs | 3 +- examples/input/keyboard_input.rs | 25 +++++++- .../release-notes/key_buttoninput.md | 13 +++++ 5 files changed, 86 insertions(+), 21 deletions(-) create mode 100644 release-content/release-notes/key_buttoninput.md diff --git a/crates/bevy_input/src/button_input.rs b/crates/bevy_input/src/button_input.rs index 58ab62aefa..e4ff47f470 100644 --- a/crates/bevy_input/src/button_input.rs +++ b/crates/bevy_input/src/button_input.rs @@ -122,7 +122,7 @@ use { /// [`DetectChangesMut::bypass_change_detection`]: bevy_ecs::change_detection::DetectChangesMut::bypass_change_detection #[derive(Debug, Clone, Resource)] #[cfg_attr(feature = "bevy_reflect", derive(Reflect), reflect(Default, Resource))] -pub struct ButtonInput { +pub struct ButtonInput { /// A collection of every button that is currently being pressed. pressed: HashSet, /// A collection of every button that has just been pressed. @@ -131,7 +131,7 @@ pub struct ButtonInput { just_released: HashSet, } -impl Default for ButtonInput { +impl Default for ButtonInput { fn default() -> Self { Self { pressed: Default::default(), @@ -143,12 +143,12 @@ impl Default for ButtonInput { impl ButtonInput where - T: Copy + Eq + Hash + Send + Sync + 'static, + T: Clone + Eq + Hash + Send + Sync + 'static, { /// Registers a press for the given `input`. pub fn press(&mut self, input: T) { // Returns `true` if the `input` wasn't pressed. - if self.pressed.insert(input) { + if self.pressed.insert(input.clone()) { self.just_pressed.insert(input); } } diff --git a/crates/bevy_input/src/keyboard.rs b/crates/bevy_input/src/keyboard.rs index 909880ac7a..70efe18a84 100644 --- a/crates/bevy_input/src/keyboard.rs +++ b/crates/bevy_input/src/keyboard.rs @@ -92,8 +92,9 @@ use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; /// /// ## Usage /// -/// The event is consumed inside of the [`keyboard_input_system`] -/// to update the [`ButtonInput`](ButtonInput) resource. +/// The event is consumed inside of the [`keyboard_input_system`] to update the +/// [`ButtonInput`](ButtonInput) and +/// [`ButtonInput`](ButtonInput) resources. #[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq, Hash)] #[cfg_attr( feature = "bevy_reflect", @@ -107,8 +108,12 @@ use bevy_reflect::{ReflectDeserialize, ReflectSerialize}; )] pub struct KeyboardInput { /// The physical key code of the key. + /// + /// This corresponds to the location of the key independent of the keyboard layout. pub key_code: KeyCode, - /// The logical key of the input + /// The logical key of the input. + /// + /// This corresponds to the actual key taking keyboard layout into account. pub logical_key: Key, /// The press state of the key. pub state: ButtonState, @@ -148,32 +153,46 @@ pub struct KeyboardInput { )] pub struct KeyboardFocusLost; -/// Updates the [`ButtonInput`] resource with the latest [`KeyboardInput`] events. +/// Updates the [`ButtonInput`] and [`ButtonInput`] resources with the latest [`KeyboardInput`] events. /// /// ## Differences /// -/// The main difference between the [`KeyboardInput`] event and the [`ButtonInput`] resources is that +/// The main difference between the [`KeyboardInput`] event and the [`ButtonInput`] resources are that /// the latter has convenient functions such as [`ButtonInput::pressed`], [`ButtonInput::just_pressed`] and [`ButtonInput::just_released`] and is window id agnostic. +/// +/// There is a [`ButtonInput`] for both [`KeyCode`] and [`Key`] as they are both useful in different situations, see their documentation for the details. pub fn keyboard_input_system( - mut key_input: ResMut>, + mut keycode_input: ResMut>, + mut key_input: ResMut>, mut keyboard_input_events: EventReader, mut focus_events: EventReader, ) { - // Avoid clearing if it's not empty to ensure change detection is not triggered. + // Avoid clearing if not empty to ensure change detection is not triggered. + keycode_input.bypass_change_detection().clear(); key_input.bypass_change_detection().clear(); + for event in keyboard_input_events.read() { let KeyboardInput { - key_code, state, .. + key_code, + logical_key, + state, + .. } = event; match state { - ButtonState::Pressed => key_input.press(*key_code), - ButtonState::Released => key_input.release(*key_code), + ButtonState::Pressed => { + keycode_input.press(*key_code); + key_input.press(logical_key.clone()); + } + ButtonState::Released => { + keycode_input.release(*key_code); + key_input.release(logical_key.clone()); + } } } // Release all cached input to avoid having stuck input when switching between windows in os if !focus_events.is_empty() { - key_input.release_all(); + keycode_input.release_all(); focus_events.clear(); } } @@ -220,13 +239,13 @@ pub enum NativeKeyCode { /// It is used as the generic `T` value of an [`ButtonInput`] to create a `Res>`. /// /// Code representing the location of a physical key -/// This mostly conforms to the UI Events Specification's [`KeyboardEvent.code`] with a few +/// This mostly conforms to the [`UI Events Specification's KeyboardEvent.code`] with a few /// exceptions: /// - The keys that the specification calls `MetaLeft` and `MetaRight` are named `SuperLeft` and /// `SuperRight` here. /// - The key that the specification calls "Super" is reported as `Unidentified` here. /// -/// [`KeyboardEvent.code`]: https://w3c.github.io/uievents-code/#code-value-tables +/// [`UI Events Specification's KeyboardEvent.code`]: https://w3c.github.io/uievents-code/#code-value-tables /// /// ## Updating /// @@ -756,6 +775,19 @@ pub enum NativeKey { /// The logical key code of a [`KeyboardInput`]. /// +/// This contains the actual value that is produced by pressing the key. This is +/// useful when you need the actual letters, and for symbols like `+` and `-` +/// when implementing zoom, as they can be in different locations depending on +/// the keyboard layout. +/// +/// In many cases you want the key location instead, for example when +/// implementing WASD controls so the keys are located the same place on QWERTY +/// and other layouts. In that case use [`KeyCode`] instead. +/// +/// ## Usage +/// +/// It is used as the generic `T` value of an [`ButtonInput`] to create a `Res>`. +/// /// ## Technical /// /// Its values map 1 to 1 to winit's Key. diff --git a/crates/bevy_input/src/lib.rs b/crates/bevy_input/src/lib.rs index 653af4c991..5a6a177223 100644 --- a/crates/bevy_input/src/lib.rs +++ b/crates/bevy_input/src/lib.rs @@ -49,7 +49,7 @@ use bevy_ecs::prelude::*; #[cfg(feature = "bevy_reflect")] use bevy_reflect::Reflect; use gestures::*; -use keyboard::{keyboard_input_system, KeyCode, KeyboardFocusLost, KeyboardInput}; +use keyboard::{keyboard_input_system, Key, KeyCode, KeyboardFocusLost, KeyboardInput}; use mouse::{ accumulate_mouse_motion_system, accumulate_mouse_scroll_system, mouse_button_input_system, AccumulatedMouseMotion, AccumulatedMouseScroll, MouseButton, MouseButtonInput, MouseMotion, @@ -89,6 +89,7 @@ impl Plugin for InputPlugin { .add_event::() .add_event::() .init_resource::>() + .init_resource::>() .add_systems(PreUpdate, keyboard_input_system.in_set(InputSystems)) // mouse .add_event::() diff --git a/examples/input/keyboard_input.rs b/examples/input/keyboard_input.rs index ec9b97973e..1e00e0e695 100644 --- a/examples/input/keyboard_input.rs +++ b/examples/input/keyboard_input.rs @@ -1,6 +1,6 @@ //! Demonstrates handling a key press/release. -use bevy::prelude::*; +use bevy::{input::keyboard::Key, prelude::*}; fn main() { App::new() @@ -9,8 +9,13 @@ fn main() { .run(); } -/// This system prints 'A' key state -fn keyboard_input_system(keyboard_input: Res>) { +/// This system responds to certain key presses +fn keyboard_input_system( + keyboard_input: Res>, + key_input: Res>, +) { + // KeyCode is used when you want the key location across different keyboard layouts + // See https://w3c.github.io/uievents-code/#code-value-tables for the locations if keyboard_input.pressed(KeyCode::KeyA) { info!("'A' currently pressed"); } @@ -21,4 +26,18 @@ fn keyboard_input_system(keyboard_input: Res>) { if keyboard_input.just_released(KeyCode::KeyA) { info!("'A' just released"); } + + // Key is used when you want a specific key, no matter where it is located. + // This is useful for symbols that have a specific connotation, e.g. '?' for + // a help menu or '+'/'-' for zoom + let key = Key::Character("?".into()); + if key_input.pressed(key.clone()) { + info!("'?' currently pressed"); + } + if key_input.just_pressed(key.clone()) { + info!("'?' just pressed"); + } + if key_input.just_released(key) { + info!("'?' just released"); + } } diff --git a/release-content/release-notes/key_buttoninput.md b/release-content/release-notes/key_buttoninput.md new file mode 100644 index 0000000000..3124a59440 --- /dev/null +++ b/release-content/release-notes/key_buttoninput.md @@ -0,0 +1,13 @@ +--- +title: ButtonInput for Key +authors: ["@kristoff3r"] +pull_requests: [19684] +--- + +Bevy now has a `ButtonInput` resource, similarly to the existing `ButtonInput` resource. + +The difference between `KeyCode` and `Key` is that the former refers to the +button location on a US keyboard independent of the actual layout in use, while +`Key` gives you the actual letter or symbol that was entered. In most cases you +still want to use `KeyCode`, but in some cases it makes more sense to use `Key`, +for example when using '+'/'-' to zoom.