flame/doc/gesture-input.md

Gesture Input

This includes documentation for gesture inputs, which is, mouse and touch pointers.

For other input documents, see also:

• Keyboard Input: for keystrokes
• Other Inputs: For joysticks, game pads, etc.

Intro

Inside package:flame/gestures.dart you can find a whole set of mixins which can be included on your game class instance to be able to receive touch input events. Below you can see the full list of these mixins and its methods:

Touch and mouse detectors

- TapDetector
  - onTap
  - onTapCancel
  - onTapDown
  - onTapUp

- SecondaryTapDetector
  - onSecondaryTapDown
  - onSecondaryTapUp
  - onSecondaryTapCancel

- DoubleTapDetector
  - onDoubleTap

- LongPressDetector
  - onLongPress
  - onLongPressStart
  - onLongPressMoveUpdate
  - onLongPressUp
  - onLongPressEnd

- VerticalDragDetector
  - onVerticalDragDown
  - onVerticalDragStart
  - onVerticalDragUpdate
  - onVerticalDragEnd
  - onVerticalDragCancel

- HorizontalDragDetector
  - onHorizontalDragDown
  - onHorizontalDragStart
  - onHorizontalDragUpdate
  - onHorizontalDragEnd
  - onHorizontalDragCancel

- ForcePressDetector
  - onForcePressStart
  - onForcePressPeak
  - onForcePressUpdate
  - onForcePressEnd

- PanDetector
  - onPanDown
  - onPanStart
  - onPanUpdate
  - onPanEnd
  - onPanCancel

- ScaleDetector
  - onScaleStart
  - onScaleUpdate
  - onScaleEnd

 - MultiTouchTapDetector
  - onTap
  - onTapCancel
  - onTapDown
  - onTapUp

 - MultiTouchDragDetector
  - onReceiveDrag

Mouse only events

 - MouseMovementDetector
  - onMouseMove
 - ScrollDetector
  - onScroll

Many of these detectors can conflict with each other. For example, you can't register both vertical and horizontal drags, so not all of them can be used together.

It is also not possible to mix advanced detectors (MultiTouch*) with basic detectors as they will always win the gesture arena and the basic detectors will never be triggered. So for example, you can use both MultiTouchDragDetector and MultiTouchDragDetector together, but if you try to use MultiTouchTapDetector and PanDetector, no events will be triggered for the latter.

Flame's GestureApi is provided by Flutter's Gesture Widgets, including GestureDetector widget](https://api.flutter.dev/flutter/widgets/GestureDetector-class.html), RawGestureDetector widget and MouseRegion widget, you can also read more about Flutter's gestures here.

It is also possible to change the current mouse cursor displayed on the GameWidget region. To do so the following code can be used inside the Game class

mouseCursor.value = SystemMouseCursors.move;

To already initialize the GameWidget with a custom cursor, the mouseCursor property can be used

GameWidget(
  game: MouseCursorGame(),
  mouseCursor: SystemMouseCursors.move,
);

Event coordinate system

On events that have positions, like for example Tap* or Drag, you will notice that the eventPosition attribute includes 3 fields: game, widget and global. Below you will find a brief explanation about each one of them.

global

The position where the event occurred considering the entire screen, same as globalPosition in Flutter's native events.

widget

The position where the event occurred relative to the GameWidget position and size , same as localPosition in Flutter's native events.

game

The position where the event ocurred relative to the GameWidget and with any transformations that the game applied to the game (e.g. camera). If the game doesn't have any transformations, this will be equal to the widget attribute.

Example

class MyGame extends Game with TapDetector {
  // Other methods omitted

  @override
  void onTapDown(TapDownInfo event) {
    print("Player tap down on ${event.eventPosition.game}");
  }

  @override
  void onTapUp(TapUpInfo event) {
    print("Player tap up on ${event.eventPosition.game}");
  }
}

You can also check more complete examples here.

Tappable, Draggable and Hoverable components

Any component derived from BaseComponent (most components) can add the Tappable, the Draggable, and/or the Hoverable mixins to handle taps, drags and hovers on the component.

All overridden methods return a boolean to control if the event should be passed down further along to components underneath it. So say that you only want your top visible component to receive a tap and not the ones underneath it, then your onTapDown, onTapUp and onTapCancel implementations should return false and if you want the event to go through more of the components underneath then you should return true.

The same applies if your component has children, then the event is first sent to the leaves in the children tree and then passed further down until a method returns false.

Tappable components

By adding the HasTappableComponents mixin to your game, and using the mixin Tappable on your components, you can override the following methods on your components:

void onTapCancel() {}
void onTapDown(TapDownInfo event) {}
void onTapUp(TapUpInfo event) {}

Minimal component example:

import 'package:flame/components.dart';

class TappableComponent extends PositionComponent with Tappable {

  // update and render omitted

  @override
  void onTapUp(TapUpInfo event) {
    print("tap up");
  }

  @override
  void onTapDown(TapDownInfo event) {
    print("tap down");
  }

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

class MyGame extends BaseGame with HasTappableComponents {
  MyGame() {
    add(TappableComponent());
  }
}

Note: HasTappableComponents uses an advanced gesture detector under the hood and as explained further up on this page it shouldn't be used alongside basic detectors.

Draggable components

Just like with Tappable, Flame offers a mixin for Draggable.

By adding the HasDraggableComponents mixin to your game, and by using the mixin Draggable on your components, they can override the simple methods that enable an easy to use drag api on your components.

  void onDragStart(int pointerId, Vector2 startPosition) {}
  void onDragUpdate(int pointerId, DragUpdateInfo event) {}
  void onDragEnd(int pointerId, DragEndInfo event) {}
  void onDragCancel(int pointerId) {}

Note that all events take a uniquely generated pointer id so you can, if desired, distinguish between different simultaneous drags.

The default implementation provided by Draggable will already check:

• upon drag start, the component only receives the event if the position is within its bounds; keep track of pointerId.
• when handling updates/end/cancel, the component only receives the event if the pointerId was tracked (regardless of position).
• on end/cancel, stop tracking pointerId.

Minimal component example (this example ignores pointerId so it wont work well if you try to multi-drag):

import 'package:flame/components.dart';

class DraggableComponent extends PositionComponent with Draggable {

  // update and render omitted

  Vector2 dragDeltaPosition;
  bool get isDragging => dragDeltaPosition != null;

  @override
  bool onDragStart(int pointerId, Vector2 startPosition) {
    dragDeltaPosition = startPosition - position;
    return false;
  }

  @override
  bool onDragUpdate(int pointerId, DragUpdateInfo event) {
    final localCoords = event.eventPosition.game;
    position = localCoords - dragDeltaPosition;
    return false;
  }

  @override
  bool onDragEnd(int pointerId, DragEndInfo event) {
    dragDeltaPosition = null;
    return false;
  }

  @override
  bool onDragCancel(int pointerId) {
    dragDeltaPosition = null;
    return false;
  }
}

class MyGame extends BaseGame with HasDraggableComponents {
  MyGame() {
    add(DraggableComponent());
  }
}

Note: HasDraggableComponents uses an advanced gesture detector under the hood and as explained further up on this page, shouldn't be used alongside basic detectors.

Hoverable components

Just like the others, this mixin allows for easy wiring of your component to listen to hover states and events.

By adding the HasHoverableComponents mixin to your base game, and by using the mixin Hoverable on your components, they get an isHovered field and a couple of methods (onHoverStart, onHoverEnd) that you can override if you want to listen to the events.

  bool isHovered = false;
  void onHoverEnter(PointerHoverInfo event) {}
  void onHoverLeave(PointerHoverInfo event) {}

The provided event info is from the mouse move that triggered the action (entering or leaving). While the mouse movement is kept inside or outside, no events are fired and those mouse move events are not propagated. Only when the state is changed the handlers are triggered.

Hitbox

The Hitbox mixin is used to make detection of gestures on top of your PositionComponents more accurate. Say that you have a fairly round rock as a SpriteComponent for example, then you don't want to register input that is in the corner of the image where the rock is not displayed. Then you can use the Hitbox mixin to define a more accurate polygon for which the input should be within for the event to be counted on your component.

An example of you to use it can be seen here.