input.md

Input

In order to handle user input, you can use the libraries provided by Flutter for regular apps: Gesture Recognizers.

However, in order to bind them, use the Flame.util.addGestureRecognizer method; in doing so, you'll make sure they are properly unbound when the game widget is not being rendered, and so the rest of your screens will work appropriately.

For example, to add a tap listener ("on click"):

    Flame.util.addGestureRecognizer(new TapGestureRecognizer()
        ..onTapDown = (TapDownDetails evt) => game.handleInput(evt.globalPosition.dx, evt.globalPosition.dy));

Where game is a reference to your game object and handleInput is a method you create to handle the input inside your game.

If your game doesn't have other screens, just call this after your runApp call, in the main method.

Here are some example of more complex Gesture Recognizers:

    MyGame() {
        // other init...

        Flame.util.addGestureRecognizer(createDragRecognizer());
        Flame.util.addGestureRecognizer(createTapRecognizer());
    }

    GestureRecognizer createDragRecognizer() {
        return new ImmediateMultiDragGestureRecognizer()
            ..onStart = (Offset position) => this.handleDrag(position);
    }

    TapGestureRecognizer createTapRecognizer() {
        return new TapGestureRecognizer()
            ..onTapUp = (TapUpDetails details) => this.handleTap(details.globalPosition);;
    }

ATTENTION: Flame.util.addGestureRecognizer must be called after the runApp, otherwise Flutter's GestureBinding will not be initialized yet and exceptions will occur.

Tapable components

Flame also offers a simple helper to make it easier to handle tap events on PositionComponent, by using the mixin Tapable your components can override the following methods, enabling easy to use tap events on your Component.

  void onTapCancel() {}
  void onTapDown(TapDownDetails details) {}
  void onTapUp(TapUpDetails details) {}

Minimal component example:

import 'package:flame/components/component.dart';
import 'package:flame/components/events/gestures.dart';

class TapableComponent extends PositionComponent with Tapable {

  // update and render omitted

  @override
  void onTapUp(TapUpDetails details) {
    print("tap up");
  }

  @override
  void onTapDown(TapDownDetails details) {
    print("tap down");
  }

  @override
  void onTapCancel() {
    print("tap cancel");
  }
}