Treat Android hardware keys (such as the Back button) as InputEvents

[andy-noisyduck]

Describe the project you are working on:
A mobile game for Android

Describe the problem or limitation you are having in your project:
Android supports a hardware back button (modern devices tend to implement this in software as an overlay, but with same functionality). Currently this is handled by raising the MainLoop.NOTIFICATION_WM_GO_BACK_REQUEST notification. This behaviour is inconsistent with other hardware keys, and inconsistent with handling inputs in Godot generally. It also makes working with the back button needlessly complicated.

Describe the feature / enhancement and how it helps to overcome the problem or limitation:
The back key should raise an InputEventKey (or similar, perhaps a new concrete class) as if it was a key press. This not only makes handling the input consistent with other keys, but also means GUI Controls and other nodes handling inputs events can consume the event and stop it propagating (e.g. with accept_event()). See input event diagram.

Right now if you want to handle the hardware key, you end up with a bunch of logic to work out where that event should be processed. The work is non trivial, yet you end up with something that looks a lot like Godot's existing input loop.

My recent use cases of the back key include a stack of popup windows that can be closed, an in-game menu, and navigating through a stack of scenes. These are all cases I would be using Godot's GUI classes for, yet they have no nice way of handling the button.

Describe how your proposal will work, with code, pseudocode, mockups, and/or diagrams:
Covered above.

If this enhancement will not be used often, can it be worked around with a few lines of script?:
More than a few. You could build your own input manager, but it would be non-trivial. It would also seem to go against the designs of the current input system.

Is there a reason why this should be core and not an add-on in the asset library?:
Support for the back button is already core, I just think it can be done in a much friendlier way.

[Calinou]

Which key scancode would the back button correspond to? I'm not sure if making a dedicated scancode for an OS-specific key makes sense.

[andy-noisyduck]

Which key scancode would the back button correspond to? I'm not sure if making a dedicated scancode for an OS-specific key makes sense.

A custom scancode seemed like the path of least resistance to implement something, and would give developers a familiar way of handling input. In my mind the back button is simply another key, and that makes sense to me.

If we wanted to keep InputEventKey as is, then alternatives could include a new subclass of InputEvent to cover device specific hardware keys. Whilst I'm not sure which one of those makes more sense, I'm of the view that the current notification implementation makes the least sense.

Also keep in mind that the back button is not the only key, it's just the one with the more obvious use case, and the only one Godot supports right now (I think).. Most phones have a menu button (not the home button), volume buttons, and a few have a dedicated search button too. These tend to be used less, but if solutions are being looked at, it's worth considering something that could include them all in future.

[maximstewart]

Ok, just came across this trying to help someone figure out how to get volume key events in Android and see this isn't easily done. I'm perplexed as to why this isn't implemented already??

[Calinou]

I'm perplexed as to why this isn't implemented already??

It's probably because nobody really needed it in their project until now 🙂

Godot is a game engine, and listening to volume key events isn't a common need. Can apps even listen to volume key events in the first place on Android (let alone iOS)? These are different from the back button.

[andy-noisyduck]

Can apps even listen to volume key events in the first place on Android (let alone iOS)? These are different from the back button.

They can. Android uses the same callback for all keys, and just has custom key constants for the hardware buttons (including volume).

There's a bunch of mobile specific functionality that should probably remain as being handled by plugins for those platforms, but I would expect input handling to fall within the purview of the engine.

[YuriSizov]

I think for the purposes of clarity a new InputEvent type for hardware buttons is the best option. And indeed, many apps use them for their own things, including the volume rocker.

[OrganicPepper]

I'm just about to start building a couple of escape room style mobile games using Godot, and it would be super handy to be able to interface my game with system hardware buttons. Perhaps pressing volume up and down in a particular pattern causes something to unlock in the game! Although, I appreciate that this is very niche and may not be worth the work.

[syntaxerror247]

Android Back button is now mapped to KEY_BACK in godotengine/godot#95460. This change is available starting with 4.4 dev7.
Example:

func _input(event: InputEvent) -> void:
	if event is InputEventKey and event.keycode == KEY_BACK and event.pressed:
		print("Back key pressed")