Your First Flutter Flame Game

When a player interacts with any game, they perform input events that the game interpretes and responds to accordingly.

Now, in a mobile device, you can have multiple inputs like:

• tilting the phone
• tapping the screen
• voice commands

Flame provides a set of built-in input handlers and helpers for you to choose from:

• Drag Events: for dragging gestures.
• Tap Events: for tapping or longpressing.
• Gesture Input: for customized or complex gestures.
• Keyboard Input: for software and hardware keyboards.
• Gamepad: via additional package flame_gamepad.

Flame’s got two different APIs for gesture handling: one based on gesture detectors which is referred to as Gesture Input and another one based on events, also called Events API.

Most of the time, if you just want to detect input on your components you are better off using the Events API. On the other hand, if you require complex or custom gesture handling, you’ll need to rely on Gesture Input API.

Now, Flame’s event API is based on mixins. Mixins provide a way for another class to inherit a certain behavior without using multiple inheritances. Here’s some of the most used ones:

TapCallbacks mixin is applicable to any Component, enabling the component to respond to tap events. This mixin introduces the methods onTapDown, onLongTapDown, onTapUp, and onTapCancel to the component. By default, these methods do nothing, providing flexibility for customization based on specific needs. It is not mandatory to override all of them; for instance, overriding onTapUp alone allows selective response to real taps.

DragCallbacks mixin helps you detect drag events. Drag events take place when the user glides their finger across the device screen or moves the mouse while keeping its button depressed. This mixin adds four methods to your component: onDragStart, onDragUpdate, onDragEnd, and onDragCancel. By default, these methods do nothing – you’ll need to override them in order to perform any function.

DoubleTapCallbacks mixin allows the component to capture double-tap events. To enable double tap event handling in a component, simply include the DoubleTapCallbacks mixin in your PositionComponent.

All of these mixins exclusively capture tap events that occur within the boundaries of the Component. The widely-used PositionComponent class comes with a built-in implementation that leverages its size property to determine the boundaries. If your component is derived directly from the basic Component class, you’ll have to manually implement containsLocalPoint() and define the spatial boundaries within which tap events will be recognized.

Demo

MeteormaniaGame

Let’s add a couple of mixins to MeteormaniaGame

with TapCallbacks, DragCallbacks

TapCallbacks allows you to look for tap events in the game, while DragCallbacks does the same except it looks for dragging events (like rotating or swiping left or right).

Let’s override onTapUp and print to the console for now.

@override
void onTapUp(TapUpEvent event) {
  print('Tap!');
}

This function gets called each time the player taps on the sreen. It’ll be used for shooting in the future.

HasCollisionCallbacks calls onDragUpdate whenever the user long presses the screen, for example in a swipe motion.

@override
void onDragUpdate(DragUpdateEvent event) {
  print('Drag! ${event.delta}');
}

Build and run the game. Tap or drag the screen to make sure your callbacks are getting the user input events appropiately.