Split buttons and axes and improve ergonomics of working with gamepad input #3419

alice-i-cecile · 2021-12-23T07:04:09Z

Objective

Principally fixes Button data is typically binary, but is treated as if it were continuous #3398.
Incidentally fixes Type-level disparity between keyboard and gamepad input APIs #3224.
Significantly improves the ergonomics of working with gamepad axes and buttons, as you no longer need to constantly generate GamepadButton structs which store both the gamepad id and the button that is being pressed.

Solution

Adds a value and set_value method to Input, which is appropriately updated. 0.0 is unpressed, 1.0 is pressed, following industry convention.
Made it impossible to use a button-like type (0.0 to 1.0) as an axis (-1.0 to 1.0) by adding the methodless Inputlike and Axislike traits.
Incidentally made it possible to iterate over all of the possible variants of the input types, by pulling in the strum crate's EnumIter trait. We already had some constants for this, which have been removed.

This was simple enough, except that I could not accomplish this nicely for GamepadButton, as its variant type and the input type were not the same (see #3224). Instead of adding an ugly hack with an associated type that was almost always Self I:

Eliminated the existing GamepadButton type, and gave the nice name to GamepadButtonType.
Changed the appropriate Input type to accept the enum.
Managed the "you can have multiple controllers" problem by handing out multiple Input<GamepadButton> types using the freshly added Gamepads type (Make GamepadLobby a built-in type #3245), rather than a single resource which required you to pass in the Gamepad constantly.
Eliminated the dedicated Gamepads management system by rolling it all into the existing gamepad_event_system.
Did the same for GamepadAxis and GamepadAxisType for consistency and a wonderfully smooth API.

Showcase

Before:

fn gamepad_system(
    gamepads: Res<Gamepads>,
    button_inputs: Res<Input<GamepadButton>>,
    button_axes: Res<Axis<GamepadButton>>,
    axes: Res<Axis<GamepadAxis>>,
) {
    for gamepad in gamepads.iter().cloned() {
        if button_inputs.just_pressed(GamepadButton(gamepad, GamepadButtonType::South)) {
            info!("{:?} just pressed South", gamepad);
        } else if button_inputs.just_released(GamepadButton(gamepad, GamepadButtonType::South)) {
            info!("{:?} just released South", gamepad);
        }

        let right_trigger = button_axes
            .get(GamepadButton(gamepad, GamepadButtonType::RightTrigger2))
            .unwrap();
        if right_trigger.abs() > 0.01 {
            info!("{:?} RightTrigger2 value is {}", gamepad, right_trigger2);
        }

        let left_stick_x = axes
            .get(GamepadAxis(gamepad, GamepadAxisType::LeftStickX))
            .unwrap();
        if left_stick_x.abs() > 0.01 {
            info!("{:?} LeftStickX value is {}", gamepad, left_stick_x);
        }
    }

After:

fn gamepad_system(gamepads: Res<Gamepads>) {
    for (gamepad, buttons) in gamepads.buttons.iter() {
        if buttons.just_pressed(GamepadButton::South) {
            info!("{:?} just pressed South", gamepad);
        } else if buttons.just_released(GamepadButton::South) {
            info!("{:?} just released South", gamepad);
        }

        let right_trigger2 = buttons.value(GamepadButton::RightTrigger2);
        if right_trigger2 > 0.01 {
            info!("{:?} RightTrigger2 value is {}", gamepad, right_trigger);
        }
    }

    for (gamepad, axes) in gamepads.axes.iter() {
        let left_stick_x = axes.get(GamepadAxis::LeftStickX).unwrap();
        if left_stick_x.abs() > 0.01 {
            info!("{:?} LeftStickX value is {}", gamepad, left_stick_x);
        }
    }
}

alice-i-cecile · 2021-12-23T19:40:24Z

bors try

bors · 2021-12-23T20:04:42Z

try

Build succeeded:

Any T that implements Intpulike also implements Copy + Eq + Hash

Tiny cosmetic change

# Objective - Significantly improve the ergonomics of gamepads and allow new features Gamepads are a bit unergonomic to work with, they use resources but unlike other inputs, they are not limited to a single gamepad, to get around this it uses an identifier (Gamepad) to interact with anything causing all sorts of issues. 1. There are too many: Gamepads, GamepadSettings, GamepadInfo, ButtonInput<T>, 2 Axis<T>. 2. ButtonInput/Axis generic methods become really inconvenient to use e.g. any_pressed() 3. GamepadButton/Axis structs are unnecessary boilerplate: ```rust for gamepad in gamepads.iter() { if button_inputs.just_pressed(GamepadButton::new(gamepad, GamepadButtonType::South)) { info!("{:?} just pressed South", gamepad); } else if button_inputs.just_released(GamepadButton::new(gamepad, GamepadButtonType::South)) { info!("{:?} just released South", gamepad); } } ``` 4. Projects often need to create resources to store the selected gamepad and have to manually check if their gamepad is still valid anyways. - Previously attempted by #3419 and #12674 ## Solution - Implement gamepads as entities. Using entities solves all the problems above and opens new possibilities. 1. Reduce boilerplate and allows iteration ```rust let is_pressed = gamepads_buttons.iter().any(|buttons| buttons.pressed(GamepadButtonType::South)) ``` 2. ButtonInput/Axis generic methods become ergonomic again ```rust gamepad_buttons.any_just_pressed([GamepadButtonType::Start, GamepadButtonType::Select]) ``` 3. Reduces the number of public components significantly (Gamepad, GamepadSettings, GamepadButtons, GamepadAxes) 4. Components are highly convenient. Gamepad optional features could now be expressed naturally (`Option<Rumble> or Option<Gyro>`), allows devs to attach their own components and filter them, so code like this becomes possible: ```rust fn move_player<const T: usize>( player: Query<&Transform, With<Player<T>>>, gamepads_buttons: Query<&GamepadButtons, With<Player<T>>>, ) { if let Ok(gamepad_buttons) = gamepads_buttons.get_single() { if gamepad_buttons.pressed(GamepadButtonType::South) { // move player } } } ``` --- ## Follow-up - [ ] Run conditions? - [ ] Rumble component # Changelog ## Added TODO ## Changed TODO ## Removed TODO ## Migration Guide TODO --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>

# Objective - Significantly improve the ergonomics of gamepads and allow new features Gamepads are a bit unergonomic to work with, they use resources but unlike other inputs, they are not limited to a single gamepad, to get around this it uses an identifier (Gamepad) to interact with anything causing all sorts of issues. 1. There are too many: Gamepads, GamepadSettings, GamepadInfo, ButtonInput<T>, 2 Axis<T>. 2. ButtonInput/Axis generic methods become really inconvenient to use e.g. any_pressed() 3. GamepadButton/Axis structs are unnecessary boilerplate: ```rust for gamepad in gamepads.iter() { if button_inputs.just_pressed(GamepadButton::new(gamepad, GamepadButtonType::South)) { info!("{:?} just pressed South", gamepad); } else if button_inputs.just_released(GamepadButton::new(gamepad, GamepadButtonType::South)) { info!("{:?} just released South", gamepad); } } ``` 4. Projects often need to create resources to store the selected gamepad and have to manually check if their gamepad is still valid anyways. - Previously attempted by bevyengine#3419 and bevyengine#12674 ## Solution - Implement gamepads as entities. Using entities solves all the problems above and opens new possibilities. 1. Reduce boilerplate and allows iteration ```rust let is_pressed = gamepads_buttons.iter().any(|buttons| buttons.pressed(GamepadButtonType::South)) ``` 2. ButtonInput/Axis generic methods become ergonomic again ```rust gamepad_buttons.any_just_pressed([GamepadButtonType::Start, GamepadButtonType::Select]) ``` 3. Reduces the number of public components significantly (Gamepad, GamepadSettings, GamepadButtons, GamepadAxes) 4. Components are highly convenient. Gamepad optional features could now be expressed naturally (`Option<Rumble> or Option<Gyro>`), allows devs to attach their own components and filter them, so code like this becomes possible: ```rust fn move_player<const T: usize>( player: Query<&Transform, With<Player<T>>>, gamepads_buttons: Query<&GamepadButtons, With<Player<T>>>, ) { if let Ok(gamepad_buttons) = gamepads_buttons.get_single() { if gamepad_buttons.pressed(GamepadButtonType::South) { // move player } } } ``` --- ## Follow-up - [ ] Run conditions? - [ ] Rumble component # Changelog ## Added TODO ## Changed TODO ## Removed TODO ## Migration Guide TODO --------- Co-authored-by: Carter Anderson <mcanders1@gmail.com>

alice-i-cecile added 13 commits December 22, 2021 23:06

Remove Axis<GamepadButton>

ff6e0f6

Standardize naming of GamepadSettings methods

463bb7e

Add the ability to manually get and set values

743095a

Update values for gamepad buttons

ed3902c

#[inline] ALL the tiny methods

d88b529

Differentiate Axis and Input in docs

0b6a7a9

Fixed test that was using a GamepadButton as an axis

00e5b2e

Dumb typos

c88c882

Replace GamepadButton with previous GamepadButtonType type

c28ffaf

Store Input<Gamepad> in central Gamepads resource

8eaf82e

Replace GamepadAxis with previous GamepadAxisType type

5876818

Actually use the right input value in the example

d6bf085

Remove gamepad input resources; now handled through Gamepads

11d51f1

github-actions bot added the S-Needs-Triage This issue needs to be labelled label Dec 23, 2021

alice-i-cecile added 3 commits December 23, 2021 02:23

Better naming in example

0a941d5

Remove unused imports

7e56b35

Remove outdated docs

7c9a53b

alice-i-cecile added A-Input Player input via keyboard, mouse, gamepad, and more C-Usability A targeted quality-of-life change that makes Bevy easier to use S-Needs-Migration-Guide and removed S-Needs-Triage This issue needs to be labelled labels Dec 23, 2021

Improve docs for Gamepad and Gamepads

6c0fd7f

bors bot added a commit that referenced this pull request Dec 23, 2021

Try #3419:

8042e6a

remove unneeded check

707e87f

Any T that implements Intpulike also implements Copy + Eq + Hash

alice-i-cecile mentioned this pull request Dec 30, 2021

Store and return values for virtual buttons Leafwing-Studios/leafwing-input-manager#38

Closed

alice-i-cecile mentioned this pull request Jan 18, 2022

docs: Documentation and clean up of bevy_input #3692

Closed

3 tasks

alice-i-cecile added M-Needs-Migration-Guide A breaking change to Bevy's public API that needs to be noted in a migration guide and removed S-Needs-Migration-Guide labels Jan 20, 2022

Merge pull request #31 from Conando025/axis-button-split

74b924e

Tiny cosmetic change

alice-i-cecile added the X-Controversial There is active debate or serious implications around merging this PR label Apr 26, 2022

alice-i-cecile closed this Jul 31, 2023

alice-i-cecile mentioned this pull request Mar 23, 2024

Improve gamepad input handling ergonomics #12674

Closed

s-puig mentioned this pull request Mar 29, 2024

Implement gamepads as entities #12770

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Split buttons and axes and improve ergonomics of working with gamepad input #3419

Split buttons and axes and improve ergonomics of working with gamepad input #3419

alice-i-cecile commented Dec 23, 2021 •

edited

Loading

alice-i-cecile commented Dec 23, 2021

bors bot commented Dec 23, 2021

Split buttons and axes and improve ergonomics of working with gamepad input #3419

Split buttons and axes and improve ergonomics of working with gamepad input #3419

Conversation

alice-i-cecile commented Dec 23, 2021 • edited Loading

Objective

Solution

Showcase

alice-i-cecile commented Dec 23, 2021

bors bot commented Dec 23, 2021

try

alice-i-cecile commented Dec 23, 2021 •

edited

Loading