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

1. There are too many: 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(GamepadButtonType::South))

2. ButtonInput/Axis generic methods become ergonomic again

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:

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?
• Recreate the previous GamepadEvent
• Rumble component

Changelog

Added

TODO

Changed

TODO

Removed

TODO

Migration Guide

TODO

[s-puig]

@alice-i-cecile @mockersf I think this is mostly done, i will recheck the docs again once you decide if this should be merged or not.

[alice-i-cecile]

@cart, just to be sure: you're broadly in favor of representing gamepads as entities, correct?

[alice-i-cecile]

Agreed. I'm fine to leave this for follow-up though.

[cart]

Seems like Entity should be that unique id

[s-puig]

Unfortunately, i don't think this is a good idea right now until we can re-create entities with a given id.

Gilrs tries to reuse the same ids for reconnecting gamepads which allows us (and users) a way to preserve state. We could keep some mapping between dropped entities->current entity but that might be a bit of a foot-gun with users expecting their id(entity) to also persist.

EDIT: On second thought, on disconnection, we could leave the entity alive, remove the gamepad components and assume that if the user deleted the entity it no longer wants to preserve the state and create a new one.

[alice-i-cecile]

I like the idea in your edit. Eventually we could use entity disabling instead.

[cart]

@cart, just to be sure: you're broadly in favor of representing gamepads as entities, correct?

Provided we have a satisfying answer to my comment right above this, then yeah I'm broadly in favor.