Build a 2D physics game with Flutter and Flame

1. Before you begin

Flame is a Flutter-based 2D game engine. In this codelab, you build a game that uses a 2D physics simulation along the lines of Box2D called Forge2D. You use Flame's components to paint the simulated physical reality on the screen for your users to play with. When complete, your game should look like this animated gif:

Prerequisites

• Completion of the Introduction to Flame with Flutter codelab

What you learn

• How the basics of Forge2D works, starting with the different types of physical bodies.
• How to set up a physical simulation in 2D.

What you need

• The Flutter SDK
• Visual Studio Code (VS Code) with the Flutter and Dart plugins

Compiler software for your chosen development target. This codelab works for all six platforms that Flutter supports. You need Visual Studio to target Windows, Xcode to target macOS or iOS, and Android Studio to target Android.

2. Create a project

Create your Flutter project

There are many ways to create a Flutter project. In this section, you use the command line for brevity.

To begin, follow these steps:

1. On a command line, create a Flutter project:

   $ flutter create --empty forge2d_game
   Creating project forge2d_game...
   Resolving dependencies in forge2d_game... (4.7s)
   Got dependencies in forge2d_game.
   Wrote 128 files.
   
   All done!
   You can find general documentation for Flutter at: https://docs.flutter.dev/
   Detailed API documentation is available at: https://api.flutter.dev/
   If you prefer video documentation, consider: https://www.youtube.com/c/flutterdev
   
   In order to run your empty application, type:
   
     $ cd forge2d_game
     $ flutter run
   
   Your empty application code is in forge2d_game/lib/main.dart.
   

2. Modify the project's dependencies to add Flame and Forge2D:

   $ cd forge2d_game
   $ flutter pub add characters flame flame_forge2d flame_kenney_xml xml
   Resolving dependencies...
   Downloading packages...
     characters 1.4.0 (from transitive dependency to direct dependency)
   + flame 1.29.0
   + flame_forge2d 0.19.0+2
   + flame_kenney_xml 0.1.1+12
     flutter_lints 5.0.0 (6.0.0 available)
   + forge2d 0.14.0
     leak_tracker 10.0.9 (11.0.1 available)
     leak_tracker_flutter_testing 3.0.9 (3.0.10 available)
     leak_tracker_testing 3.0.1 (3.0.2 available)
     lints 5.1.1 (6.0.0 available)
     material_color_utilities 0.11.1 (0.13.0 available)
     meta 1.16.0 (1.17.0 available)
   + ordered_set 8.0.0
   + petitparser 6.1.0 (7.0.0 available)
     test_api 0.7.4 (0.7.6 available)
     vector_math 2.1.4 (2.2.0 available)
     vm_service 15.0.0 (15.0.2 available)
   + xml 6.5.0 (6.6.0 available)
   Changed 8 dependencies!
   12 packages have newer versions incompatible with dependency constraints.
   Try `flutter pub outdated` for more information.
   

The flame package is familiar to you, but the other three may need some explanation. The characters package is used for path manipulation in a UTF8 conformant manner. The flame_forge2d package exposes the Forge2D functionality in a way that works well with Flame. Finally, the xml package is used in various places to consume and modify XML content.

Open the project and then replace the contents of the lib/main.dart file with the following:

lib/main.dart

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

void main() {
  runApp(GameWidget.controlled(gameFactory: FlameGame.new));
}

This starts the app with a GameWidget that instantiates the FlameGame instance. There's no Flutter code in this codelab that uses the state of the game instance to display information about the running game, so this simplified bootstrap works nicely.

Optional: Take a macOS only side quest

The screenshots in this project are from the game as a macOS desktop app. To avoid the title bar of the app detracting from the overall experience, you can modify the project configuration of the macOS runner to elide the title bar.

To do so, follow these steps:

1. Create a bin/modify_macos_config.dart file and add the following content:

bin/modify_macos_config.dart

import 'dart:io';
import 'package:xml/xml.dart';
import 'package:xml/xpath.dart';

void main() {
  final file = File('macos/Runner/Base.lproj/MainMenu.xib');
  var document = XmlDocument.parse(file.readAsStringSync());
  document.xpath('//document/objects/window').first
    ..setAttribute('titlebarAppearsTransparent', 'YES')
    ..setAttribute('titleVisibility', 'hidden');
  document
      .xpath('//document/objects/window/windowStyleMask')
      .first
      .setAttribute('fullSizeContentView', 'YES');
  file.writeAsStringSync(document.toString());
}

This file is not in the lib directory because it isn't part of the runtime codebase for the game. It's a command-line tool used for modifying the project.

2. From the project base directory, run the tool as follows:

dart bin/modify_macos_config.dart

If everything goes to plan, the program will generate no output on the command line. It will, however, modify the macos/Runner/Base.lproj/MainMenu.xib configuration file to run the game without a visible title bar and with the Flame game taking up the entire window.

Run the game to verify everything is working. It should display a new window with only a blank black background.

3. Add image assets

Add the images

Any game needs art assets to be able to paint a screen in a way that uses find fun. This codelab will use the Physics Assets pack from Kenney.nl. These assets are licensed Creative Commons CC0, but I still strongly suggest giving the team at Kenney a donation so they can continue the great work they are doing. I did.

You will need to modify the pubspec.yaml configuration file to enable the use of Kenney's assets. Modify it as follows:

pubspec.yaml

name: forge2d_game
description: "A new Flutter project."
publish_to: 'none'
version: 0.1.0

environment:
  sdk: ^3.8.1

dependencies:
  flutter:
    sdk: flutter
  characters: ^1.4.0
  flame: ^1.29.0
  flame_forge2d: ^0.19.0+2
  flame_kenney_xml: ^0.1.1+12
  xml: ^6.5.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0

flutter:
  uses-material-design: true
  assets:                        # Add from here
    - assets/
    - assets/images/             # To here.

Flame expects image assets to be located in assets/images, although this can be configured differently. See Flame's Images documentation for more detail. Now that you have the paths configured, you need to add them to the project itself. One way to do this is to use the command line as follows:

mkdir -p assets/images

There should be no output from the mkdir command, but the new directory should be visible in either your editor or a file explorer.

Expand the kenney_physics-assets.zip file you downloaded, and you should see something like this:

From the PNG/Backgrounds directory, copy across the colored_desert.png, colored_grass.png, colored_land.png and colored_shroom.png files to your project's assets/images directory.

There are also sprite sheets. These are a combination of a PNG image and an XML file that describes where in the spritesheet image smaller images may be found. Spritesheets are a technique for reducing loading time by only loading a single file as opposed to tens, if not hundreds, of individual image files.

Copy across the spritesheet_aliens.png, spritesheet_elements.png, and the spritesheet_tiles.png to your project's assets/images directory. While you are here, also copy the spritesheet_aliens.xml, spritesheet_elements.xml and spritesheet_tiles.xml files to your project's assets directory. Your project should look like the following.

Paint the background

Now that your project has image assets added, time to put them on the screen. Well, one image on screen. More will come in the following steps.

Create a file called background.dart in a new directory called lib/components and add the following content.

lib/components/background.dart

import 'dart:math';
import 'package:flame/components.dart';
import 'game.dart';

class Background extends SpriteComponent with HasGameReference<MyPhysicsGame> {
  Background({required super.sprite})
    : super(anchor: Anchor.center, position: Vector2(0, 0));

  @override
  void onMount() {
    super.onMount();

    size = Vector2.all(
      max(
        game.camera.visibleWorldRect.width,
        game.camera.visibleWorldRect.height,
      ),
    );
  }
}

This component is a specialized SpriteComponent. It is responsible for displaying one of Kenney.nl's four background images. There are a few simplifying assumptions in this code. The first is that the images are square, which all four of the background images from Kenney are. The second is that the size of the visible world will never change, otherwise this component would need to handle game resize events. The third assumption is that the position (0,0) will be in the center of the screen. These assumptions require specific configuration of the game's CameraComponent.

Create another new file, this one called game.dart, again in the lib/components directory.

lib/components/game.dart

import 'dart:async';

import 'package:flame/components.dart';
import 'package:flame_forge2d/flame_forge2d.dart';
import 'package:flame_kenney_xml/flame_kenney_xml.dart';

import 'background.dart';

class MyPhysicsGame extends Forge2DGame {
  MyPhysicsGame()
    : super(
        gravity: Vector2(0, 10),
        camera: CameraComponent.withFixedResolution(width: 800, height: 600),
      );

  late final XmlSpriteSheet aliens;
  late final XmlSpriteSheet elements;
  late final XmlSpriteSheet tiles;

  @override
  FutureOr<void> onLoad() async {
    final backgroundImage = await images.load('colored_grass.png');
    final spriteSheets = await Future.wait([
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_aliens.png',
        xmlPath: 'spritesheet_aliens.xml',
      ),
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_elements.png',
        xmlPath: 'spritesheet_elements.xml',
      ),
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_tiles.png',
        xmlPath: 'spritesheet_tiles.xml',
      ),
    ]);

    aliens = spriteSheets[0];
    elements = spriteSheets[1];
    tiles = spriteSheets[2];

    await world.add(Background(sprite: Sprite(backgroundImage)));

    return super.onLoad();
  }
}

A lot is happening here. Start with the MyPhysicsGame class. Unlike the previous codelab, this extends Forge2DGame not FlameGame. Forge2DGame itself extends FlameGame with a few interesting tweaks. The first is that, by default, zoom is set to 10. This zoom setting is to do with the range of useful values that Box2D style physics simulation engines work well with. The engine is written using the MKS system where the units are assumed to be in meters, kilograms and seconds. The range over which you don't see noticeable mathematical errors for objects is from 0.1 meters to 10s of meters. Feeding in pixel dimensions directly without some level of down scaling would take Forge2D outside of its useful envelope. The useful summary is to think of simulating objects in the range of a soda can up to a bus.

The assumptions made in the Background component are satisfied here by fixing the CameraComponent's resolution to 800 by 600 virtual pixels. This means that the game area will be 80 units wide, and 60 units tall, centered at (0,0). This has no effect on the displayed resolution, but it will affect where we place objects in the game scene.

Alongside the camera constructor argument is another, more physics aligned argument called gravity. Gravity is set to a Vector2 with an x of 0 and a y of 10. The 10 is a close approximation of the generally accepted 9.81 meters per second per second value for gravity. The fact that gravity is set to positive 10 shows that in this system the direction for the Y axis is down. Which is different to Box2D generally, but is in line with how Flame is usually configured.

Next up is the onLoad method. This method is asynchronous, which is appropriate because it is responsible for loading image assets from disk. The calls to images.load return a Future<Image>, and as a side effect cache the loaded image in the Game object. These futures are gathered together and awaited for as a single unit using the Futures.wait static method. The list of returned images are then pattern matched into individual names.

The spritesheet images are then fed into a series of XmlSpriteSheet objects which are responsible for retrieving the individually named Sprites contained in the spritesheet. The XmlSpriteSheet class is defined in the flame_kenney_xml package.

With all that out of the way, you only need a couple of minor edits to lib/main.dart to get an image on the screen.

lib/main.dart

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

import 'components/game.dart';                                    // Add this import

void main() {
  runApp(GameWidget.controlled(gameFactory: MyPhysicsGame.new));  // Modify this line
}

With this change you can now run the game again to see the background on the screen. Note, the CameraComponent.withFixedResolution() camera instance will add letterboxing as required to make the 800 by 600 ratio of the game work.

4. Add the ground

Something to build upon

If we have gravity, we need something to catch objects in the game before they fall off the bottom of the screen. Unless falling off screen is part of your game design, of course. Create a new ground.dart file in your lib/components directory and add the following to it:

lib/components/ground.dart

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

const groundSize = 7.0;

class Ground extends BodyComponent {
  Ground(Vector2 position, Sprite sprite)
    : super(
        renderBody: false,
        bodyDef: BodyDef()
          ..position = position
          ..type = BodyType.static,
        fixtureDefs: [
          FixtureDef(
            PolygonShape()..setAsBoxXY(groundSize / 2, groundSize / 2),
            friction: 0.3,
          ),
        ],
        children: [
          SpriteComponent(
            anchor: Anchor.center,
            sprite: sprite,
            size: Vector2.all(groundSize),
            position: Vector2(0, 0),
          ),
        ],
      );
}

This Ground component derives from BodyComponent. In Forge2D bodies are important, they are the objects that are part of the two dimensional physical simulation. The BodyDef for this component is specified to have a BodyType.static.

In Forge2D, bodies have three different types. Static bodies don't move. They effectively have both zero mass - they don't react to gravity - and infinite mass - they don't move when hit by other objects, no matter how heavy they are. This makes static bodies perfect for a ground surface, as it doesn't move.

The other two types of bodies are kinematic and dynamic. Dynamic bodies are bodies that are completely simulated, they react to gravity and to the objects they bump into. You will see many dynamic bodies in the rest of this codelab. Kinematic bodies are a halfway house between static and dynamic. They move, but they don't react to gravity or other objects hitting them. Useful, but beyond the scope of this codelab.

The body itself does not do much. A body needs associated shapes to have substance. In this case, this body has one associated shape, a PolygonShape set as a BoxXY. This type of box is axis aligned with the world, unlike a PolygonShape set as a BoxXY which can be rotated around a point of rotation. Again useful, but also outside the scope of this codelab. The shape and the body are attached together with a fixture, which is useful for adding things like friction to the system.

By default, a body will render its attached shapes in a way that is useful for debugging, but doesn't make for great gameplay. Setting the super argument renderBody to false disables this debug rendering. Giving this body an in-game rendering is the responsibility of the child SpriteComponent.

To add the Ground component to the game, edit your game.dart file as follows.

lib/components/game.dart

import 'dart:async';

import 'package:flame/components.dart';
import 'package:flame_forge2d/flame_forge2d.dart';
import 'package:flame_kenney_xml/flame_kenney_xml.dart';

import 'background.dart';
import 'ground.dart';                                      // Add this import

class MyPhysicsGame extends Forge2DGame {
  MyPhysicsGame()
    : super(
        gravity: Vector2(0, 10),
        camera: CameraComponent.withFixedResolution(width: 800, height: 600),
      );

  late final XmlSpriteSheet aliens;
  late final XmlSpriteSheet elements;
  late final XmlSpriteSheet tiles;

  @override
  FutureOr<void> onLoad() async {
    final backgroundImage = await images.load('colored_grass.png');
    final spriteSheets = await Future.wait([
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_aliens.png',
        xmlPath: 'spritesheet_aliens.xml',
      ),
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_elements.png',
        xmlPath: 'spritesheet_elements.xml',
      ),
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_tiles.png',
        xmlPath: 'spritesheet_tiles.xml',
      ),
    ]);

    aliens = spriteSheets[0];
    elements = spriteSheets[1];
    tiles = spriteSheets[2];

    await world.add(Background(sprite: Sprite(backgroundImage)));
    await addGround();                                     // Add this line

    return super.onLoad();
  }

  Future<void> addGround() {                               // Add from here...
    return world.addAll([
      for (
        var x = camera.visibleWorldRect.left;
        x < camera.visibleWorldRect.right + groundSize;
        x += groundSize
      )
        Ground(
          Vector2(x, (camera.visibleWorldRect.height - groundSize) / 2),
          tiles.getSprite('grass.png'),
        ),
    ]);
  }                                                        // To here.
}

This edit adds a series of Ground components to the world by using a for loop inside of a List context, and passing the resulting list of Ground components to the world's addAll method.

Note: It is vital that you add it to the world, not the game itself. If you do add the Ground components directly to the game instance, they won't be correctly transformed by the cameraComponent, nor will they be part of the Forge2D simulation. For BodyComponents to be simulated with Forge2D they must be direct children of the world.

Running the game now shows the background and the ground.

5. Add the bricks

Build a wall

The ground gave us an example of a static body. Now it is time for your first dynamic component. Dynamic components in Forge2D are the cornerstone of the player's experience, they are the things that move and interact with the world around them. In this step, you will introduce bricks, which will be randomly chosen to appear on screen in a cluster of bricks. You will see them fall and bump into each other as they do so.

Bricks will be made from the elements sprite sheet. If you look at the sprite sheet description in assets/spritesheet_elements.xml you will see we have an interesting problem. The names don't seem to be very helpful. What would be useful would be able to select a brick by type of material, its size, and the amount of damage. Thankfully, a helpful elf spent some time to figure out the pattern in the file naming and created a tool to make it easier for y'all. Create a new file generate_brick_file_names.dart in the bin directory and add the following content:

bin/generate_brick_file_names.dart

import 'dart:io';
import 'package:equatable/equatable.dart';
import 'package:xml/xml.dart';
import 'package:xml/xpath.dart';

void main() {
  final file = File('assets/spritesheet_elements.xml');
  final rects = <String, Rect>{};
  final document = XmlDocument.parse(file.readAsStringSync());
  for (final node in document.xpath('//TextureAtlas/SubTexture')) {
    final name = node.getAttribute('name')!;
    rects[name] = Rect(
      x: int.parse(node.getAttribute('x')!),
      y: int.parse(node.getAttribute('y')!),
      width: int.parse(node.getAttribute('width')!),
      height: int.parse(node.getAttribute('height')!),
    );
  }
  print(generateBrickFileNames(rects));
}

class Rect extends Equatable {
  final int x;
  final int y;
  final int width;
  final int height;
  const Rect({
    required this.x,
    required this.y,
    required this.width,
    required this.height,
  });

  Size get size => Size(width, height);

  @override
  List<Object?> get props => [x, y, width, height];

  @override
  bool get stringify => true;
}

class Size extends Equatable {
  final int width;
  final int height;
  const Size(this.width, this.height);

  @override
  List<Object?> get props => [width, height];

  @override
  bool get stringify => true;
}

String generateBrickFileNames(Map<String, Rect> rects) {
  final groups = <Size, List<String>>{};
  for (final entry in rects.entries) {
    groups.putIfAbsent(entry.value.size, () => []).add(entry.key);
  }
  final buff = StringBuffer();
  buff.writeln('''
Map<BrickDamage, String> brickFileNames(BrickType type, BrickSize size) {
  return switch ((type, size)) {''');
  for (final entry in groups.entries) {
    final size = entry.key;
    final entries = entry.value;
    entries.sort();
    for (final type in ['Explosive', 'Glass', 'Metal', 'Stone', 'Wood']) {
      var filtered = entries.where((element) => element.contains(type));
      if (filtered.length == 5) {
        buff.writeln('''
    (BrickType.${type.toLowerCase()}, BrickSize.size${size.width}x${size.height}) => {
        BrickDamage.none: '${filtered.elementAt(0)}',
        BrickDamage.some: '${filtered.elementAt(1)}',
        BrickDamage.lots: '${filtered.elementAt(4)}',
      },''');
      } else if (filtered.length == 10) {
        buff.writeln('''
    (BrickType.${type.toLowerCase()}, BrickSize.size${size.width}x${size.height}) => {
        BrickDamage.none: '${filtered.elementAt(3)}',
        BrickDamage.some: '${filtered.elementAt(4)}',
        BrickDamage.lots: '${filtered.elementAt(9)}',
      },''');
      } else if (filtered.length == 15) {
        buff.writeln('''
    (BrickType.${type.toLowerCase()}, BrickSize.size${size.width}x${size.height}) => {
        BrickDamage.none: '${filtered.elementAt(7)}',
        BrickDamage.some: '${filtered.elementAt(8)}',
        BrickDamage.lots: '${filtered.elementAt(13)}',
      },''');
      }
    }
  }
  buff.writeln('''
  };
}''');
  return buff.toString();
}

Your editor should give you a warning or error about a missing dependency. Add it using the following command:

flutter pub add equatable

You should now be able to run this program as follows:

$ dart run bin/generate_brick_file_names.dart
Map<BrickDamage, String> brickFileNames(BrickType type, BrickSize size) {
  return switch ((type, size)) {
    (BrickType.explosive, BrickSize.size140x70) => {
        BrickDamage.none: 'elementExplosive009.png',
        BrickDamage.some: 'elementExplosive012.png',
        BrickDamage.lots: 'elementExplosive050.png',
      },
    (BrickType.glass, BrickSize.size140x70) => {
        BrickDamage.none: 'elementGlass010.png',
        BrickDamage.some: 'elementGlass013.png',
        BrickDamage.lots: 'elementGlass048.png',
      },
[Content elided...]
    (BrickType.wood, BrickSize.size140x220) => {
        BrickDamage.none: 'elementWood020.png',
        BrickDamage.some: 'elementWood025.png',
        BrickDamage.lots: 'elementWood052.png',
      },
  };
}

This tool has helpfully parsed the sprite sheet description file and converted it into Dart code that we can use to select the right image file for each brick you want to put on screen. Useful!

Create the brick.dart file with the following content:

lib/components/brick.dart

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

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

const brickScale = 0.5;

enum BrickType {
  explosive(density: 1, friction: 0.5),
  glass(density: 0.5, friction: 0.2),
  metal(density: 1, friction: 0.4),
  stone(density: 2, friction: 1),
  wood(density: 0.25, friction: 0.6);

  final double density;
  final double friction;

  const BrickType({required this.density, required this.friction});
  static BrickType get randomType => values[Random().nextInt(values.length)];
}

enum BrickSize {
  size70x70(ui.Size(70, 70)),
  size140x70(ui.Size(140, 70)),
  size220x70(ui.Size(220, 70)),
  size70x140(ui.Size(70, 140)),
  size140x140(ui.Size(140, 140)),
  size220x140(ui.Size(220, 140)),
  size140x220(ui.Size(140, 220)),
  size70x220(ui.Size(70, 220));

  final ui.Size size;

  const BrickSize(this.size);

  static BrickSize get randomSize => values[Random().nextInt(values.length)];
}

enum BrickDamage { none, some, lots }

Map<BrickDamage, String> brickFileNames(BrickType type, BrickSize size) {
  return switch ((type, size)) {
    (BrickType.explosive, BrickSize.size140x70) => {
      BrickDamage.none: 'elementExplosive009.png',
      BrickDamage.some: 'elementExplosive012.png',
      BrickDamage.lots: 'elementExplosive050.png',
    },
    (BrickType.glass, BrickSize.size140x70) => {
      BrickDamage.none: 'elementGlass010.png',
      BrickDamage.some: 'elementGlass013.png',
      BrickDamage.lots: 'elementGlass048.png',
    },
    (BrickType.metal, BrickSize.size140x70) => {
      BrickDamage.none: 'elementMetal009.png',
      BrickDamage.some: 'elementMetal012.png',
      BrickDamage.lots: 'elementMetal050.png',
    },
    (BrickType.stone, BrickSize.size140x70) => {
      BrickDamage.none: 'elementStone009.png',
      BrickDamage.some: 'elementStone012.png',
      BrickDamage.lots: 'elementStone047.png',
    },
    (BrickType.wood, BrickSize.size140x70) => {
      BrickDamage.none: 'elementWood011.png',
      BrickDamage.some: 'elementWood014.png',
      BrickDamage.lots: 'elementWood054.png',
    },
    (BrickType.explosive, BrickSize.size70x70) => {
      BrickDamage.none: 'elementExplosive011.png',
      BrickDamage.some: 'elementExplosive014.png',
      BrickDamage.lots: 'elementExplosive049.png',
    },
    (BrickType.glass, BrickSize.size70x70) => {
      BrickDamage.none: 'elementGlass011.png',
      BrickDamage.some: 'elementGlass012.png',
      BrickDamage.lots: 'elementGlass046.png',
    },
    (BrickType.metal, BrickSize.size70x70) => {
      BrickDamage.none: 'elementMetal011.png',
      BrickDamage.some: 'elementMetal014.png',
      BrickDamage.lots: 'elementMetal049.png',
    },
    (BrickType.stone, BrickSize.size70x70) => {
      BrickDamage.none: 'elementStone011.png',
      BrickDamage.some: 'elementStone014.png',
      BrickDamage.lots: 'elementStone046.png',
    },
    (BrickType.wood, BrickSize.size70x70) => {
      BrickDamage.none: 'elementWood010.png',
      BrickDamage.some: 'elementWood013.png',
      BrickDamage.lots: 'elementWood045.png',
    },
    (BrickType.explosive, BrickSize.size220x70) => {
      BrickDamage.none: 'elementExplosive013.png',
      BrickDamage.some: 'elementExplosive016.png',
      BrickDamage.lots: 'elementExplosive051.png',
    },
    (BrickType.glass, BrickSize.size220x70) => {
      BrickDamage.none: 'elementGlass014.png',
      BrickDamage.some: 'elementGlass017.png',
      BrickDamage.lots: 'elementGlass049.png',
    },
    (BrickType.metal, BrickSize.size220x70) => {
      BrickDamage.none: 'elementMetal013.png',
      BrickDamage.some: 'elementMetal016.png',
      BrickDamage.lots: 'elementMetal051.png',
    },
    (BrickType.stone, BrickSize.size220x70) => {
      BrickDamage.none: 'elementStone013.png',
      BrickDamage.some: 'elementStone016.png',
      BrickDamage.lots: 'elementStone048.png',
    },
    (BrickType.wood, BrickSize.size220x70) => {
      BrickDamage.none: 'elementWood012.png',
      BrickDamage.some: 'elementWood015.png',
      BrickDamage.lots: 'elementWood047.png',
    },
    (BrickType.explosive, BrickSize.size70x140) => {
      BrickDamage.none: 'elementExplosive017.png',
      BrickDamage.some: 'elementExplosive022.png',
      BrickDamage.lots: 'elementExplosive052.png',
    },
    (BrickType.glass, BrickSize.size70x140) => {
      BrickDamage.none: 'elementGlass018.png',
      BrickDamage.some: 'elementGlass023.png',
      BrickDamage.lots: 'elementGlass050.png',
    },
    (BrickType.metal, BrickSize.size70x140) => {
      BrickDamage.none: 'elementMetal017.png',
      BrickDamage.some: 'elementMetal022.png',
      BrickDamage.lots: 'elementMetal052.png',
    },
    (BrickType.stone, BrickSize.size70x140) => {
      BrickDamage.none: 'elementStone017.png',
      BrickDamage.some: 'elementStone022.png',
      BrickDamage.lots: 'elementStone049.png',
    },
    (BrickType.wood, BrickSize.size70x140) => {
      BrickDamage.none: 'elementWood016.png',
      BrickDamage.some: 'elementWood021.png',
      BrickDamage.lots: 'elementWood048.png',
    },
    (BrickType.explosive, BrickSize.size140x140) => {
      BrickDamage.none: 'elementExplosive018.png',
      BrickDamage.some: 'elementExplosive023.png',
      BrickDamage.lots: 'elementExplosive053.png',
    },
    (BrickType.glass, BrickSize.size140x140) => {
      BrickDamage.none: 'elementGlass019.png',
      BrickDamage.some: 'elementGlass024.png',
      BrickDamage.lots: 'elementGlass051.png',
    },
    (BrickType.metal, BrickSize.size140x140) => {
      BrickDamage.none: 'elementMetal018.png',
      BrickDamage.some: 'elementMetal023.png',
      BrickDamage.lots: 'elementMetal053.png',
    },
    (BrickType.stone, BrickSize.size140x140) => {
      BrickDamage.none: 'elementStone018.png',
      BrickDamage.some: 'elementStone023.png',
      BrickDamage.lots: 'elementStone050.png',
    },
    (BrickType.wood, BrickSize.size140x140) => {
      BrickDamage.none: 'elementWood017.png',
      BrickDamage.some: 'elementWood022.png',
      BrickDamage.lots: 'elementWood049.png',
    },
    (BrickType.explosive, BrickSize.size220x140) => {
      BrickDamage.none: 'elementExplosive019.png',
      BrickDamage.some: 'elementExplosive024.png',
      BrickDamage.lots: 'elementExplosive054.png',
    },
    (BrickType.glass, BrickSize.size220x140) => {
      BrickDamage.none: 'elementGlass020.png',
      BrickDamage.some: 'elementGlass025.png',
      BrickDamage.lots: 'elementGlass052.png',
    },
    (BrickType.metal, BrickSize.size220x140) => {
      BrickDamage.none: 'elementMetal019.png',
      BrickDamage.some: 'elementMetal024.png',
      BrickDamage.lots: 'elementMetal054.png',
    },
    (BrickType.stone, BrickSize.size220x140) => {
      BrickDamage.none: 'elementStone019.png',
      BrickDamage.some: 'elementStone024.png',
      BrickDamage.lots: 'elementStone051.png',
    },
    (BrickType.wood, BrickSize.size220x140) => {
      BrickDamage.none: 'elementWood018.png',
      BrickDamage.some: 'elementWood023.png',
      BrickDamage.lots: 'elementWood050.png',
    },
    (BrickType.explosive, BrickSize.size70x220) => {
      BrickDamage.none: 'elementExplosive020.png',
      BrickDamage.some: 'elementExplosive025.png',
      BrickDamage.lots: 'elementExplosive055.png',
    },
    (BrickType.glass, BrickSize.size70x220) => {
      BrickDamage.none: 'elementGlass021.png',
      BrickDamage.some: 'elementGlass026.png',
      BrickDamage.lots: 'elementGlass053.png',
    },
    (BrickType.metal, BrickSize.size70x220) => {
      BrickDamage.none: 'elementMetal020.png',
      BrickDamage.some: 'elementMetal025.png',
      BrickDamage.lots: 'elementMetal055.png',
    },
    (BrickType.stone, BrickSize.size70x220) => {
      BrickDamage.none: 'elementStone020.png',
      BrickDamage.some: 'elementStone025.png',
      BrickDamage.lots: 'elementStone052.png',
    },
    (BrickType.wood, BrickSize.size70x220) => {
      BrickDamage.none: 'elementWood019.png',
      BrickDamage.some: 'elementWood024.png',
      BrickDamage.lots: 'elementWood051.png',
    },
    (BrickType.explosive, BrickSize.size140x220) => {
      BrickDamage.none: 'elementExplosive021.png',
      BrickDamage.some: 'elementExplosive026.png',
      BrickDamage.lots: 'elementExplosive056.png',
    },
    (BrickType.glass, BrickSize.size140x220) => {
      BrickDamage.none: 'elementGlass022.png',
      BrickDamage.some: 'elementGlass027.png',
      BrickDamage.lots: 'elementGlass054.png',
    },
    (BrickType.metal, BrickSize.size140x220) => {
      BrickDamage.none: 'elementMetal021.png',
      BrickDamage.some: 'elementMetal026.png',
      BrickDamage.lots: 'elementMetal056.png',
    },
    (BrickType.stone, BrickSize.size140x220) => {
      BrickDamage.none: 'elementStone021.png',
      BrickDamage.some: 'elementStone026.png',
      BrickDamage.lots: 'elementStone053.png',
    },
    (BrickType.wood, BrickSize.size140x220) => {
      BrickDamage.none: 'elementWood020.png',
      BrickDamage.some: 'elementWood025.png',
      BrickDamage.lots: 'elementWood052.png',
    },
  };
}

class Brick extends BodyComponent {
  Brick({
    required this.type,
    required this.size,
    required BrickDamage damage,
    required Vector2 position,
    required Map<BrickDamage, Sprite> sprites,
  }) : _damage = damage,
       _sprites = sprites,
       super(
         renderBody: false,
         bodyDef: BodyDef()
           ..position = position
           ..type = BodyType.dynamic,
         fixtureDefs: [
           FixtureDef(
               PolygonShape()..setAsBoxXY(
                 size.size.width / 20 * brickScale,
                 size.size.height / 20 * brickScale,
               ),
             )
             ..restitution = 0.4
             ..density = type.density
             ..friction = type.friction,
         ],
       );

  late final SpriteComponent _spriteComponent;

  final BrickType type;
  final BrickSize size;
  final Map<BrickDamage, Sprite> _sprites;

  BrickDamage _damage;
  BrickDamage get damage => _damage;
  set damage(BrickDamage value) {
    _damage = value;
    _spriteComponent.sprite = _sprites[value];
  }

  @override
  Future<void> onLoad() {
    _spriteComponent = SpriteComponent(
      anchor: Anchor.center,
      scale: Vector2.all(1),
      sprite: _sprites[_damage],
      size: size.size.toVector2() / 10 * brickScale,
      position: Vector2(0, 0),
    );
    add(_spriteComponent);
    return super.onLoad();
  }
}

You can now see how the Dart code generated previously is integrated into this codebase to make it quick to select brick images based on material, size and condition. Looking past the enums and onto the Brick component itself, you should find most of this code seems fairly familiar from the Ground component in the previous step. There is mutable state here to allow for the brick to become damaged, although using this is left as an exercise for the reader.

Time to get the bricks on screen. Edit the game.dart file as follows:

lib/components/game.dart

import 'dart:async';
import 'dart:math';                                        // Add this import

import 'package:flame/components.dart';
import 'package:flame_forge2d/flame_forge2d.dart';
import 'package:flame_kenney_xml/flame_kenney_xml.dart';

import 'background.dart';
import 'brick.dart';                                       // Add this import
import 'ground.dart';

class MyPhysicsGame extends Forge2DGame {
  MyPhysicsGame()
    : super(
        gravity: Vector2(0, 10),
        camera: CameraComponent.withFixedResolution(width: 800, height: 600),
      );

  late final XmlSpriteSheet aliens;
  late final XmlSpriteSheet elements;
  late final XmlSpriteSheet tiles;

  @override
  FutureOr<void> onLoad() async {
    final backgroundImage = await images.load('colored_grass.png');
    final spriteSheets = await Future.wait([
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_aliens.png',
        xmlPath: 'spritesheet_aliens.xml',
      ),
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_elements.png',
        xmlPath: 'spritesheet_elements.xml',
      ),
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_tiles.png',
        xmlPath: 'spritesheet_tiles.xml',
      ),
    ]);

    aliens = spriteSheets[0];
    elements = spriteSheets[1];
    tiles = spriteSheets[2];

    await world.add(Background(sprite: Sprite(backgroundImage)));
    await addGround();
    unawaited(addBricks());                                // Add this line

    return super.onLoad();
  }

  Future<void> addGround() {
    return world.addAll([
      for (
        var x = camera.visibleWorldRect.left;
        x < camera.visibleWorldRect.right + groundSize;
        x += groundSize
      )
        Ground(
          Vector2(x, (camera.visibleWorldRect.height - groundSize) / 2),
          tiles.getSprite('grass.png'),
        ),
    ]);
  }

  final _random = Random();                                // Add from here...

  Future<void> addBricks() async {
    for (var i = 0; i < 5; i++) {
      final type = BrickType.randomType;
      final size = BrickSize.randomSize;
      await world.add(
        Brick(
          type: type,
          size: size,
          damage: BrickDamage.some,
          position: Vector2(
            camera.visibleWorldRect.right / 3 +
                (_random.nextDouble() * 5 - 2.5),
            0,
          ),
          sprites: brickFileNames(
            type,
            size,
          ).map((key, filename) => MapEntry(key, elements.getSprite(filename))),
        ),
      );
      await Future<void>.delayed(const Duration(milliseconds: 500));
    }
  }                                                        // To here.
}

This code addition is a bit different to the code you used to add the Ground components. This time the Bricks are being added in a random cluster, over time. There are two parts to this, the first is that the method that adds the Bricks awaits a Future.delayed, which is the asynchronous equivalent of a sleep() call. However, there is a second part to making this work, the call to addBricks in the onLoad method is not awaited. If it were, the onLoad method won't complete until all the bricks were on screen. Wrapping the call to addBricks in an unawaited call makes the linters happy, and makes our intent obvious to future programmers. Not waiting for this method to return is intentional.

Run the game, and you will see bricks appear, bumping into each other, and spilling on the ground.

6. Add the player

Throw aliens at bricks

Watching bricks tumble is fun the first couple of times, but I'm guessing this game is going to be more fun if we give the player an avatar they can use to interact with the world. How about an alien they can throw at the bricks?

Create a new player.dart file in the lib/components directory and add the following to it:

lib/components/player.dart

import 'dart:math';

import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/events.dart';
import 'package:flame_forge2d/flame_forge2d.dart';
import 'package:flutter/material.dart';

const playerSize = 5.0;

enum PlayerColor {
  pink,
  blue,
  green,
  yellow;

  static PlayerColor get randomColor =>
      PlayerColor.values[Random().nextInt(PlayerColor.values.length)];

  String get fileName =>
      'alien${toString().split('.').last.capitalize}_round.png';
}

class Player extends BodyComponent with DragCallbacks {
  Player(Vector2 position, Sprite sprite)
    : _sprite = sprite,
      super(
        renderBody: false,
        bodyDef: BodyDef()
          ..position = position
          ..type = BodyType.static
          ..angularDamping = 0.1
          ..linearDamping = 0.1,
        fixtureDefs: [
          FixtureDef(CircleShape()..radius = playerSize / 2)
            ..restitution = 0.4
            ..density = 0.75
            ..friction = 0.5,
        ],
      );

  final Sprite _sprite;

  @override
  Future<void> onLoad() {
    addAll([
      CustomPainterComponent(
        painter: _DragPainter(this),
        anchor: Anchor.center,
        size: Vector2(playerSize, playerSize),
        position: Vector2(0, 0),
      ),
      SpriteComponent(
        anchor: Anchor.center,
        sprite: _sprite,
        size: Vector2(playerSize, playerSize),
        position: Vector2(0, 0),
      ),
    ]);
    return super.onLoad();
  }

  @override
  void update(double dt) {
    super.update(dt);

    if (!body.isAwake) {
      removeFromParent();
    }

    if (position.x > camera.visibleWorldRect.right + 10 ||
        position.x < camera.visibleWorldRect.left - 10) {
      removeFromParent();
    }
  }

  Vector2 _dragStart = Vector2.zero();
  Vector2 _dragDelta = Vector2.zero();
  Vector2 get dragDelta => _dragDelta;

  @override
  void onDragStart(DragStartEvent event) {
    super.onDragStart(event);
    if (body.bodyType == BodyType.static) {
      _dragStart = event.localPosition;
    }
  }

  @override
  void onDragUpdate(DragUpdateEvent event) {
    if (body.bodyType == BodyType.static) {
      _dragDelta = event.localEndPosition - _dragStart;
    }
  }

  @override
  void onDragEnd(DragEndEvent event) {
    super.onDragEnd(event);
    if (body.bodyType == BodyType.static) {
      children
          .whereType<CustomPainterComponent>()
          .firstOrNull
          ?.removeFromParent();
      body.setType(BodyType.dynamic);
      body.applyLinearImpulse(_dragDelta * -50);
      add(RemoveEffect(delay: 5.0));
    }
  }
}

extension on String {
  String get capitalize =>
      characters.first.toUpperCase() + characters.skip(1).toLowerCase().join();
}

class _DragPainter extends CustomPainter {
  _DragPainter(this.player);

  final Player player;

  @override
  void paint(Canvas canvas, Size size) {
    if (player.dragDelta != Vector2.zero()) {
      var center = size.center(Offset.zero);
      canvas.drawLine(
        center,
        center + (player.dragDelta * -1).toOffset(),
        Paint()
          ..color = Colors.orange.withAlpha(180)
          ..strokeWidth = 0.4
          ..strokeCap = StrokeCap.round,
      );
    }
  }

  @override
  bool shouldRepaint(covariant CustomPainter oldDelegate) => true;
}

This is a step up from the Brick components in the previous step. This Player component has two child components, a SpriteComponent that you should recognise, and a CustomPainterComponent that is new. The CustomPainter concept is from Flutter, and it lets you paint on a canvas. It is used here to give the player feedback on where the round alien is going to fly when it is flung.

How does the player initiate the flinging of the alien? Using a drag gesture, which the Player component detects with the DragCallbacks callbacks. The eagle eyed amongst you will have noticed something else here.

Where Ground components were static bodies, the Brick components were dynamic bodies. The Player here is a combination of both. The player starts off as static, waiting for the player to drag it, and on drag release it converts itself from static to dynamic, adds linear impulse in proportion to the drag, and lets the alien avatar fly!

There is also code in the Player component to remove it from the screen if it goes out of bounds, falls asleep or times out. The intent here is to allow the player to fling the alien, see what happens, and then have another go.

Integrate the Player component into the game by editing game.dart as follows:

lib/components/game.dart

import 'dart:async';
import 'dart:math';

import 'package:flame/components.dart';
import 'package:flame_forge2d/flame_forge2d.dart';
import 'package:flame_kenney_xml/flame_kenney_xml.dart';

import 'background.dart';
import 'brick.dart';
import 'ground.dart';
import 'player.dart';                                      // Add this import

class MyPhysicsGame extends Forge2DGame {
  MyPhysicsGame()
    : super(
        gravity: Vector2(0, 10),
        camera: CameraComponent.withFixedResolution(width: 800, height: 600),
      );

  late final XmlSpriteSheet aliens;
  late final XmlSpriteSheet elements;
  late final XmlSpriteSheet tiles;

  @override
  FutureOr<void> onLoad() async {
    final backgroundImage = await images.load('colored_grass.png');
    final spriteSheets = await Future.wait([
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_aliens.png',
        xmlPath: 'spritesheet_aliens.xml',
      ),
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_elements.png',
        xmlPath: 'spritesheet_elements.xml',
      ),
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_tiles.png',
        xmlPath: 'spritesheet_tiles.xml',
      ),
    ]);

    aliens = spriteSheets[0];
    elements = spriteSheets[1];
    tiles = spriteSheets[2];

    await world.add(Background(sprite: Sprite(backgroundImage)));
    await addGround();
    unawaited(addBricks());
    await addPlayer();                                     // Add this line

    return super.onLoad();
  }

  Future<void> addGround() {
    return world.addAll([
      for (
        var x = camera.visibleWorldRect.left;
        x < camera.visibleWorldRect.right + groundSize;
        x += groundSize
      )
        Ground(
          Vector2(x, (camera.visibleWorldRect.height - groundSize) / 2),
          tiles.getSprite('grass.png'),
        ),
    ]);
  }

  final _random = Random();

  Future<void> addBricks() async {
    for (var i = 0; i < 5; i++) {
      final type = BrickType.randomType;
      final size = BrickSize.randomSize;
      await world.add(
        Brick(
          type: type,
          size: size,
          damage: BrickDamage.some,
          position: Vector2(
            camera.visibleWorldRect.right / 3 +
                (_random.nextDouble() * 5 - 2.5),
            0,
          ),
          sprites: brickFileNames(
            type,
            size,
          ).map((key, filename) => MapEntry(key, elements.getSprite(filename))),
        ),
      );
      await Future<void>.delayed(const Duration(milliseconds: 500));
    }
  }

  Future<void> addPlayer() async => world.add(             // Add from here...
    Player(
      Vector2(camera.visibleWorldRect.left * 2 / 3, 0),
      aliens.getSprite(PlayerColor.randomColor.fileName),
    ),
  );

  @override
  void update(double dt) {
    super.update(dt);
    if (isMounted && world.children.whereType<Player>().isEmpty) {
      addPlayer();
    }
  }                                                        // To here.
}

Adding the player to the game is similar to the previous components, with one additional wrinkle. The player's alien is designed to remove itself from the game under certain conditions, so there is an update handler here that checks if there is no Player component in the game, and if so, adds one back in. Running the game looks like this.

7. React to impact

Add the enemies

You have seen static and dynamic objects interacting with each other. However, to truly get somewhere, you need to get callbacks in the code when things collide. You are going to introduce some enemies for the player to go against. This gives a path to a winning condition - remove all the enemies from the game!

Create an enemy.dart file in the lib/components directory and add the following:

lib/components/enemy.dart

import 'dart:math';

import 'package:flame/components.dart';
import 'package:flame_forge2d/flame_forge2d.dart';
import 'package:flutter/material.dart';

import 'body_component_with_user_data.dart';

const enemySize = 5.0;

enum EnemyColor {
  pink(color: 'pink', boss: false),
  blue(color: 'blue', boss: false),
  green(color: 'green', boss: false),
  yellow(color: 'yellow', boss: false),
  pinkBoss(color: 'pink', boss: true),
  blueBoss(color: 'blue', boss: true),
  greenBoss(color: 'green', boss: true),
  yellowBoss(color: 'yellow', boss: true);

  final bool boss;
  final String color;

  const EnemyColor({required this.color, required this.boss});

  static EnemyColor get randomColor =>
      EnemyColor.values[Random().nextInt(EnemyColor.values.length)];

  String get fileName =>
      'alien${color.capitalize}_${boss ? 'suit' : 'square'}.png';
}

class Enemy extends BodyComponentWithUserData with ContactCallbacks {
  Enemy(Vector2 position, Sprite sprite)
    : super(
        renderBody: false,
        bodyDef: BodyDef()
          ..position = position
          ..type = BodyType.dynamic,
        fixtureDefs: [
          FixtureDef(
            PolygonShape()..setAsBoxXY(enemySize / 2, enemySize / 2),
            friction: 0.3,
          ),
        ],
        children: [
          SpriteComponent(
            anchor: Anchor.center,
            sprite: sprite,
            size: Vector2.all(enemySize),
            position: Vector2(0, 0),
          ),
        ],
      );

  @override
  void beginContact(Object other, Contact contact) {
    var interceptVelocity =
        (contact.bodyA.linearVelocity - contact.bodyB.linearVelocity).length
            .abs();
    if (interceptVelocity > 35) {
      removeFromParent();
    }

    super.beginContact(other, contact);
  }

  @override
  void update(double dt) {
    super.update(dt);

    if (position.x > camera.visibleWorldRect.right + 10 ||
        position.x < camera.visibleWorldRect.left - 10) {
      removeFromParent();
    }
  }
}

extension on String {
  String get capitalize =>
      characters.first.toUpperCase() + characters.skip(1).toLowerCase().join();
}

From your previous interactions with the Player and Brick components, most of this file should be familiar. However, there will be a couple of red underlines in your editor due to a new unknown base class. Add this class now by adding a file named body_component_with_user_data.dart to lib/components with the following content:

lib/components/body_component_with_user_data.dart

import 'package:flame_forge2d/flame_forge2d.dart';

class BodyComponentWithUserData extends BodyComponent {
  BodyComponentWithUserData({
    super.key,
    super.bodyDef,
    super.children,
    super.fixtureDefs,
    super.paint,
    super.priority,
    super.renderBody,
  });

  @override
  Body createBody() {
    final body = world.createBody(super.bodyDef!)..userData = this;
    fixtureDefs?.forEach(body.createFixture);
    return body;
  }
}

This base class, combined with the new beginContact callback in the Enemy component forms the basis of getting notified programmatically on impacts between bodies. In fact, you will need to edit any components you want to get impact notifications between. So, go ahead and edit the Brick, Ground and Player components to use this BodyComponentWithUserData in place of the BodyComponent base class those components use. For example, here is how to edit the Ground component:

lib/components/ground.dart

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

import 'body_component_with_user_data.dart';               // Add this import

const groundSize = 7.0;

class Ground extends BodyComponentWithUserData {           // Edit this line
  Ground(Vector2 position, Sprite sprite)
    : super(
        renderBody: false,
        bodyDef: BodyDef()
          ..position = position
          ..type = BodyType.static,
        fixtureDefs: [
          FixtureDef(
            PolygonShape()..setAsBoxXY(groundSize / 2, groundSize / 2),
            friction: 0.3,
          ),
        ],
        children: [
          SpriteComponent(
            anchor: Anchor.center,
            sprite: sprite,
            size: Vector2.all(groundSize),
            position: Vector2(0, 0),
          ),
        ],
      );
}

For more information about how Forge2d handles contact, see Forge2D documentation on contact callbacks.

Note: If any component has userData set to null, it is ignored for the purposes of generating contact events. For this game, that means that the Player, Ground, Brick and Enemy components all need their userData set, even though only the Enemy component mixes in the ContactCallbacks mixin.

Win the game

Now that you have enemies, and a way to remove the enemies from the world, there is a simplistic way to turn this simulation into a game. Make the goal to remove all enemies! Time to edit the game.dart file as follows:

lib/components/game.dart

import 'dart:async';
import 'dart:math';

import 'package:flame/components.dart';
import 'package:flame_forge2d/flame_forge2d.dart';
import 'package:flame_kenney_xml/flame_kenney_xml.dart';
import 'package:flutter/material.dart';                    // Add this import

import 'background.dart';
import 'brick.dart';
import 'enemy.dart';                                       // Add this import
import 'ground.dart';
import 'player.dart';

class MyPhysicsGame extends Forge2DGame {
  MyPhysicsGame()
    : super(
        gravity: Vector2(0, 10),
        camera: CameraComponent.withFixedResolution(width: 800, height: 600),
      );

  late final XmlSpriteSheet aliens;
  late final XmlSpriteSheet elements;
  late final XmlSpriteSheet tiles;

  @override
  FutureOr<void> onLoad() async {
    final backgroundImage = await images.load('colored_grass.png');
    final spriteSheets = await Future.wait([
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_aliens.png',
        xmlPath: 'spritesheet_aliens.xml',
      ),
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_elements.png',
        xmlPath: 'spritesheet_elements.xml',
      ),
      XmlSpriteSheet.load(
        imagePath: 'spritesheet_tiles.png',
        xmlPath: 'spritesheet_tiles.xml',
      ),
    ]);

    aliens = spriteSheets[0];
    elements = spriteSheets[1];
    tiles = spriteSheets[2];

    await world.add(Background(sprite: Sprite(backgroundImage)));
    await addGround();
    unawaited(addBricks().then((_) => addEnemies()));      // Modify this line
    await addPlayer();

    return super.onLoad();
  }

  Future<void> addGround() {
    return world.addAll([
      for (
        var x = camera.visibleWorldRect.left;
        x < camera.visibleWorldRect.right + groundSize;
        x += groundSize
      )
        Ground(
          Vector2(x, (camera.visibleWorldRect.height - groundSize) / 2),
          tiles.getSprite('grass.png'),
        ),
    ]);
  }

  final _random = Random();

  Future<void> addBricks() async {
    for (var i = 0; i < 5; i++) {
      final type = BrickType.randomType;
      final size = BrickSize.randomSize;
      await world.add(
        Brick(
          type: type,
          size: size,
          damage: BrickDamage.some,
          position: Vector2(
            camera.visibleWorldRect.right / 3 +
                (_random.nextDouble() * 5 - 2.5),
            0,
          ),
          sprites: brickFileNames(
            type,
            size,
          ).map((key, filename) => MapEntry(key, elements.getSprite(filename))),
        ),
      );
      await Future<void>.delayed(const Duration(milliseconds: 500));
    }
  }

  Future<void> addPlayer() async => world.add(
    Player(
      Vector2(camera.visibleWorldRect.left * 2 / 3, 0),
      aliens.getSprite(PlayerColor.randomColor.fileName),
    ),
  );

  @override
  void update(double dt) {
    super.update(dt);
    if (isMounted &&                                       // Modify from here...
        world.children.whereType<Player>().isEmpty &&
        world.children.whereType<Enemy>().isNotEmpty) {
      addPlayer();
    }
    if (isMounted &&
        enemiesFullyAdded &&
        world.children.whereType<Enemy>().isEmpty &&
        world.children.whereType<TextComponent>().isEmpty) {
      world.addAll(
        [
          (position: Vector2(0.5, 0.5), color: Colors.white),
          (position: Vector2.zero(), color: Colors.orangeAccent),
        ].map(
          (e) => TextComponent(
            text: 'You win!',
            anchor: Anchor.center,
            position: e.position,
            textRenderer: TextPaint(
              style: TextStyle(color: e.color, fontSize: 16),
            ),
          ),
        ),
      );
    }
  }

  var enemiesFullyAdded = false;

  Future<void> addEnemies() async {
    await Future<void>.delayed(const Duration(seconds: 2));
    for (var i = 0; i < 3; i++) {
      await world.add(
        Enemy(
          Vector2(
            camera.visibleWorldRect.right / 3 +
                (_random.nextDouble() * 7 - 3.5),
            (_random.nextDouble() * 3),
          ),
          aliens.getSprite(EnemyColor.randomColor.fileName),
        ),
      );
      await Future<void>.delayed(const Duration(seconds: 1));
    }
    enemiesFullyAdded = true;                              // To here.
  }
}

Your challenge, should you choose to accept it, is to run the game and get yourself to this screen.

8. Congratulations

Congratulations, you succeeded in building a game with Flutter and Flame!

You built a game using the Flame 2D game engine and embedded it in a Flutter wrapper. You used Flame's Effects to animate and remove components. You used Google Fonts and Flutter Animate packages to make the whole game look well designed.

What's next?

Check out some of these codelabs...

• Building next generation UIs in Flutter
• Take your Flutter app from boring to beautiful
• Adding in-app purchases to your Flutter app

Further reading

• Flutter Casual Games Toolkit
• Flame Engine
• How we built the new Super Dash demo in Flutter and Flame in just six weeks!