Add support for getting a joypad's battery and connection information

[Nintorch]

• Closes Add support for getting a joypad's battery and connection information godot-proposals#14482

I decided to split my big SDL3 joypad features PR ( #107967 ) into several smaller PRs, this PR is one of them.

This PR adds the ability to get information about the joypad's battery state (no battery, charging, fully charged), battery percentage, connection state (wired, wireless).

Relevant SDL documentation:
SDL_GetJoystickPowerInfo
SDL_GetJoystickConnectionState

This PR used to have a name Add support for querying more joypad information, but was repurposed to Add support for getting a joypad's battery and connection information since getting button/axis names and has_joy_axis/button() might not be necessary to be builtin in Godot, and get_joy_model(), get_joy_type() have been moved into a separate PR ( #117526 ).

Old TODO

• JOY_MODEL_STEAM_DECK documentation
• Throttle documentation I don't have access to one :(
• get_joy_num_axes/buttons() I think checking if a joypad has a particular axis/button is more useful
• has_joy_axis/button()
• Mark as experimental
• Supersede Re-add and improve methods to get the name of gamepad inputs #89193
• get_joy_model() and get_joy_scheme() for Android and Web (depends on Add support for SDL-compatible joypad GUID and Input.get_joy_info() on Android #114338 and Add support for Input.get_joy_info() for web #114589 ) (Support for other platforms will be done in a separate PR)
• get_joy_power_state() and get_joy_battery_percent() for Android ( https://stackoverflow.com/questions/78331095/how-to-get-battery-level-of-a-game-controller-from-an-android-application and https://developer.android.com/reference/android/hardware/BatteryState )
• has_joy_axis/button() for Android and Web based on Godot's mapping system
• Mark as available on iOS (see also Add support for SDL3 joystick input driver for iOS #114316 )
• Remove button/axis name functionality
• Remove get_joy_model() and get_joy_type() functionality since it's been moved into a separate PR ( Add support for querying joypad type, model and layout scheme #117526 )

[Nintorch]

Thank you for your review, AThousandShips!

[Nintorch]

This needs more documentation too, but I'm not sure where to get it/how to make it :(

[Nintorch]

What should we call JOY_MODEL_STEAM_DECK since Valve has announced the new Steam Controller with the same layout? :D

[clarence112]

What should we call JOY_MODEL_STEAM_DECK since Valve has announced the new Steam Controller with the same layout? :D

Maybe just JOY_MODEL_STEAM ? Or keep as-is and add another entry for the controller, since it technically has that extra capacitive grip input that the deck doesn't, as well as traditional rumble motors in addition to haptics.
And maybe JOY_MODEL_STEAM_LEGACY or something for the original steam controller, too?
(idk if this is dependent on how SDL reports things tho, since I haven't looked too close at your code)

[Nintorch]

Or keep as-is and add another entry for the controller, since it technically has that extra capacitive grip input that the deck doesn't, as well as traditional rumble motors in addition to haptics

Hm, I think that's a good idea :D

[Nintorch]

Thank you for your review, AThousandShips! I included your suggested changes into the code!

[Nintorch]

@DanielSnd Hello, sorry for bothering you, but may I ask if you can help with Steam Deck documentation for this PR as I don't have one myself, if you're willing to do so of course?
May I ask what would be the button names that should be returned for Steam Deck by get_joy_model_button_string() and what buttons are present by using has_joy_button()?

[DanielSnd]

@DanielSnd Hello, sorry for bothering you, but may I ask if you can help with Steam Deck documentation for this PR as I don't have one myself, if you're willing to do so of course? May I ask what would be the button names that should be returned for Steam Deck by get_joy_model_button_string() and what buttons are present by using has_joy_button()?

I'm not super sure what that means. Do I have to run some code on the steamdeck and send you the output? I could do that if that's the case. I'm not super familiar with this stuff.

[Nintorch]

Sure, I can prepare a test project later!

[DanielSnd]

Sure, I can prepare a test project later!

Sounds good then :)

[Nintorch]

Here :D
joypad-info-test.zip

And I just found a web page with Steam Deck's buttons and their names, so we will use it to get more specific button names. https://steamcommunity.com/sharedfiles/filedetails/?id=2804823261&ysclid=mjy9ogdptd46361097

May I ask if you can test the project above, verify that the model name is "Steam Deck", press every button on the Steam Deck that is usable in games and save the reported names for them that are shown in "Last pressed button" label?

[Nintorch]

I decided to use thirdparty/sdl/joystick/controller_type.h and thirdparty/sdl/joystick/controller_list.h directly instead of relying on SDL_GetGamepadType() so that we can use Input.get_joy_model() and Input.get_joy_scheme() on platforms where SDL support is not currently planned, i.e. Android and web. We should be able to use these headers there since they don't use other SDL code/headers.

[Nintorch]

I might move the buttons/axes names into a separate PR, I think I have a better way to make this functionality
I thought about something like Input.get_action_input_names(device = -1) that allows the developer to retrieve the button/axis names (not IDs) from input actions, and the names will depend on the joypad's model and scheme.
Basically, if there are keyboard buttons and joypad buttons in an action, this method would return keyboard button names if the last used device wasn't a joypad, and joypad button names otherwise.
Getting button IDs makes sense, but they're separate enums, so multiple methods would have to be created, and I think InputMap.action_get_events() (I hope I got the name right) is better suited for this.

Or it might make sense to let the developers themselves provide the buttons/axes names based on the joypad model.

[Nintorch]

I was thinking about writing a proposal for this PR (specifically, for battery and connection information), but now that I think about it, these methods might not be useful for games, since I currently can't find an example of games that use those and I currently can't think of a good reason to use those in a game, in which case I might remove these features from this PR (unless we can find a good reason for them to exist in Godot).

[autione]

Would it be too harmful to keep them though? If it's not too costly, then I personally think there would be no downsides to keeping these methods available for those few who can find a use for it.

Consider that Godot is also used for things beyond just games, like desktop apps or even development tools as well. For example, if someone is developing a gamepad tester/viewer, or a launcher app, or anything that would benefit from visual display of this queried info.

Whereas for games, I can imagine being able to query battery info coming in handy to let the player know their controller is low on battery, then pausing the game or suggesting them to save their progress, plug the controller in or switch controllers.

Similarly for connection information, if I understood what it means correctly, games could use that to warn about features that won't work over a wireless connection, for example. Some games on Steam do that already, especially if they use fancy hardware-specific capabilities that only work through USB or whatnot.

[Nintorch]

Hm, in this case I think I should write a proposal for this functionality and keep this PR for it.

EDIT: Done! godotengine/godot-proposals#14482