Flame is a free 2D game engine for Flutter. Run flutter pub add flame and you get a game loop, game objects called components, a camera, touch and keyboard input, collision detection and sprite animation. It runs on Android, iOS, web and desktop from one codebase.
This guide is for Flutter developers and hobby game makers who want to start a first game. It uses flame 1.38.2, the latest stable version on pub.dev in October 2026.
In short:
- Flame is MIT licensed and has the Flutter Favorite badge.
- Use it when the game keeps moving on its own. Use plain widgets for turn-based games.
- Put game objects in
world, not straight into the game, so the camera shows them. - Old tutorials use mixins that are deprecated now.
Use Flame when the world keeps moving
Flutter's Casual Games Toolkit splits casual games in two. Turn-based games, such as cards and puzzles, "are well suited for Flutter" as it is. Real-time games "could use an open source game engine like the Flame game engine".
The test is simple: does the world keep moving while the player watches? If yes, use Flame. If it only changes when the player acts, use widgets.
| Your game | Build it with |
|---|---|
| Brick breaker, platformer, shooter, runner, snake | Flame |
| Tic-tac-toe, memory cards, quiz, sudoku | Plain Flutter widgets |
| Pieces that keep sliding after you let go | Widgets first, Flame if you need physics |
| A drawing pad | CustomPainter |
A hand-made loop with a Ticker and a CustomPainter works for a demo. It breaks down once you need hitboxes, a camera and touches that know which object was hit. Flame already has those.
Install with one command
flutter pub add flame
Put images in assets/images/ and sounds in assets/audio/, and list both folders under flutter: assets: in pubspec.yaml. Flame's assets structure page shows the layout. Version 1.38.2 needs Flutter 3.41 or newer.
Four ideas carry every Flame game
The game loop. A game is two methods called every frame. update(double dt) changes state, and render(Canvas canvas) draws it. dt is the seconds since the last frame.
Multiply speed by dt. x += 120 * dt means 120 pixels per second on any phone.
Components. Everything is a Component, and components form a tree like Flutter's widgets. A parent updates and draws its children. Most visible things extend PositionComponent, which adds position, size, angle and anchor. The components page covers the lifecycle.
FlameGame, World and camera. FlameGame is the root. It owns a World that holds your objects and a CameraComponent that looks at it. By default the camera puts world position (0, 0) in the middle of the screen. See components, worlds and cameras.
GameWidget. This is the bridge to Flutter. It is an ordinary widget, so menus and settings around the game are ordinary Flutter. Inside a build method use GameWidget.controlled(gameFactory: MyGame.new). Flame's docs warn that a game created in build is rebuilt whenever the tree rebuilds.
Behaviour comes from mixins: TapCallbacks and DragCallbacks for touch, CollisionCallbacks for hits, HasGameReference<MyGame> for a typed game field.
A spinning square is already a game
This whole program shows a square spinning in the middle of the screen. It needs no images.
import 'package:flame/components.dart';
import 'package:flame/game.dart';
import 'package:flutter/material.dart';
void main() => runApp(GameWidget(game: FlameGame(world: MyWorld())));
class MyWorld extends World {
@override
Future<void> onLoad() async => add(Spinner());
}
class Spinner extends RectangleComponent {
Spinner() : super(size: Vector2.all(80), anchor: Anchor.center,
paint: Paint()..color = Colors.cyan);
@override
void update(double dt) => angle += dt;
}
onLoad runs once. Anchor.center makes the position the square's centre, so it spins around itself at the origin. angle += dt turns one radian per second on every device.
Add-on packages bring audio, physics and maps
The core package also has sprites, effects, particles, text, a router and a joystick. Heavier features are separate packages. Versions below are the latest stable on pub.dev in October 2026.
| Package | Version | Adds |
|---|---|---|
| flame_audio | 2.12.2 | Sound effects and music |
| flame_forge2d | 0.20.0 | Rigid-body physics |
| flame_tiled | 3.1.2 | Maps from the Tiled editor |
| flame_rive | 1.11.2 | Rive animations |
| bonfire | 4.0.0 | RPG-style games on Flame |
Bonfire has a different publisher from the others, and its pub.dev page does not list web. flame_forge2d 0.20.0 changed its API and needs Dart 3.12, so older Forge2D tutorials may not compile. Read physics with Forge2D before you start.
Old tutorials use deprecated code
Many Flame tutorials online were written for early 1.x versions. These four changes trip up most of them. Two APIs are deprecated, and two old habits still compile but give worse results.
| Old tutorial says | Write now |
|---|---|
TapDetector on the game |
TapCallbacks on the component |
HasGameRef and gameRef |
HasGameReference<MyGame> and game |
add(component) on the game |
world.add(component) |
onCollision for a hit |
onCollisionStart, once per contact |
Flame's own source marks TapDetector as "Use TapCallbacks instead". When code will not compile, check the tutorial's date first.
GrowApps builds 2D games on Flame
GrowApps makes real Flutter apps from a chat. Its builder is instructed to build any 2D game, such as a brick breaker, platformer, tapper or shooter, on the flame package and never on a hand-written loop. Turn-based games stay plain widgets.
The builder starts from a tested brick-breaker game and adds a music loop. You get a normal Flutter project. See making a Flame game from a prompt or try GrowApps.
Build the dodge game next
Create a Flutter project, add Flame, and paste the spinner above. Then follow your first Flame game: you drag a square and dodge falling rocks, with collisions and a restart.
Frequently asked questions
Does Flame run on the web and on phones?
Yes. Flame's docs list web, Android, iOS, Windows, macOS and Linux. A few device calls, such as setting orientation, do nothing on the web.
Can Flame make 3D games?
Not with the core engine. Flame is a 2D engine, and the separate flame_3d package is still experimental. For a 3D game, pick a dedicated 3D engine.