Implement gamepads as entities

[s-puig]

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 inconveniences.

1. There are too many structs: Gamepads, GamepadSettings, GamepadInfo, ButtonInput, 2 Axis.
2. ButtonInput/Axis generic methods become really inconvenient to use e.g. any_pressed()
3. GamepadButton/Axis structs are unnecessary boilerplate:

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 Split buttons and axes and improve ergonomics of working with gamepad input #3419 and Improve gamepad input handling ergonomics #12674

Solution

• Implement gamepads as entities.

Using entities solves all the problems above and opens new possibilities.

1. Reduce boilerplate and allows iteration

let is_pressed = gamepads_buttons.iter().any(|buttons| buttons.pressed(GamepadButton::South))

2. ButtonInput/Axis generic methods become ergonomic again

gamepad.any_just_pressed([GamepadButton::Start, GamepadButton::Select])

3. Reduces the number of public components significantly (Gamepad, GamepadSettings)
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:

fn move_player<const T: usize>(
    player: Query<&Transform, With<Player<T>>>,
    gamepads: Query<&Gamepad, With<Player<T>>>,
) {
    if let Ok(gamepad) = gamepads.get_single() {
        if gamepad.pressed(GamepadButton::South) {
            // move player
        }
    }
}

---

Follow-up

• Run conditions?
• Rumble component

Changelog

Gamepads are now entities instead of resources.
Filtering is now done in bevy_input instead of bevy_gilrs.
RawGamepad events are made available to users.

Added

• RawGamepadEvent
• RawGamepadAxisChangedEvent
• RawGamepadButtonChangedEvent
• Gamepad component
• GamepadSettings component
• GamepadInput enum
  • Encapsulation over GamepadButton and GamepadAxis to share the Gamepad.get and Gamepad.get_clamped methods and Axis

Changed

• GamepadAxisType to GamepadAxis
• GamepadButtonType to GamepadButton
• GamepadButtonInput event to GamepadButtonStateChangedEvent

Removed

• Axis resource
• Axis resource
• ButtonInput
• GamepadSettings resource
• Gamepads resource
• Old GamepadAxis no longer exists
• Old GamepadButton no longer exists

Migration Guide

Gamepad input is no longer accessed using resources, instead they are entities and are accessible using the Gamepad component as long as the gamepad is connected.

Gamepads resource has been deleted, instead of using an internal id to identify gamepads you can use its Entity. Disconnected gamepads will NOT be despawned. Gamepad components that don't need to preserve their state will be removed i.e. Gamepad component is removed, but GamepadSettings is kept.
Reconnected gamepads will try to preserve their Entity id and necessary components will be re-inserted.

GamepadSettings is no longer a resource, instead it is a component attached to the Gamepad entity.

Axis, Axis and ButtonInput methods are accessible via Gamepad component.

fn gamepad_system(
-   gamepads: Res<Gamepads>,
-   button_inputs: Res<ButtonInput<GamepadButton>>,
-   button_axes: Res<Axis<GamepadButton>>,
-   axes: Res<Axis<GamepadAxis>>,
+   gamepads: Query<&Gamepad>
) {
    for gamepad in gamepads.iter() {
-      if button_inputs.just_pressed(GamepadButton::new(gamepad, GamepadButtonType::South)) {
+      if gamepad.just_pressed(GamepadButton::South) {
            println!("just pressed South");
        } 
         
-      let right_trigger = button_axes
-           .get(GamepadButton::new(
-               gamepad,
-               GamepadButtonType::RightTrigger2,
-           ))
-           .unwrap();
+      let right_trigger = gamepad.get(GamepadButton::RightTrigger2).unwrap();
        if right_trigger.abs() > 0.01 {
            info!("RightTrigger2 value is {}", right_trigger);      
        }

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

[alice-i-cecile]

I agree with the suggestions from Cart, but feel more strongly about them! Let me know when those are cleaned up and I'll approve and merge this.

[s-puig]

I agree with the suggestions from Cart, but feel more strongly about them! Let me know when those are cleaned up and I'll approve and merge this.

Will LWIM have enough time this late into 0.15? If not, we might want to postpone and merge it early into 0.16 so they have plenty of time.

[alice-i-cecile]

The release candidate period makes me confident that LWIM will be able to port over :)

[s-puig]

@alice-i-cecile Gosh you are fast. I didn't even get the chance to update the changelog!

Anyways here are some relevant issues you might want to take a look related to this PR:

• Sending a GamepadButtonChangedEvent but Axis<GamepadButton> is not changed #13195 Solved by sending RawGamepadEvent that will be used by bevy_input.
• Gamepads cannot be easily manually registered or deregistered #4911 You can send GamepadConnectionEvent to disconnect or connect gamepads.
• Button data is typically binary, but is treated as if it were continuous #3398 I think this should have been closed long ago?
• Type-level disparity between keyboard and gamepad input APIs #3224 I guess we merged them in a way
  ¯\(ツ)/¯
• Partially make Userinput for gamepad and touch more intuitive #5163, analogue values now share a Gamepad::get() and Gamepad::get_clamped() method. Also added the difference between a GamepadAxis (range from [-1.0,1.0]) and GamepadButton(range from [0.0,1.0]).
  I think now we can easily turn GamepadAxis into GamepadButtons if we wanted.

[alice-i-cecile]

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1700 if you'd like to help out.

[Shatur]

Found a small functionality regression, opened #16221