Add support for querying hardware controls (such as volume up/down inputs) on Android

Describe the project you are working on

I am working on a cross-platform mobile game that relies on innovative input methods to enhance accessibility and user experience. Specifically, I want to enable players to interact with the game using external physical buttons on Android devices, such as the volume up/down buttons, headset buttons, or other hardware controls available on modern smartphones. This feature is particularly useful for users with limited mobility or those who prefer minimal on-screen touch interaction.

Describe the problem or limitation you are having in your project

Currently, Godot lacks built-in support for detecting input from Android external buttons such as the volume controls. While touchscreens are the primary input method for mobile devices, physical buttons provide an intuitive and accessible way to interact with games or applications. The absence of this feature limits the potential input methods for mobile game developers and restricts accessibility for users who rely on hardware buttons for navigation or interaction.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The proposed feature would enable Godot to natively recognize and process input from Android external buttons, such as volume up, volume down, and headset buttons. This would:

• Allow developers to bind external button inputs to specific actions in their games or applications (e.g., controlling a character, pausing the game, or toggling options).

• Improve accessibility by providing alternative input methods for players with disabilities.

• Expand the input capabilities of Godot for Android, making it more competitive with other game engines that offer similar features.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

The implementation involves integrating Android's key event handling API into Godot's input system. Here is how it could work:

Core Implementation Details

Android Key Event Mapping Modify the Android platform layer in Godot to capture key events for external buttons. For example:

• KeyEvent.KEYCODE_VOLUME_UP for the volume up button. • KeyEvent.KEYCODE_VOLUME_DOWN for the volume down button. • Other key codes as needed (e.g., KEYCODE_HEADSETHOOK for headset buttons).

Integration into Godot's Input System Map these key events to Godot’s InputEvent system. This allows developers to use Input.is_action_pressed() and InputMap for external button inputs, just like touchscreen or keyboard inputs.
Optional Remapping Provide a way for developers to remap external button inputs in the Godot editor via InputMap.

Code Example • Java Implementation for Android Platform Layer Modify the Android activity to handle external button events and pass them to the Godot engine:

@Override
public boolean onKeyDown(int keyCode, KeyEvent event) {
    if (keyCode == KeyEvent.KEYCODE_VOLUME_UP || keyCode == KeyEvent.KEYCODE_VOLUME_DOWN) {
        GodotLib.key(keyCode, true); // Pass the event to Godot
        return true; // Prevent default system behavior
    }
    return super.onKeyDown(keyCode, event);
}

@Override
public boolean onKeyUp(int keyCode, KeyEvent event) {
    if (keyCode == KeyEvent.KEYCODE_VOLUME_UP || keyCode == KeyEvent.KEYCODE_VOLUME_DOWN) {
        GodotLib.key(keyCode, false); // Pass the event to Godot
        return true; // Prevent default system behavior
    }
    return super.onKeyUp(keyCode, event);
}

• GDScript Usage Developers can bind the buttons to actions in the editor or handle them directly in script:

if Input.is_action_pressed("volume_up"):
    print("Volume Up button pressed!")

Mock-Up of Input Map Integration The Input Map editor would display a new category for external buttons under "Key Mapping," such as:

• Volume Up • Volume Down • Headset Button

If this enhancement will not be used often, can it be worked around with a few lines of script?

No, this enhancement cannot be easily worked around with script alone. It requires low-level integration with Android's key event APIs, which are not accessible via GDScript or the current Godot API. While developers could theoretically modify the engine themselves, this is not practical for most users and would fragment the community.

Is there a reason why this should be core and not an add-on in the asset library?

This feature should be part of Godot’s core for the following reasons:

• Platform-Specific Functionality: Handling Android key events requires modifications to the platform layer, which is not accessible to asset library plugins. • Cross-Platform Consistency: Integrating this into the core ensures a consistent API across platforms, which is essential for developers targeting multiple devices. • Accessibility: Including this feature in the core supports Godot’s mission of making game development accessible and inclusive to all developers and players.

godotengine / godot-proposals