A downloadable asset pack for Android

Download NowName your own price

Detecting android hard keys events like the volume up/down,  power button and Android TV remotes,  was never so easy before!

This project is in alpha state and is not considered stable or ready for production, but you are welcome to download it for free and use it in any way you wish. 

This extension serves two primary purposes :

  •  To detect natively any detectable hard key that GMS2 cannot detect, like the power button, sound volume buttons, media buttons etc
  •  To allow very easy integration of Android TV remote input, without the developer messing with asynchronous events.

This extension is not suitable to those that intent to implement gamepad functionality with GMS2.


How to use it

The API is minimal and very similar to the GMS2 functions, offering usage familiarity.

With the function android_key_pressed(keycode)  you can check to see if a key has been pressed or not.

With the function android_key_check(keycode)  you can check to see if a key is held down or not.

With the function android_key_released(keycode)  you can check to see if a key has been released or not.

The default GMS2 keycodes like vk_up, vk_space etc are not compatible with the extension. The extension uses the native keycodes and they have been set as macros in the supplementary extension AndroidEventKeycodes. You can macro yourself the ones that you need and do not include the supplementary extension to avoid over flowing the code autocompletion. You can see the complete keycodes list [here]. Please note that the equivalent to vk_any  is the real -1 and has been set as KEYCODE_ANY macro.


What is happening behind the scenes

The three functions above when called, are checking if there is already exists an instance of the object o_android_core_events. If does not exist then the instantiation occurs at depth level 16001 and the functions are fully working at the next step. While this is the indented behavior, it has not been tested extensively at the current alpha state of the project, so it is recommended to put an instance of the o_android_core_events at the first room and make it persistent, for now. You can refer to object  o_android_core_events with the macro core_events, as long as an instance of it exists.

The o_android_core_events object creates the  ds map events_map on create event or room start event if persistent.  The events_map is a copy of the async_load which receives the events from the java native code. The events_map can be accessed from other objects, by using the macro core_events_map.

You can use the contents of core_events_map directly if you want, but first you must manually instantiate the core_events and make sure that the core_events_map has been created. To get the events data from the core_events_map, use the key ON_KEY_DOWN_LENGHT first:

var _total_keys_down =  ds_map_find_value(core_events_map, ON_KEY_DOWN_LENGHT);

The ON_KEY_DOWN_LENGHT will return the number of keys that are currently down. Use this number with a loop to access all the events data:

for (var i = 0; i < _total_keys_down; i++)
{        
    var _key_check = ds_map_find_value(core_events_map, ON_KEY_DOWN_KEYCODE + string(i));
    var _key_pressed = ds_map_find_value(core_events_map, ON_KEY_DOWN_PRESSED_KEYCODE + string(i))
    var _key_released = ds_map_find_value(core_events_map, ON_KEY_UP_KEYCODE);
    var _key_name = ds_map_find_value(core_events_map, ON_KEY_DOWN_TO_STRING + string(i));
}

The ON_KEY_DOWN_KEYCODE + string(i), returns the keycodes of the  keys that are currently down. If 3 keys are currently down then you will find the corresponding keycodes in ON_KEY_DOWN_KEYCODE+"0", ON_KEY_DOWN_KEYCODE+"1" and ON_KEY_DOWN_KEYCODE+"2". Same applies to the rest of the map keys. ON_KEY_DOWN_PRESSED_KEYCODE+"0", ON_KEY_DOWN_PRESSED_KEYCODE+"1",... for the pressed keys and ON_KEY_UP_KEYCODE+"0",.. for the released keys. The keys ON_KEY_DOWN_TO_STRING+"0",.. are contain the keycodes as strings for debugging.
Example: If the user presses the up arrow of the tv remote's dpad and no other keys are currently down then:

  • The ON_KEY_DOWN_LENGHT will be 1
  • The ON_KEY_DOWN_KEYCODE +"0" will be 19 as long as the user is holding down the key.
  • The ON_KEY_DOWN_PRESSED_KEYCODE+"0" will be 19 for 1 step after pressing the key.
  • The ON_KEY_UP_KEYCODE+"0" will be 19 for 1 step after releasing the key.
  • The ON_KEY_DOWN_TO_STRING+"0" will be "KEYCODE_DPAD_UP" as long as the user is holding down the key.

(A complete list of the keycodes can be found here)

What next?

I intent in the future to add keys that specifying the device id of the key event and more other useful data for complete integration of multiple input sources. I consider this project as active, developing wise, but know that I can only work on it in the free time between my main projects, so expect a relatively slow progress. The project is free with MIT license, so if you find it useful, consider a small tip to support me.


Some WIP footage



The downloadable files

EDIT: I accidentally forgot to include the core object into the extension packages. I uploaded the fixed packages. I am sorry for the inconvenience...

The downloadable files are:

  • A compiled apk to test the extension on a device
  • the extension itself GMS2.2 and GMS2.3 version
  • the supplementary extension with the keycodes GMS2.2 and GMS2.3 version
  • an example project GMS2.2 and GMS2.3 version

The code is not yet documented. Expect fully documented code at a later more stable release.

Please note that I have not put specific platform conditionals in the example project yet, so any attempt to compile at any non android platform will fail!

Download

Download NowName your own price

Click download now to get access to the following files:

AndroidEvents.apk - The example project compiled for Android 11 MB
AndroidEventsKeycodesGMS23.yymps - Supplementary, only keycodes 12 kB
AndroidEvents-Example-Project-GMS23.yyz - The example project 852 kB
AndroidEvents-Extension-GMS23.yymps - Extension only 24 kB

Development log

Leave a comment

Log in with itch.io to leave a comment.