If you already know Flutter, you are closer to shipping your first game than you think. Flame is a 2D game engine built directly on top of Flutter’s own rendering and widget system, which means there is no new language to learn and no separate editor to install – you write Dart, you use your existing IDE, and your game runs on every platform Flutter already supports (Android, iOS, web, and desktop) from a single codebase.
In this guide we will set up a Flame project from scratch and build a small moving box you can control with the keyboard – no sprite images required, so you can focus on understanding how Flame’s game loop actually works before you add art.
Why Flame instead of Unity or Godot?
Unity and Godot are full dedicated game engines, and they are the better choice once you need 3D, a large asset pipeline, or a dedicated visual editor. Flame is the right tool for a specific, common case: you are a Flutter developer (or want to become one), and you want to build casual 2D games – puzzle games, endless runners, simple arcade games – that can share code, state management, and UI widgets with a normal Flutter app. If you’re coming from this site’s Flutter tutorials, Flame is the shortest path from “I know Flutter” to “I shipped a playable game.”
Step 1: Add Flame to a Flutter project
Start with a normal Flutter project (flutter create my_game), then add the Flame package to pubspec.yaml:
dependencies:
flutter:
sdk: flutter
flame: ^1.18.0
Run flutter pub get, and you’re ready to write your first game class.
Step 2: The game class and the game loop
Every Flame game starts with a class that extends FlameGame. This class is the root of your component tree – every object in your game (the player, enemies, the background) gets added to it as a component.
import 'package:flame/game.dart';
import 'package:flutter/material.dart';
void main() {
final game = BoxRunnerGame();
runApp(GameWidget(game: game));
}
class BoxRunnerGame extends FlameGame {
@override
Future onLoad() async {
await add(PlayerBox());
}
}
onLoad() runs once, before the first frame, which makes it the right place to add your starting components. GameWidget is a normal Flutter widget, so you can drop it anywhere in a widget tree – inside a Scaffold, next to a score display, behind a pause menu overlay, exactly like any other widget.
Step 3: A component with no sprite required
Most Flame tutorials start by asking you to find or draw a sprite image. We’ll skip that for now and use RectangleComponent, which draws a plain colored rectangle – perfect for learning movement and the update loop before you touch art assets.
import 'package:flame/components.dart';
import 'package:flutter/material.dart';
class PlayerBox extends RectangleComponent {
final Vector2 velocity = Vector2.zero();
static const double speed = 200;
PlayerBox()
: super(
size: Vector2.all(48),
position: Vector2(100, 100),
paint: Paint()..color = Colors.greenAccent,
);
@override
void update(double dt) {
super.update(dt);
position += velocity * speed * dt;
}
}
The important line is position += velocity * speed * dt. dt is the time, in seconds, since the last frame. Multiplying by dt instead of moving a fixed number of pixels per frame is what makes the box move at the same real-world speed whether the game is running at 30fps or 120fps – this is the single most common bug in a first game engine attempt, so it’s worth understanding from day one rather than fixing later.
Step 4: Reading keyboard input
To move the box with the arrow keys, add the KeyboardEvents mixin to the game class and override onKeyEvent:
import 'package:flutter/services.dart';
import 'package:flame/game.dart';
import 'package:flame/events.dart';
class BoxRunnerGame extends FlameGame with KeyboardEvents {
late final PlayerBox player;
@override
Future onLoad() async {
player = PlayerBox();
await add(player);
}
@override
KeyEventResult onKeyEvent(
KeyEvent event,
Set keysPressed,
) {
final dx = (keysPressed.contains(LogicalKeyboardKey.arrowRight) ? 1 : 0) -
(keysPressed.contains(LogicalKeyboardKey.arrowLeft) ? 1 : 0);
final dy = (keysPressed.contains(LogicalKeyboardKey.arrowDown) ? 1 : 0) -
(keysPressed.contains(LogicalKeyboardKey.arrowUp) ? 1 : 0);
player.velocity.setValues(dx.toDouble(), dy.toDouble());
if (player.velocity.length2 > 0) {
player.velocity.normalize();
}
return KeyEventResult.handled;
}
}
Returning KeyEventResult.handled tells Flutter the key press was consumed – skip this and you’ll get an audible system-sound complaint on desktop every time a key is pressed. normalize() keeps diagonal movement (holding two arrow keys at once) from being faster than straight movement, since a normalized diagonal vector has the same length as a horizontal or vertical one.
That’s a complete, working game loop: input, state (position and velocity), and a render step Flame handles for you automatically every frame.
Where to go from here
From this starting point, the next steps are: load an actual sprite with SpriteComponent and Sprite.load() instead of a plain rectangle, add HasCollisionDetection to the game and a RectangleHitbox to the player so it can detect hitting obstacles, and add a TextComponent for a score display. Each of those is its own focused tutorial on this site – this page will link out to them as they go live, so bookmark the Game Development Guide and check back.
Common mistakes beginners make with Flame
- Moving by a fixed amount instead of
velocity * dt. This is the one bug above, but it’s worth repeating: withoutdt, your game runs at different speeds on different devices depending on their frame rate. - Forgetting
awaitonadd()insideonLoad().add()returns a future that completes once the component has finished loading (including any asset loading inside its ownonLoad). Skippingawaitusually still works for a plainRectangleComponent, but will cause a component with a sprite to briefly render before its image is ready. - Putting game logic inside
build()methods. Flame components already have their own lifecycle (onLoad,update,render) that runs independently of Flutter’s widget rebuilds. Mixing the two models – for example, callingsetState()every frame to move something – defeats the performance benefit of using a game engine in the first place and will visibly stutter. - Not disposing of input listeners or timers. If a component adds its own
Timeror external stream subscription inonLoad, cancel it inonRemove; otherwise it keeps firing after the component (and its game) is gone, which shows up as confusing crashes much later.
Frequently asked questions
Is Flutter Flame good enough for a real, published game?
Yes, for 2D casual and mid-core games. Flame handles the same rendering pipeline Flutter itself uses, so performance is comparable to a native Flutter app – fine for platformers, puzzle games, card games, and endless runners. It is not the right choice for 3D games or AAA-scale production values; that’s where Unity or a dedicated 3D engine wins.
Do I need to know Flutter before learning Flame?
Basic Flutter and Dart knowledge (widgets, async/await, classes) makes this much easier, since Flame reuses Dart’s syntax and some Flutter concepts (like the widget tree) directly. If you’re brand new to Flutter, work through a few widget tutorials first – see the Flutter Widgets Guide on this site – then come back to Flame.
Can a Flame game run on the web and desktop, not just mobile?
Yes – this is one of Flame’s biggest advantages over picking a mobile-only game framework. Since it’s built on Flutter, the exact same game code compiles to Android, iOS, web, Windows, macOS, and Linux, with only minor adjustments for things like touch versus mouse/keyboard input.