Skip to content

A Flutter plugin to handle gamepad input across multiple platforms.

License

Notifications You must be signed in to change notification settings

flame-engine/gamepads

Repository files navigation

gamepads

A Flutter plugin to handle gamepad input across multiple platforms.

Badge for latest release Badge for build status Badge for Discord server Badge showing that Melos is used


Note: This plugin is still in beta. All APIs are subject to change. Any feedback is appreciated.

Gamepads is a Flutter plugin to handle gamepad (or joystick) input across multiple platforms.

It supports multiple simultaneously connected gamepads, and will automatically detect and listen to new connections.

Getting Started

The list method will list all currently connected gamepads:

  final gamepads = await Gamepads.list();
  // ...

This uses the data class GamepadController, which has an id and a user-facing name.

And the events stream will broadcast input events from all gamepads:

  Gamepads.events.listen((event) {
    // ...
  });

You can also listen to events only for a specific gamepad with eventsByGamepad.

Events are described by the data class GamepadEvent:

class GamepadEvent {
  /// The id of the gamepad controller that fired the event.
  final String gamepadId;

  /// The timestamp in which the event was fired, in milliseconds since epoch.
  final int timestamp;

  /// The [KeyType] of the key that was triggered.
  final KeyType type;

  /// A platform-dependant identifier for the key that was triggered.
  final String key;

  /// The current value of the key.
  final double value;

  // ...
}

Next Steps

As mentioned, this is still a WIP library. Not only APIs are expected to change if needed, but we plan to add more features, like:

  • stream to listen for connecting/disconnecting gamepads
  • get current state of a gamepad
  • add support for web and even mobile

If you are interested in helping, please reach out! You can use GitHub or our Discord server.

Android Integration

The Android implementation requires the application's Activity to forward input events (and input devices) to the plugin. Below is an example of a MainActivity for a clean Flutter project that has implemented the required boilerplate code. For many projects it will be possible to simply duplicate this setup.

package [YOUR_PACKAGE_NAME]

import android.hardware.input.InputManager
import android.os.Handler
import android.view.InputDevice
import android.view.KeyEvent
import android.view.MotionEvent
import io.flutter.embedding.android.FlutterActivity
import org.flame_engine.gamepads_android.GamepadsCompatibleActivity

class MainActivity: FlutterActivity(), GamepadsCompatibleActivity {
    var keyListener: ((KeyEvent) -> Boolean)? = null
    var motionListener: ((MotionEvent) -> Boolean)? = null

    override fun dispatchGenericMotionEvent(motionEvent: MotionEvent): Boolean {
        return motionListener?.invoke(motionEvent) ?: false
    }
    
    override fun dispatchKeyEvent(keyEvent: KeyEvent): Boolean {
        return keyListener?.invoke(keyEvent) ?: false
    }

    override fun registerInputDeviceListener(
      listener: InputManager.InputDeviceListener, handler: Handler?) {
        val inputManager = getSystemService(INPUT_SERVICE) as InputManager
        inputManager.registerInputDeviceListener(listener, null)
    }

    override fun registerKeyEventHandler(handler: (KeyEvent) -> Boolean) {
        keyListener = handler
    }

    override fun registerMotionEventHandler(handler: (MotionEvent) -> Boolean) {
        motionListener = handler
    }
}

Support

The simplest way to show us your support is by giving the project a star! ⭐

If you want, you can also support us monetarily by donating through OpenCollective:

Open Collective donate button

Through GitHub Sponsors:

GitHub Sponsor button

Or by becoming a patron on Patreon:

Patreon donate button