feat: New package flame_gamepads (#3886)

lea108 · spydon · web-flow · commit 8cadff21dfac · 2026-03-26T07:10:25.000Z
Adds new package flame_gamepads. This package provides a
GamepadCallbacks mixin to use gamepads library with Flame.

---------

Co-authored-by: Lukas Klingsbo &lt;lukas.klingsbo@gmail.com&gt;
diff --git a/.github/.cspell/words_dictionary.txt b/.github/.cspell/words_dictionary.txt
@@ -25,4 +25,5 @@ rerasterize
 rescan
 Roboto
 tappable
+thumbstick
 underutilize
diff --git a/doc/bridge_packages/bridge_packages.md b/doc/bridge_packages/bridge_packages.md
@@ -36,6 +36,11 @@ Create texture atlases for games (bridge package for [FireAtlas]).
 A Box2D physics engine (bridge package for [Forge2D]).
 :::
 
+:::{package} flame_gamepads
+
+Support gamepad input in your game (bridge package for [gamepads])
+:::
+
 :::{package} flame_isolate
 
 Use isolates to offload heavy computations to another thread.
@@ -101,6 +106,7 @@ Load Typled sprite atlases with edge-repeated padding (bridge package for [Typle
 [Bloc]: https://github.com/felangel/bloc
 [FireAtlas]: https://github.com/flame-engine/fire-atlas
 [Forge2D]: https://github.com/flame-engine/forge2d
+[gamepads]: https://github.com/flame-engine/gamepads
 [Lottie]: https://pub.dev/packages/lottie
 [Rive]: https://rive.app/
 [Riverpod]: https://github.com/rrousselGit/riverpod
diff --git a/doc/bridge_packages/flame_gamepads/flame_gamepads.md b/doc/bridge_packages/flame_gamepads/flame_gamepads.md
@@ -0,0 +1,27 @@
+# flame_gamepads
+
+**flame_gamepads** provides helping bridge functionality to use the `gamepads` package in your flame
+game.
+
+
+## GamepadCallbacks mixin
+
+Add `GamepadCallbacks` mixin to your component with the `with` keyword and override the
+`onGamepadEvent` method to receive callbacks when a gamepad event occurs.
+
+```dart
+class PlayerComponent extends PositionComponent with GamepadCallbacks {
+  @override
+  void onGamepadEvent(NormalizedGamepadEvent event) {
+    if (event.button == GamepadButton.a && event.value != 0) {
+        // 'a' button pressed.
+    }
+  }
+}
+```
+
+An example of how to use the API can be found
+[here](https://github.com/flame-engine/flame/tree/main/packages/flame_gamepads/example).
+
+See the lib [gamepads](https://github.com/flame-engine/gamepads.dart) for more info on how to
+process the NormalizedGamepadEvent data.
diff --git a/packages/flame_gamepads/CHANGELOG.md b/packages/flame_gamepads/CHANGELOG.md
@@ -0,0 +1,4 @@
+
+## 0.1.0
+
+ - Add GamepadCallbacks mixin
diff --git a/packages/flame_gamepads/LICENSE b/packages/flame_gamepads/LICENSE
@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021 Blue Fire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
diff --git a/packages/flame_gamepads/README.md b/packages/flame_gamepads/README.md
@@ -0,0 +1,26 @@
+<!-- markdownlint-disable MD013 -->
+<p align="center">
+  <a href="https://flame-engine.org">
+    <img alt="flame" width="200px" src="https://user-images.githubusercontent.com/6718144/101553774-3bc7b000-39ad-11eb-8a6a-de2daa31bd64.png">
+  </a>
+</p>
+
+<p align="center">
+Support gamepad input in your game (bridge package for <a href="https://github.com/flame-engine/gamepads">gamepads</a>)
+</p>
+
+<p align="center">
+  <a title="Pub" href="https://pub.dev/packages/flame_gamepads" ><img src="https://img.shields.io/pub/v/flame_gamepads.svg?style=popout" /></a>
+  <a title="Test" href="https://github.com/flame-engine/flame/actions?query=workflow%3Acicd+branch%3Amain"><img src="https://github.com/flame-engine/flame/actions/workflows/cicd.yml/badge.svg?branch=main&event=push"/></a>
+  <a title="Discord" href="https://discord.gg/pxrBmy4"><img src="https://img.shields.io/discord/509714518008528896.svg"/></a>
+  <a title="Melos" href="https://github.com/invertase/melos"><img src="https://img.shields.io/badge/maintained%20with-melos-f700ff.svg"/></a>
+</p>
+
+---
+<!-- markdownlint-enable MD013 -->
+
+<!-- markdownlint-disable-next-line MD002 -->
+
+# flame_gamepads
+
+Package to bridge the `gamepads` library to easy-to-use Flame bindings.
diff --git a/packages/flame_gamepads/analysis_options.yaml b/packages/flame_gamepads/analysis_options.yaml
@@ -0,0 +1 @@
+include: package:flame_lint/analysis_options_with_dcm.yaml
diff --git a/packages/flame_gamepads/example/.gitignore b/packages/flame_gamepads/example/.gitignore
@@ -0,0 +1,45 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.build/
+.buildlog/
+.history
+.svn/
+.swiftpm/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+/coverage/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release
diff --git a/packages/flame_gamepads/example/README.md b/packages/flame_gamepads/example/README.md
@@ -0,0 +1,5 @@
+# flame_gamepads example
+
+Simple project to showcase the usage of flame_gamepads input handling.
+
+Use the left stick on your gamepad to control the player.
diff --git a/packages/flame_gamepads/example/analysis_options.yaml b/packages/flame_gamepads/example/analysis_options.yaml
@@ -0,0 +1,5 @@
+include: package:flame_lint/analysis_options_with_dcm.yaml
+
+linter:
+  rules:
+    public_member_api_docs: false
diff --git a/packages/flame_gamepads/example/lib/main.dart b/packages/flame_gamepads/example/lib/main.dart
@@ -0,0 +1,43 @@
+import 'package:flame/components.dart';
+import 'package:flame/game.dart';
+import 'package:flame_gamepads_example/player_component.dart';
+import 'package:flutter/material.dart';
+
+void main() {
+  runApp(GameWidget(game: GamepadsGame()));
+}
+
+class GamepadsGame extends FlameGame {
+  PlayerComponent? player;
+
+  static const worldSizeX = 16.0 * 28;
+  static const worldSizeY = 16.0 * 14;
+
+  GamepadsGame()
+    : super(
+        camera: CameraComponent.withFixedResolution(
+          width: worldSizeX,
+          height: worldSizeY,
+        ),
+      );
+
+  @override
+  Future<void> onLoad() async {
+    camera.viewfinder.zoom = 0.5;
+    camera.moveTo(Vector2(worldSizeX / 2, worldSizeY / 2));
+
+    player = PlayerComponent(worldSizeX: worldSizeX, worldSizeY: worldSizeY)
+      ..position = Vector2(5 * 16, 5 * 16)
+      ..size = Vector2(16, 16);
+    world.addAll([
+      RectangleComponent()
+        ..size = Vector2(worldSizeX, worldSizeY)
+        ..setColor(Colors.lightGreen[800]!),
+      TextComponent(text: 'Use left thumbstick on your gamepad to move player')
+        ..position = Vector2(worldSizeX / 2, worldSizeY + 10)
+        ..scale = Vector2.all(0.7)
+        ..anchor = Anchor.topCenter,
+      player!,
+    ]);
+  }
+}
diff --git a/packages/flame_gamepads/example/lib/player_component.dart b/packages/flame_gamepads/example/lib/player_component.dart
@@ -0,0 +1,52 @@
+import 'dart:async';
+
+import 'package:flame/components.dart';
+import 'package:flame_gamepads/flame_callbacks.dart';
+import 'package:flutter/material.dart';
+import 'package:gamepads/gamepads.dart';
+
+class PlayerComponent extends RectangleComponent with GamepadCallbacks {
+  final double worldSizeX;
+  final double worldSizeY;
+
+  PlayerComponent({required this.worldSizeX, required this.worldSizeY});
+
+  double inputX = 0;
+  double inputY = 0;
+
+  static const deadZone = 0.15;
+  static const velocity = 150.0;
+
+  @override
+  FutureOr<void> onLoad() {
+    setColor(Colors.orange);
+    return super.onLoad();
+  }
+
+  @override
+  void update(double dt) {
+    super.update(dt);
+
+    if (inputX != 0.0) {
+      position.x = (position.x + inputX * dt * velocity).clamp(
+        0,
+        worldSizeX - size.x,
+      );
+    }
+    if (inputY != 0.0) {
+      position.y = (position.y - inputY * dt * velocity).clamp(
+        0,
+        worldSizeY - size.y,
+      );
+    }
+  }
+
+  @override
+  void onGamepadEvent(NormalizedGamepadEvent event) {
+    if (event.axis == GamepadAxis.leftStickX) {
+      inputX = event.value.abs() > deadZone ? event.value : 0.0;
+    } else if (event.axis == GamepadAxis.leftStickY) {
+      inputY = event.value.abs() > deadZone ? event.value : 0.0;
+    }
+  }
+}
diff --git a/packages/flame_gamepads/example/pubspec.yaml b/packages/flame_gamepads/example/pubspec.yaml
@@ -0,0 +1,20 @@
+name: flame_gamepads_example
+resolution: workspace
+description: Simple project to showcase the usage of flame_gamepads
+publish_to: 'none'
+version: 1.0.0+1
+
+environment:
+  sdk: ">=3.11.0 <4.0.0"
+
+dependencies:
+  flame: ^1.36.0
+  flame_gamepads: ^0.1.0
+  flutter:
+    sdk: flutter
+  gamepads: ^0.1.10
+
+dev_dependencies:
+  flame_lint: ^1.4.3
+flutter:
+  uses-material-design: true
diff --git a/packages/flame_gamepads/lib/flame_callbacks.dart b/packages/flame_gamepads/lib/flame_callbacks.dart
@@ -0,0 +1,3 @@
+library flame_gamepads;
+
+export 'src/gamepad_callbacks.dart';
diff --git a/packages/flame_gamepads/lib/src/gamepad_callbacks.dart b/packages/flame_gamepads/lib/src/gamepad_callbacks.dart
@@ -0,0 +1,33 @@
+import 'dart:async';
+
+import 'package:flame/components.dart';
+import 'package:flutter/material.dart';
+import 'package:gamepads/gamepads.dart';
+
+/// This mixin can be added to a [Component] allowing it to receive
+/// normalized gamepad events while the component is mounted.
+///
+/// If this is added to multiple components that are concurrently
+/// mounted, all of them will receive the event.
+mixin GamepadCallbacks on Component {
+  void onGamepadEvent(NormalizedGamepadEvent event) {}
+
+  final List<StreamSubscription> _subscriptions = [];
+
+  @override
+  @mustCallSuper
+  void onMount() {
+    super.onMount();
+    _subscriptions.add(Gamepads.normalizedEvents.listen(onGamepadEvent));
+  }
+
+  @override
+  @mustCallSuper
+  void onRemove() {
+    for (final subscription in _subscriptions) {
+      subscription.cancel();
+    }
+    _subscriptions.clear();
+    super.onRemove();
+  }
+}
diff --git a/packages/flame_gamepads/pubspec.yaml b/packages/flame_gamepads/pubspec.yaml
@@ -0,0 +1,30 @@
+name: flame_gamepads
+resolution: workspace
+description: Flame bindings to work with gamepads package
+version: 0.1.0
+homepage: https://github.com/flame-engine/flame/tree/main/packages/flame_gamepads
+funding:
+  - https://opencollective.com/blue-fire
+  - https://github.com/sponsors/bluefireteam
+  - https://patreon.com/bluefireoss
+topics:
+  - flame
+  - gamepads
+
+environment:
+  sdk: ">=3.11.0 <4.0.0"
+  flutter: ">=3.41.0"
+
+dependencies:
+  flame: ^1.36.0
+  flutter:
+    sdk: flutter
+  gamepads: ^0.1.10
+
+dev_dependencies:
+  dartdoc: ^9.0.0
+  flame_lint: ^1.4.3
+  flutter_test:
+    sdk: flutter
+  gamepads_platform_interface: any
+  test: any
diff --git a/packages/flame_gamepads/test/flame_gamepads_test.dart b/packages/flame_gamepads/test/flame_gamepads_test.dart
diff --git a/pubspec.yaml b/pubspec.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
++
 +## 0.1.0
++
 + - Add GamepadCallbacks mixin
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+include: package:flame_lint/analysis_options_with_dcm.yaml`