flame 0.18.2

  • Readme
  • Changelog
  • Example
  • Installing
  • 97

Pub Build Status - Travis Discord

🔥 flame #

A minimalist Flutter game engine.

Any help is appreciated! Comment, suggestions, issues, PR's! Give us a star to help!

Help #

We have a Flame help channel on Fireslime's Discord, join it here. Also we now have a FAQ, so please search your questions there first.

Goals #

The goal of this project is to provided a complete set of out-of-the-way solutions for the common problems every game developed in Flutter will share.

Currently it provides you with: a few utilities, images/sprites/sprite sheets, audio, a game loop and a component/object system.

You can use whatever ones you want, as they are all somewhat independent.

Support #

Support us by becoming a patron on Patreon


Or making a single donation buying us a coffee:

Buy Me A Coffee

You can also show support by showing on your repository that your game is made with Flame by using one of the following badges:

Powered by Flame Powered by Flame Powered by Flame

[![Powered by Flame](https://img.shields.io/badge/Powered%20by-%F0%9F%94%A5-orange.svg)](https://flame-engine.org)
[![Powered by Flame](https://img.shields.io/badge/Powered%20by-%F0%9F%94%A5-orange.svg?style=flat-square)](https://flame-engine.org)
[![Powered by Flame](https://img.shields.io/badge/Powered%20by-%F0%9F%94%A5-orange.svg?style=for-the-badge)](https://flame-engine.org)

Contributing #

Found a bug on Flame and want to contribute with a PR? PRs are always very welcome, just be sure to create your PR from the develop branch.

External Modules #

Flame is modular, and you can always pick and choose. Some modules are extracted to separate plugins; some are bundled with flame, and some must be added separately.

  • audioplayers is the audio engine behind flame. It's included.

  • tiled adds support for parsing and using TMX files from Tiled. It's included.

  • box2d adds wrappers over Box2D for the physics engine. It's included.

  • flame_gamepad adds support to gamepad. Android only. It's not included, add to your pubspec as desired.

  • play_games integrates to Google Play Games Services (GPGS). Adds login, achievements, saved games and leaderboard. Android only. It's not included, add to your pubspec as desired. Be sure to check the instructions on how to configure, as it's not trivial.

Usage #

Just drop it in your pubspec.yaml:

  flame: ^0.18.2

And start using it!


We strive to keep Flame working on the Flutter's stable channel, currently on version v1.7.8+hotfix.2, be sure to check which channel are you using if you encounter any trouble.

Documentation #

The complete documentation can be found here.

A very cool docs site can be found here.

Getting started #

Check out this great series of articles/tutorials written by Alekhin

We also offer a curated list of Games, Libraries and Articles over at awesome-flame.

Structure #

The only structure you are required to comply is a assets folder with two sub folders: audio and images.

An example:



The file structure would have to be:

└── assets
    ├── audio
    │   └── explosion.mp3
    └── images
        ├── enemy.png
        └── player.png

Don't forget to add these files to your pubspec.yaml file:

    - assets/audio/explosion.mp3
    - assets/images/player.png
    - assets/images/enemy.png

Modules #

The modular approach allows you to use any of these modules independently, or together, or as you wish.

Audio #

To play an audio, just use the Flame.audio.play method:

    import 'package:flame/flame.dart';


You can pre-load your audios in the beginning and avoid delays with the loadAll method:

    // in a async prepare function for your game
    await Flame.audio.loadAll(['explosion.mp3']);

Complete Audio Guide

Looping Background Music Guide

Images #

If you are using the Component module and doing something simple, you probably won't need to use these classes; use SpriteComponent or AnimationComponent instead.

If you want to load an image and render it on the Canvas, you can use the Sprite class:

    import 'package:flame/sprite.dart';

    Sprite sprite = Sprite('player.png');

    // in your render loop
    sprite.render(canvas, width, height);

Note that the render method will do nothing while the image has not been loaded; you can check for completion using the loaded method.

Complete Images Guide

Component #

This class represent a single object on the screen, being a floating rectangle or a rotating sprite.

The base abstract class has the common expected methods update and render to be implemented.

The intermediate inheritance PositionComponent adds x, y, width, height and angle to your Components, as well as some useful methods like distance and angleBetween.

The most commonly used implementation, SpriteComponent, can be created with a Sprite:

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

    // on your constructor or init logic
    Sprite sprite = Sprite('player.png');

    const size = 128.0;
    final player = SpriteComponent.fromSprite(size, size, sprite); // width, height, sprite

    // screen coordinates
    player.x = ... // 0 by default
    player.y = ... // 0 by default
    player.angle = ... // 0 by default

    // on your render method...
    player.render(canvas); // it will render only if the image is loaded and the x, y, width and height parameters are not null

Every Component has a few other methods that you can optionally implement, that are used by the BaseGame class. If you are not using the base game, you can alternatively use these methods on your own game loop.

The resize method is called whenever the screen is resized, and in the beginning once when the component is added via the add method. You need to apply here any changes to the x, y, width and height of your component, or any other changes, due to the screen resizing. You can start these variables here, as the sprite won't be rendered until everything is set.

The destroy method can be implemented to return true and warn the BaseGame that your object is marked for destruction, and it will be remove after the current update loop. It will then no longer be rendered or updated.

The isHUD method can be implemented to return true (default false) to make the BaseGame ignore the camera for this element.

There are also other implementations:

  • The AnimationComponent takes an Animation object and renders a cyclic animated sprite (more details about Animations here)
  • The ParallaxComponent can render a parallax background with several frames
  • The Box2DComponent, that has a physics engine built-in (using the Box2D port for Dart)

Complete Components Guide

Game Loop #

The Game Loop module is a simple abstraction over the game loop concept. Basically most games are built upon two methods:

  • The render method takes the canvas ready for drawing the current state of the game.
  • The update method receives the delta time in milliseconds since last update and allows you to move the next state.

The class Game can be subclassed and will provide both these methods for you to implement. In return it will provide you with a widget property that returns the game widget, that can be rendered in your app.

You can either render it directly in your runApp, or you can have a bigger structure, with routing, other screens and menus for your game.

To start, just add your game widget directly to your runApp, like so:

    main() {
        Game game = MyGameImpl();

Instead of implementing the low level Game class, you should probably use the more full-featured BaseGame class.

The BaseGame implements a Component based Game for you; basically it has a list of Components and repasses the update and render calls appropriately. You can still extend those methods to add custom behavior, and you will get a few other features for free, like the repassing of resize methods (every time the screen is resized the information will be passed to the resize methods of all your components) and also a basic camera feature (that will translate all your non-HUD components in order to center in the camera you specified).

A very simple BaseGame implementation example can be seen below:

    class MyCrate extends SpriteComponent {

        // creates a component that renders the crate.png sprite, with size 16 x 16
        MyCrate() : SpriteComponent.fromSprite(16.0, 16.0, new Sprite('crate.png'));

        void resize(Size size) {
            // we don't need to set the x and y in the constructor, we can set then here
            this.x = (size.width - this.width)/ 2;
            this.y = (size.height - this.height) / 2;

    class MyGame extends BaseGame {
        MyGame() {
            add(new MyCrate()); // this will call resize the first time as well

Input #

Inside package:flame/gestures.dart you can find a whole set of mixin which can be included on your game class instance to be able to receive touch input events


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

  void onTapDown(TapDownDetails details) {
    print("Player tap down on ${details.globalPosition.dx} - ${details.globalPosition.dy}");

  void onTapUp(TapUpDetails details) {
    print("Player tap up on ${details.globalPosition.dx} - ${details.globalPosition.dy}");

Complete Input Guide

Credits #

  • All the friendly contributors and people who are helping in the community.
  • My own audioplayers lib, which in turn is forked from rxlabz's.
  • The Dart port of Box2D.
  • inu-no-policemen's post on reddit, which helped me a lot with the basics
  • Everyone who answered my beginner's questions on Stack Overflow

0.18.2 #

  • Add loop for AnimationComponent.sequenced() (thanks @wenxiangjiang)
  • TextComponent optimization (thanks @Gericop)
  • Adding Component#onMount
  • Check if chidren are loaded before rendering on ComposedComponent (thanks @wenxiangjiang)
  • Amend type for width and height properties on Animation.sequenced (thanks @wenxiangjiang)
  • Fixing Tapable position checking
  • Support line feed when create animation from a single image source (thanks @wenxiangjiang)
  • Fixing TextBoxComponent start/end of line bugs (thanks @kurtome)
  • Prevent widgets overlay controller from closing when in debug mode

0.18.1 #

  • Expose stepTime paramter from the Animation class to the animation component
  • Updated versions for bugfixes + improved macOS support. (thanks @flowhorn)
  • Update flutter_svg to 0.17.1 (thanks @flowhorn)
  • Update audioplayers to 0.14.0 (thanks @flowhorn)
  • Update path_provider to 1.6.0 (thanks @flowhorn)
  • Update ordered_set to 1.1.5 (thanks @flowhorn)

0.18.0 #

  • Improving FlareComponent API and updating FlareFlutter dependency
  • Adding HasWidgetsOverlay mixin
  • Adding NineTileBox widget

0.17.4 #

  • Fixing compilations errors regarding changes on box2_flame
  • Add splash screen docs

0.17.3 #

  • Tweaking text box rendering to reduce pixelated text (thanks, @kurtome)
  • Adding NineTileBox component

0.17.2 #

  • Added backgroundColor method for overriding the game background (thanks @wolfenrain)
  • Update AudioPlayers version to 0.13.5
  • Bump SVG dependency plus fix example app

0.17.1 #

  • Added default render function for Box2D ChainShape
  • Adding TimerComponent
  • Added particles subsystem (thanks @av)

0.17.0 #

  • Fixing FlareAnimation API to match convention
  • Fixing FlareComponent renderization
  • New GestureDetector API to Game

0.16.1 #

  • Added Bgm class for easy looping background music management.
  • Added options for flip rendering of PositionComponents easily (horizontal and vertical).

0.16.0 #

  • Improve our mixin structure (breaking change)
  • Adds HasGameRef mixin
  • Fixes for ComposedComponent (for tapables and other apis using preAdd)
  • Added no-parameter alias functions for setting the game's orientation.
  • Prevent double completion on onMetricsChanged callback

0.15.2 #

  • Exposing tile objects on TiledComponent (thanks @renatoferreira656)
  • Adding integrated API for taps on Game class and adding Tapeables mixin for PositionComponents

0.15.1 #

  • Bumped version of svg dependency
  • Fixed warnings

0.15.0 #

  • Refactoring ParallaxComponent (thanks @spydon)
  • Fixing flare animation with embed images
  • Adding override paint parameter to Sprite, and refactoring it have named optional parameters

0.14.2 #

  • Refactoring BaseGame debugMode
  • Adding SpriteSheet class
  • Adding Flame.util.spriteAsWidget
  • Fixing AnimationComponent.empty()
  • Fixing FlameAudio.loopLongAudio

0.14.1 #

  • Fixed build on travis
  • Updated readme badges
  • Fixed changelog
  • Fixed warning on audiopool, added audiopool example in docs

0.14.0 #

  • Adding Timer#isRunning method
  • Adding Timer#progress getter
  • Updating Flame to work with Flutter >= 1.6.0

0.13.1 #

  • Adding Timer utility class
  • Adding destroyOnFinish flag for AnimationComponent
  • Fixing release mode on examples that needed screen size
  • Bumping dependencies versions (audioplayers and path_provider)

0.13.0 #

  • Downgrading flame support to stable channel.

0.12.2 #

  • Added more functionality to the Position class (thanks, @illiapoplawski)

0.12.1 #

  • Fixed PositionComponent#setByRect to comply with toRect (thanks, @illiapoplawski)

0.12.0 #

  • Updating flutter_svg and pubspec to support the latest flutter version (1.6.0)
  • Adding Flare Support
  • Fixing PositionComponent#toRect which was not considering the anchor property (thanks, @illiapoplawski)

[0.11.2] #

  • Fixed bug on animatons with a single frame
  • Fixed warning on using specific version o flutter_svg on pubspec
  • ParallaxComponent is not abstract anymore, as it does not include any abstract method
  • Added some functionality to Position class

[0.11.1] #

  • Fixed lack of paint update when using AnimationAsWidget as pointed in #78
  • Added travis (thanks, @renancarujo)

[0.11.0] #

  • Implementing low latency api from audioplayers (breaking change)
  • Improved examples by adding some instructions on how to run
  • Add notice on readme about the channel
  • Upgrade path_provider to fix conflicts

[0.10.4] #

  • Fix breaking change on svg plugin

[0.10.3] #

  • Svg support
  • Adding Animation#reversed allowing a new reversed animation to be created from an existing animation.
  • Fix games inside regular apps when the component is inside a sliver
  • Support asesprite animations

[0.10.2] #

  • Fixed some warnings and formatting

[0.10.1] #

  • Fixes some typos
  • Improved docs
  • Extracted gamepads to a new lib, lots of improvements there (thanks, @erickzanardo)
  • Added more examples and an article

[0.10.0] #

  • Fixing a few minor bugs, typos, improving docs
  • Adding the Palette concept: easy access to white and black colors/paints, create your palette to keep your game organized.
  • Adding the Anchor concept: specify where thins should anchor, added to PositionComponent and to the new text releated features.
  • Added a whole bunch of text related components: TextConfig allows you to easily define your typography information, TextComponent allows for easy rendering of stuff and TextBox can make sized texts and also typing effects.
  • Improved Utils to have better and more concise APIs, removed unused stuff.
  • Adding TiledComponent to integrate with tiled

[0.9.5] #

  • Add elapsed property to Animation (thanks, @ianliu)
  • Fixed minor typo on documentation

[0.9.4] #

  • Bumps audioplayers version

[0.9.3] #

  • Fixes issue when switching between games where new game would not attach

[0.9.2] #

  • Fixes to work with Dart 2.1

[0.9.1] #

  • Updated audioplayers and box2d to fix bugs

[0.9.0] #

  • Several API changes, using new audioplayers 0.6.x

[0.8.4] #

  • Added more consistent APIs and tests

[0.8.3] #

  • Need to review audioplayers 0.5.x

[0.8.2] #

  • Added better documentation, tutorials and examples
  • Minor tweaks in the API
  • New audioplayers version

[0.8.1] #

  • The Components Overhaul Update: This is major update, even though we are keeping things in alpha (version 0.*)
  • Several major upgrades regarding the component system, new component types, Sprites and SpriteSheets, better image caching, several improvements with structure, a BaseGame, a new Game as a widget, that allows you to embed inside apps and a stop method. More minor changes.

[0.6.1] #

  • Bump required dart version

[0.6.0] #

  • Adding audio suport for iOS (bumping audioplayers version)

[0.5.0] #

  • Adding a text method to Util to more easily render a Paragraph

[0.4.0] #

  • Upgraded AudioPlayers, added method to disable logging
  • Created PositionComponent with some useful methods
  • A few refactorings

[0.3.0] #

  • Added a pre-load method for Audio module

[0.2.0] #

  • Added a loop method for playing audio on loop
  • Added the option to make rectangular SpriteComponents, not just squares

[0.1.0] #

  • First release, basic utilities


import 'dart:math' as math;
import 'dart:ui';

import 'package:flame/anchor.dart';
import 'package:flame/components/component.dart';
import 'package:flame/components/mixins/has_game_ref.dart';
import 'package:flame/game.dart';
import 'package:flame/palette.dart';
import 'package:flutter/material.dart';

void main() => runApp(MyGame().widget);

class Palette {
  static const PaletteEntry white = BasicPalette.white;
  static const PaletteEntry red = PaletteEntry(Color(0xFFFF0000));
  static const PaletteEntry blue = PaletteEntry(Color(0xFF0000FF));

class Square extends PositionComponent with HasGameRef<MyGame> {
  static const SPEED = 0.25;

  void resize(Size size) {
    x = size.width / 2;
    y = size.height / 2;

  void render(Canvas c) {

    c.drawRect(Rect.fromLTWH(0, 0, width, height), Palette.white.paint);
    c.drawRect(const Rect.fromLTWH(0, 0, 3, 3), Palette.red.paint);
    c.drawRect(Rect.fromLTWH(width / 2, height / 2, 3, 3), Palette.blue.paint);

  void update(double t) {
    angle += SPEED * t;
    angle %= 2 * math.pi;

  void onMount() {
    width = height = gameRef.squareSize;
    anchor = Anchor.center;

class MyGame extends BaseGame {
  final double squareSize = 128;

  MyGame() {

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  flame: ^0.18.2

2. Install it

You can install packages from the command line:

with Flutter:

$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:flame/flame.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Mar 31, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.6
  • Flutter: 1.12.13+hotfix.8

Health suggestions

Fix lib/game/game.dart. (-0.50 points)

Analysis of lib/game/game.dart reported 1 hint:

line 90 col 41: Close instances of dart.core.Sink.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.3.0 <3.0.0
audioplayers ^0.14.0 0.14.2 0.15.0-beta.1
box2d_flame ^0.4.5 0.4.5
convert ^2.0.1 2.1.1
flare_flutter ^2.0.1 2.0.1
flutter 0.0.0
flutter_svg ^0.17.1 0.17.3+1
meta ^1.1.8 1.1.8
ordered_set ^1.1.5 1.1.5
path_provider ^1.6.0 1.6.5
synchronized ^2.1.0 2.2.0
tiled ^0.2.1 0.2.1
Transitive dependencies
archive 2.0.13
args 1.6.0
charcode 1.1.3
collection 1.14.11 1.14.12
crypto 2.1.4
flare_dart 2.3.3
flutter_web_plugins 0.0.0
path 1.6.4
path_drawing 0.4.1
path_parsing 0.1.4
path_provider_macos 0.0.4
path_provider_platform_interface 1.0.1
petitparser 3.0.2
platform 2.2.1
plugin_platform_interface 1.0.2
sky_engine 0.0.99
typed_data 1.1.6
uuid 2.0.4
vector_math 2.0.8
xml 3.7.0 4.1.0
Dev dependencies
test ^1.9.4