Getting Started¶

About Flame¶

Flame is a modular Flutter game engine that provides a complete set of out-of-the-way solutions for games. It takes advantage of the powerful infrastructure provided by Flutter but simplifies the code you need to build your projects.

It provides you with a simple yet effective game loop implementation, and the necessary functionalities that you might need in a game. For instance; input, images, sprites, sprite sheets, animations, collision detection, and a component system that we call Flame Component System (FCS for short).

We also provide stand-alone packages that extend the Flame functionality which can be found in the Bridge Packages section.

You can pick and choose whichever parts you want, as they are all independent and modular.

The engine and its ecosystem are constantly being improved by the community, so please feel free to reach out, open issues and PRs as well as make suggestions.

Give us a star if you want to help give the engine exposure and grow the community. :)

Installation¶

Add the flame package as a dependency in your pubspec.yaml by running the following command:

flutter pub add flame

The latest version can be found on pub.dev.

then run flutter pub get and you are ready to start using it!

Getting started¶

There is a set of tutorials that you can follow to get started in the tutorials folder.

Simple examples for all features can be found in the examples folder.

To run Flame you need use the GameWidget, which is just another widget that can live anywhere in your widget tree. You can use it as the root widget of your app, or as a child of another widget.

Here is a simple example of how to use the GameWidget:

import 'package:flame/game.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(
    GameWidget(
      game: FlameGame(),
    ),
  );
}

In Flame we provide a concept called the Flame Component System (FCS), which is a way to organize your game objects in a way that makes it easy to manage them. You can read more about it in the Components section.

When you want to start a new game you either have to extend the FlameGame class or the World class. The FlameGame is the root of your game and is responsible for managing the game loop and the components. The World class is a component that can be used to create a world in your game.

So to create a simple game you can do something like this:

import 'package:flame/game.dart';
import 'package:flame/components.dart';
import 'package:flutter/widgets.dart';

void main() {
  runApp(
    GameWidget(
      game: FlameGame(world: MyWorld()),
    ),
  );
}

class MyWorld extends World {
  @override
  Future<void> onLoad() async {
    add(Player(position: Vector2(0, 0)));
  }
}

As you can see, we have created a MyWorld class that extends the World class. We have overridden the onLoad method to add a Player component (which doesn’t exist yet) to the world. In the FlameGame class we by default have a camera that is watching the world, and by default it is looking at the (0, 0) position of the world in the center of the screen, to learn more about the camera and the world you can read the Camera Component section.

The Player component can be whatever type of component that you want, to get started we recommend to use the SpriteComponent class, which is a component that can render a sprite (image) on the screen.

For example something like this:

import 'package:flame/components.dart';
import 'package:flame/geometry.dart';
import 'package:flame/extensions.dart';

class Player extends SpriteComponent {
  Player({super.position}) :
    super(size: Vector2.all(200), anchor: Anchor.center);

  @override
  Future<void> onLoad() async {
    sprite = await Sprite.load('player.png');
  }
}

In this example, we have created a Player class that extends the SpriteComponent class. We have overridden the onLoad method to set the sprite of the component to a sprite that we load from an image file called player.png. The image has to be in the assets/images directory in your project (see the Assets Directory Structure) and you have to add it to the assets section of your pubspec.yaml file. In this class we also set the size of the component to 200x200 and the anchor to the center of the component by sending them to the super constructor. We also let the user of the Player class set the position of the component when creating it (Player(position: Vector2(0, 0))).

To handle input on a component you can add any of our input mixins to the component. For example, if you want to handle tap input you can add the TapCallbacks mixin to the player component, and receive tap events within the bounds of the player component. Or if you want to handle tap input on the whole world you can add the TapCallbacks mixin to the extended World class.

The following example handles taps on the player component, and when the player component is tapped the size of the player will increase by 50 pixels in both width and height.

import 'package:flame/components.dart';
import 'package:flame/geometry.dart';
import 'package:flame/extensions.dart';

class Player extends SpriteComponent with TapCallbacks {
  Player({super.position}) :
    super(size: Vector2.all(200), anchor: Anchor.center);

  @override
  Future<void> onLoad() async {
    sprite = await Sprite.load('player.png');
  }
  
  @override
  void onTapUp(TapUpInfo info) {
    size += Vector2.all(50);
  }
}

This is just a simple example of how to get started with Flame, there are many more features that you can use (and probably need) to create your game, but this should give you a good starting point.

You can also check out the awesome flame repository, it contains quite a lot of good tutorials and articles written by the community to get you started with Flame.

Outside of the scope of the engine¶

Games sometimes require complex feature sets depending on what the game is all about. Some of these feature sets are outside of the scope of the Flame Engine ecosystem, in this section you can find them, and also some recommendations of packages/services that can be used:

Multiplayer (netcode)¶

Flame doesn’t bundle any network feature, which may be needed to write online multiplayer games.

If you are building a multiplayer game, here are some recommendations of packages/services:

Nakama: An open-source server designed to power modern games and apps.
Firebase: Provides dozens of services that can be used to write simpler multiplayer experiences.
Supabase: A cheaper alternative to Firebase, based on Postgres.