Skip to main content

just_gamepads 0.2.0 copy "just_gamepads: ^0.2.0" to clipboard
just_gamepads: ^0.2.0 copied to clipboard

Gamepad input for Flutter: Xbox, PlayStation, Nintendo and generic controllers in one standard layout. Tested with a pad on Windows; other platforms not yet.

Just Gamepads #

Gamepad input for Flutter on Android, iOS, macOS, Windows, Linux and the web, including WebAssembly builds. Xbox, PlayStation, Nintendo and generic controllers all report in one standard button and axis layout, so game code never deals with per-brand or per-platform differences.

Status. Only the Windows backend has been run with real controllers so far. The Android backend builds but has not been driven by a pad, and the Linux, iOS and macOS backends have not been built yet. See Platform support, and please report what you find.

Features #

  • Every connected controller, with connect and disconnect events, ready for local multiplayer.
  • Full-state snapshots per controller: no deltas to reassemble.
  • One layout everywhere: the W3C Standard Gamepad buttons and axes, with sticks in -1..1 (Y down-positive) and triggers in 0..1.
  • mostRecentlyActiveId: the controller a player touched last, for single-player games. Stick drift on an idle controller doesn't count.
  • Controller families (Xbox, PlayStation, Nintendo, generic) for picking button glyphs.

Platform support #

Platform Backend Verified Notes
Windows 10+ Windows.Gaming.Input Built, and run with real controllers Xbox controllers natively; others through RawGameController
Android Key and motion events Built (APK); not yet run with a controller
Web (JS and WASM) Browser Gamepad API Compiled; not yet run with a controller Controllers appear after a button press
Linux evdev (/dev/input) Not yet built. Its mapping helpers have unit tests (linux/test/) No extra system libraries
iOS 13+ GameController framework Not yet built Extended gamepads (Xbox, PlayStation, Switch Pro, MFi)
macOS 10.15+ GameController framework Not yet built Extended gamepads (Xbox, PlayStation, Switch Pro, MFi)

The Dart side, the wire protocol every backend speaks and each backend's mapping tables are tested on every change (see Testing); what is untested is each platform's own build and its behaviour with real hardware.

Getting started #

flutter pub add just_gamepads
import 'package:just_gamepads/just_gamepads.dart';

final pads = GamepadManager.instance;

pads.connections.listen((event) {
  print('${event.info.name} (${event.info.type.name}) '
      '${event.connected ? 'connected' : 'disconnected'}');
});

pads.stateChanges.listen((event) {
  final state = event.state;
  final jump = state.buttonsDown.contains(GamepadButton.a);
  final moveX = state.axes[GamepadAxis.leftStickX] ?? 0.0;
  // ...
});

await pads.start();

Subscribe before calling start() to receive the controllers that are already connected as events; afterwards they are also listed in pads.connected. The latest state of any controller is available from pads.latestState(id) at any time.

Call pads.dispose() when the game shuts down.

The standard layout #

Face buttons are named by position, using Xbox letters: GamepadButton.a is the bottom face button on every controller.

Index GamepadButton Xbox PlayStation Nintendo
0 a A Cross B
1 b B Circle A
2 x X Square Y
3 y Y Triangle X
4 leftBumper LB L1 L
5 rightBumper RB R1 R
6 leftTriggerButton LT L2 ZL
7 rightTriggerButton RT R2 ZR
8 back View Share / Create Minus
9 start Menu Options Plus
10 leftStickPress LS L3 Left stick press
11 rightStickPress RS R3 Right stick press
12-15 dpadUp, dpadDown, dpadLeft, dpadRight D-pad D-pad D-pad
GamepadAxis Range
leftStickX, rightStickX -1 (left) to 1 (right)
leftStickY, rightStickY -1 (up) to 1 (down)
leftTrigger, rightTrigger 0 (released) to 1 (fully pressed)

The trigger buttons are derived from the analog triggers past triggerButtonThreshold (0.5) on platforms that only report an axis. Raw stick values are passed through as reported: apply your own deadzone.

GamepadInfo.type gives the controller family for glyphs. It is GamepadType.generic for controllers it can't identify.

Platform notes #

Web. Browsers expose a controller only after the user presses a button on it while the page has focus. Both flutter build web and flutter build web --wasm are supported. Controllers are polled once per animation frame while one is connected, and not at all while none is. A controller the browser does not map to the standard layout goes through the positional mapper, with its trigger axes rescaled from the browser's -1..1 to 0..1.

Linux. The app reads /dev/input/event* directly. Desktop distributions give the logged-in user access to game controllers; sandboxed apps (Flatpak, Snap) need device access granted. Controllers without the kernel's standard gamepad mapping are reported positionally, like on the other platforms' fallback paths.

Windows. Xbox and XInput controllers are read through the Gamepad API; PlayStation, Switch and generic controllers through RawGameController. Windows may withhold controller input from apps that aren't in the foreground.

Android. Controller key events still reach Flutter as well, as KeyEvents with LogicalKeyboardKey.gameButton* keys. The d-pad keys Android makes up from stick motion nobody handled (fallback keys) are not read as d-pad presses; they still reach Flutter as arrow keys. When the app's window loses focus (the notification shade, a dialog), every controller is reported at rest until its next event.

iOS and macOS. Controllers that only offer a micro gamepad profile (such as the Siri Remote) are not reported.

Testing #

GamepadManager accepts any GamepadBackend, so tests can drive it with a fake instead of real hardware. GamepadBackend is an interface: a fake implements it.

import 'dart:async';

import 'package:just_gamepads/just_gamepads.dart';

class FakeBackend implements GamepadBackend {
  final _connections = StreamController<GamepadConnectionEvent>.broadcast();
  final _states = StreamController<GamepadStateEvent>.broadcast();

  /// Reports [buttons] held on the controller [id], as a platform would.
  void hold(String id, Set<int> buttons) => _states.add(
    GamepadStateEvent(gamepadId: id, state: GamepadState(buttonsDown: buttons)),
  );

  @override
  Future<void> start() async {}

  @override
  List<GamepadInfo> get connected => const [];

  @override
  Stream<GamepadConnectionEvent> get connections => _connections.stream;

  @override
  Stream<GamepadStateEvent> get stateChanges => _states.stream;

  @override
  void dispose() {
    _connections.close();
    _states.close();
  }
}

final backend = FakeBackend();
final manager = GamepadManager(backend: backend);
backend.hold('pad-1', {GamepadButton.a});

The example/ app is a live controller tester for checking a controller on real hardware. The package's own tests, including the native unit tests and the checks that every backend speaks the wire protocol, are described in CONTRIBUTING.md.

License #

BSD 3-Clause. See LICENSE.

1
likes
160
points
411
downloads

Documentation

API reference

Publisher

verified publisherjustunknown.com

Weekly Downloads

Gamepad input for Flutter: Xbox, PlayStation, Nintendo and generic controllers in one standard layout. Tested with a pad on Windows; other platforms not yet.

Homepage
Repository (GitHub)
View/report issues
Contributing

Topics

#gamepad #controller #input #gamedev #game

License

BSD-3-Clause (license)

Dependencies

flutter, flutter_web_plugins, meta, web

More

Packages that depend on just_gamepads

Packages that implement just_gamepads