README.md

gamepads

A Flutter plugin to handle gamepad input across multiple platforms.

---

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:

Through GitHub Sponsors:

Or by becoming a patron on Patreon: