Constructing Video games in Flutter with Flame: Getting Began

Replace notice: Brian Moakley up to date this tutorial for Flutter 3.3 and Dart 2.18. Vincenzo Guzzi wrote the unique.

Flutter is altering the world by bringing quick, natively compiled software program to the lots. This permits indie builders to launch purposes for each platform in the identical time it might often have taken a software program firm. It’s solely pure that recreation builders wish to make the most of that, too.

Historically, a cell recreation developer would wish to decide on between native efficiency however sluggish growth time or constructing with a multi-platform device like Unity however danger sluggish loading instances and huge app sizes.

If solely there have been a approach to develop lovely native video games with out all of the bloat. That’s the place Flame is available in.

As we speak, you’ll construct a digital world utilizing Flutter and the Flame engine. You’ll discover ways to:

• Use Flame model 1.5 to make a recreation for the net, Android and iOS.
• Use a recreation loop.
• Create a movable participant character.
• Animate your character with sprite sheets.
• Add field collision by studying from a tile map.

Getting Began

You’ll develop a recreation known as RayWorld, a 2-D orthographic recreation within the fashion of old-school Pokemon.

Utilizing an older recreation engine written in one thing like C++, a tutorial like this is able to span over three or 4 collection. However with the facility of Flutter and the Flame engine mixed, you’ll create all this in only one.

You’ll want the starter challenge to finish this tutorial. Obtain it by clicking the Obtain Supplies button on the high or backside of the tutorial.

Construct and run your challenge in your most popular IDE. This tutorial will use Visible Studio Code.

You’ll see a clean display screen with a joypad within the backside proper nook:

What you see right here is rendered purely with Flutter; you’ll want Flame to construct the remainder of your parts.

The Flame Recreation Engine

Flame — a light-weight recreation engine constructed on high of Flutter — provides recreation builders a set of instruments akin to a recreation loop, collision detection and sprite animations to create 2-D video games.

This tutorial will use Flame 1.5.

The Flame engine is modular, permitting customers to select and select which API’s they wish to use, akin to:

• Flame – The core package deal, which presents the sport loop, primary collision detection, Sprites and parts.
• Forge2D – A physics engine with superior collision detection, ported from Box2D to work with Flame.
• Tiled – A module for simply working with tile maps in Flame.
• Audio – A module that provides audio capabilities into your Flame recreation.

Flame harnesses the facility of Flutter and offers a light-weight method to growing 2-D video games for all platforms.

Organising Your Flame Recreation Loop

The primary element you’ll arrange in RayWorld is your Flame recreation loop. This would be the coronary heart of your recreation. You’ll create and handle all of your different parts from right here.

Open your lib folder and create a brand new file known as ray_world_game.dart, then add a brand new class known as RayWorldGame, which extends from the Flame widget FlameGame:

import 'package deal:flame/recreation.dart';
 
class RayWorldGame extends FlameGame {
 @override
 Future<void> onLoad() async {
   // empty
 }
}

Now to make use of your widget. Open main_game_page.dart. Add these two imports to the highest of main_game_page.dart:

import 'package deal:flame/recreation.dart';
import 'ray_world_game.dart';

Subsequent, create an occasion of your new class on the high of MainGameState:

RayWorldGame recreation = RayWorldGame();

Now, add a GameWidget to MainGameState as the primary widget within the Stack, changing // TODO 1 with:

GameWidget(recreation: recreation),

Proper now, your recreation will do nothing. It wants some parts to render. Time so as to add a playable character!

Creating Your Participant

Add a folder in lib known as parts. This folder will retailer all of your Flame parts, beginning together with your participant.

Create a file in parts known as participant.dart. On this class, arrange your Participant class:

import 'package deal:flame/parts.dart';
 
class Participant extends SpriteComponent with HasGameRef {
 Participant()
     : tremendous(
         measurement: Vector2.all(50.0),
       );
 
 @override
 Future<void> onLoad() async {
   tremendous.onLoad();
   // TODO 1
 }
}

Your Participant extends a Flame element known as SpriteComponent. You’ll use this to render a static picture in your recreation. You’re setting the scale of the participant to be 50.

Through the use of the HasGameRef mixin, the Participant now has entry to the core performance of the Flame engine. Now to make use of that performance by loading the sprite.

Change // TODO 1 in Participant with logic to load your participant picture and set the participant’s preliminary place.

sprite = await gameRef.loadSprite('participant.png');
place = gameRef.measurement / 2;

Right here, you employ that recreation reference from the HasGameRef mixin to load a sprite into your recreation with the picture of participant.png. This picture is situated in your Flutter belongings folder. You additionally set the gamers place to be in the midst of the sport.

Return to your ray_world_game.dart file and add your new Participant element as an import on the high of the file:

import 'parts/participant.dart';

Within the high of RayWorldGame, create your Participant:

remaining Participant _player = Participant();

Within the recreation onLoad methodology, exchange // empty with code so as to add your participant into the sport:

add(_player);

add is a brilliant essential methodology when constructing video games with the Flame engine. It means that you can register any element with the core recreation loop and finally render them on display screen. You should utilize it so as to add gamers, enemies, and many different issues as effectively.

Construct and run, and also you’ll see a little bit dude standing within the heart of your recreation.

Fairly thrilling!

Now, it’s time to get your participant shifting.

Including Motion to Your Participant

To maneuver your participant, you first have to know what route the joypad is dragged.

The joypad route is retrieved from the Joypad Flutter widget that lives outdoors the sport loop. The route then will get handed to the GameWidget in main_game_page.dart. In flip, this will move it to Participant, which might react to the route change with motion.

Begin with the Participant.

Open your participant.dart file and add the import for route:

import '../helpers/route.dart';

Then, declare a Course variable within the high of Participant and instantiate it to Course.none:

Course route = Course.none;

The joypad will change to both up, down, left, proper, or none. With every new place, you wish to replace the route variable.

Open ray_world_game.dart. Import the route.dart:

import '../helpers/route.dart';

Now add a perform to replace the route of your participant in RayWorldGame:

void onJoypadDirectionChanged(Course route) {
   _player.route = route;
}

Now, head again to main_game_page.dart and exchange // TODO 2 with a name to your recreation route perform:

recreation.onJoypadDirectionChanged(route);

And voilà, you’ve handed a person enter from a Flutter widget into your recreation and participant parts.

Now that your participant element is aware of what route it ought to be shifting in, it’s time to execute on that info and really transfer your participant!

Executing on Participant Motion

To start out appearing on the data handed by way of to the participant element, head again to participant.dart and add these two capabilities:

@override
 void replace(double delta) {
   tremendous.replace(delta);
   movePlayer(delta);
 }
 
 void movePlayer(double delta) {
   // TODO
 }

replace is a perform distinctive to Flame parts. Will probably be known as every time a body should be rendered, and Flame will guarantee all of your recreation parts replace on the identical time. The delta represents how a lot time has handed for the reason that final replace cycle and can be utilized to maneuver the participant predictably.

Change // TODO within the movePlayer perform with logic to learn the route. You haven’t written the transfer strategies but. You’ll maintain that quickly sufficient. For now, you’ll must endure some compile errors:

swap (route) {
  case Course.up:
    moveUp(delta);
    break;
  case Course.down:
    moveDown(delta);
    break;
  case Course.left:
    moveLeft(delta);
    break;
  case Course.proper:
    moveRight(delta);
    break;
  case Course.none:
    break;
}

movePlayer will now delegate out to different extra particular strategies to maneuver the participant. Subsequent, add the logic for shifting the participant in every route.

Begin by including a velocity variable to the highest of your Participant class:

remaining double _playerSpeed = 300.0;

Now, add a moveDown perform to the underside of your Participant class:

void moveDown(double delta) {
   place.add(Vector2(0, delta * _playerSpeed));
}

Right here, you replace the Participant place worth — represented as an X and a Y inside Vector2 — by your participant velocity multiplied by the delta.

You possibly can image your recreation view drawn on a 2-D aircraft like so:

If the sport view is 2500×2500 pixels in diameter, your participant begins within the center on the coordinates of x:1250, y:1250. Calling moveDown provides about 300 pixels to the participant’s Y place every second the person holds the joypad within the down route, inflicting the sprite to maneuver down the sport viewport.

You could add the same calculation for the opposite three lacking strategies: moveUp, moveLeft and moveRight.

Now for the opposite transfer strategies:

void moveUp(double delta) {
  place.add(Vector2(0, delta * -_playerSpeed));
}
 
void moveLeft(double delta) {
  place.add(Vector2(delta * -_playerSpeed, 0));
}
 
void moveRight(double delta) {
  place.add(Vector2(delta * _playerSpeed, 0));
}

Run your utility as soon as extra, and your little dude will transfer across the display screen in all instructions primarily based in your joypad enter.

Animating Your Participant

Your participant is shifting across the display screen like a boss – nevertheless it seems to be a bit off as a result of the participant is at all times going through in the identical route! You’ll repair that subsequent utilizing sprite sheets.

What Is a Sprite Sheet?

A sprite sheet is a group of sprites in a single picture. Recreation builders have used them for a very long time to save lots of reminiscence and guarantee fast loading instances. It’s a lot faster to load one picture as a substitute of a number of photographs. Recreation engines like Flame can then load the sprite sheet and render solely a piece of the picture.

It’s also possible to use sprite sheets for animations by lining sprites up subsequent to one another in animation frames to allow them to simply be iterated over within the recreation loop.

That is the sprite sheet you’ll use to your playable character in RayWorld:

Every row is a unique animation set and simulates shifting left, proper, up and down.

Including Sprite Sheet Animations to Your Participant

In participant.dart, change your Participant class extension from SpriteComponent to SpriteAnimationComponent as follows:

class Participant extends SpriteAnimationComponent with HasGameRef {

With this new kind of element, you’ll be capable of set an energetic animation, which can run in your participant Sprite.

Import the package deal sprite.dart. You’ll want this for establishing a SpriteSheet:

import 'package deal:flame/sprite.dart';

Add these six new variables to your Participant class:

remaining double _animationSpeed = 0.15;
late remaining SpriteAnimation _runDownAnimation;
late remaining SpriteAnimation _runLeftAnimation;
late remaining SpriteAnimation _runUpAnimation;
late remaining SpriteAnimation _runRightAnimation;
late remaining SpriteAnimation _standingAnimation;

Change the onLoad methodology with new logic to load your animations. We’ll outline the _loadAnimations future in only a second:

@override
 Future<void> onLoad() async {
   await _loadAnimations().then((_) => {animation = _standingAnimation});
}

_loadAnimations will probably be an async name. This methodology waits for the animations to load after which units the sprite’s first energetic animation to _standingAnimation.

Create the _loadAnimations methodology and instantiate your participant SpriteSheet:

Future<void> _loadAnimations() async {
   remaining spriteSheet = SpriteSheet(
     picture: await gameRef.photographs.load('player_spritesheet.png'),
     srcSize: Vector2(29.0, 32.0),
   );
 
   // TODO down animation
 
   // TODO left animation
 
   // TODO up animation
 
   // TODO proper animation
 
   // TODO standing animation
 }

This code hundreds a sprite sheet picture out of your Flutter belongings folder that you simply noticed beforehand.

The picture is 116×128 pixels, and every body is 29×32 pixels. The latter is what you’re setting the srcSize SpriteSheet parameter to. Flame will use these variables to create sprites from the totally different frames in your sprite sheet picture.

Change // TODO down animation with logic to initialize _runDownAnimation:

_runDownAnimation =
       spriteSheet.createAnimation(row: 0, stepTime: _animationSpeed, to: 4);

This code units up an animation that loops throughout the primary row of the participant sprite sheet from the primary body till the fourth. It’s successfully a “whereas” loop that repeats from 0 till lower than 4, the place the sprite viewport strikes in 32 pixel increments throughout 4 rows.

Utilizing this logic, initialize the remainder of your animation variables.

_runLeftAnimation =
       spriteSheet.createAnimation(row: 1, stepTime: _animationSpeed, to: 4);
 
_runUpAnimation =
       spriteSheet.createAnimation(row: 2, stepTime: _animationSpeed, to: 4);
 
_runRightAnimation =
       spriteSheet.createAnimation(row: 3, stepTime: _animationSpeed, to: 4);
 
_standingAnimation =
       spriteSheet.createAnimation(row: 0, stepTime: _animationSpeed, to: 1);

Replace your movePlayer perform to assign the right animations primarily based on the participant’s route:

void movePlayer(double delta) {
   swap (route) {
     case Course.up:
       animation = _runUpAnimation;
       moveUp(delta);
       break;
     case Course.down:
       animation = _runDownAnimation;
       moveDown(delta);
       break;
     case Course.left:
       animation = _runLeftAnimation;
       moveLeft(delta);
       break;
     case Course.proper:
       animation = _runRightAnimation;
       moveRight(delta);
       break;
     case Course.none:
       animation = _standingAnimation;
       break;
   }
 }

Construct and run, and also you’ll see your playable character has come to life as they run in every route.

At this level, you could have the basics of a recreation in place: a playable character with person enter and motion. The subsequent step is so as to add a world to your participant to maneuver round in.

Including a World

Create a file known as world.dart in your parts folder. In world.dart, create a SpriteComponent known as World and cargo rayworld_background.png because the world sprite:

import 'package deal:flame/parts.dart';
 
class World extends SpriteComponent with HasGameRef {
 @override
 Future<void>? onLoad() async {
   sprite = await gameRef.loadSprite('rayworld_background.png');
   measurement = sprite!.originalSize;
   return tremendous.onLoad();
 }
}

Head again to RayWorldGame. Be certain that so as to add the World import.

import 'parts/world.dart';

Then add a World as a variable beneath Participant:

remaining World _world = World();

Now, add _world to your recreation originally of onLoad:

await add(_world);

You could load the world utterly earlier than loading your participant. When you add the world afterward, it is going to render on high of your Participant sprite, obscuring it.

Construct and run, and also you’ll see a lovely pixel panorama to your participant to run round in:

In your participant to traverse the world correctly, you’ll need the sport viewport to comply with the principle character at any time when they transfer. Historically, when programming video video games, this requires a plethora of sophisticated algorithms to perform. However with Flame, it’s simple!

First, add the import for utilizing a Rect variable on the high of the file. You’ll use this to calculate some bounds:

import 'dart:ui';

Now on the backside of your recreation onLoad methodology, set the participant’s preliminary place the middle of the world and inform the sport digicam to comply with _player:

_player.place = _world.measurement / 2;
   digicam.followComponent(_player,
       worldBounds: Rect.fromLTRB(0, 0, _world.measurement.x, _world.measurement.y));

Construct and run, and also you’ll see your world sprite pan as your participant strikes. As you’ve set the worldBounds variable, the digicam will even cease panning as you attain the sting of the world sprite. Run to the sting of the map and see for your self.

Congratulations!

Try to be happy with your self for getting this far. You’ve coated a few of the core parts wanted in any recreation dev’s repertoire.

Nonetheless, there’s one remaining ability it’s essential to be taught to have the ability to make a full recreation: Collision detection.

Including World Collision to Your Recreation

Creating Tile Maps

2-D recreation builders generally make use of tile maps. The approach entails creating art work to your recreation as a group of uniform tiles you may piece collectively nonetheless wanted like a jigsaw, then making a map you should utilize to inform your recreation engine which tiles go the place.

You may make tile maps as primary or as superior as you want. In a previous challenge, a recreation known as Pixel Man used a textual content file as a tile map that seemed one thing like this:

xxxxxxxxxxx
xbooooooox
xoooobooox
xoooooooox
xoooooboox
xxxxxxxxxxx

The sport engine would learn these information and exchange x’s with partitions and b’s with collectable objects, utilizing the tile map for each logic and art work functions.

Today, software program makes the method of making a tile map much more intuitive. RayWorld makes use of software program known as Tiled. Tiled is free software program that allows you to create your ranges with a tile set and add further collision layers in a graphical editor. It then generates a tile map written in JSON that may be simply learn in your recreation engine.

A tile map known as rayworld_collision_map.json already exists. You’ll use this JSON file so as to add collision objects into your recreation within the subsequent part. It seems to be like this within the Tiled editor:

The pink packing containers are the collision rectangles. You’ll use this information to create collision objects in Flame.

Creating World Collision in RayWorld

Add a file in your parts folder known as world_collidable.dart and create a category known as WorldCollidable:

import 'package deal:flame/collisions.dart';
import 'package deal:flame/parts.dart';
 
class WorldCollidable extends PositionComponent{
  WorldCollidable() {
    add(RectangleHitbox());
  }
}

Right here you outline a brand new class to include your world. It’s a sort of PositionComponent that represents a place on the display screen. It’s meant to signify every collidable space (i.e., invisible partitions) on the world map.

Open ray_world_game.dart. First add the next imports:

import 'parts/world_collidable.dart';
import 'helpers/map_loader.dart';
import 'package deal:flame/parts.dart';

Now create a technique in RayWorldGame known as addWorldCollision:

void addWorldCollision() async =>
     (await MapLoader.readRayWorldCollisionMap()).forEach((rect) {
       add(WorldCollidable()
         ..place = Vector2(rect.left, rect.high)
         ..width = rect.width
         ..peak = rect.peak);
     });

Right here, you employ a helper perform, MapLoader, to learn rayworld_collision_map.json, situated in your belongings folder. For every rectangle, it creates a WorldCollidable and provides it to your recreation.

Name your new perform beneath add(_player) in onLoad:

await add(_world);
add(_player);
addWorldCollision(); // add

Now to register collision detection. Add the HasCollisionDetection mixin to RayWorldGame. You’ll have to specify this if you’d like Flame to construct a recreation that has collidable sprites:

class RayWorldGame extends FlameGame with HasCollisionDetection

You’ve now added all of your collidable sprites into the sport, however proper now, you gained’t be capable of inform. You’ll want to include further logic to your participant to cease them from shifting once they’ve collided with one in all these objects.

Open participant.dart. Add the CollisionCallbacks mixin after with HasGameRef subsequent to your participant class declaration:

class Participant extends SpriteAnimationComponent with HasGameRef, CollisionCallbacks

You now have entry to onCollision and onCollisionEnd. Add them to your Participant class:

@override
void onCollision(Set<Vector2> intersectionPoints, PositionComponent different) {
  tremendous.onCollision(intersectionPoints, different);
  // TODO 1
}
 
@override
void onCollisionEnd(PositionComponent different) {
  tremendous.onCollisionEnd(different);
  // TODO 2
}

Create and add a HitboxRectangle to your Participant within the constructor. Like your WorldCollision parts, your participant wants a Hitbox to have the ability to register collisions:

Participant()
     : tremendous(
         measurement: Vector2.all(50.0),
       ) {
   add(RectangleHitbox());
 }

Add the WorldCollidable import above your class:

import 'world_collidable.dart';

Now, add two variables into your Participant class to assist monitor your collisions:

Course _collisionDirection = Course.none;
bool _hasCollided = false;

You possibly can populate these variables within the two collision strategies. Go to onCollision and exchange // TODO 1 with logic to gather collision info:

if (different is WorldCollidable) {
  if (!_hasCollided) {
    _hasCollided = true;
    _collisionDirection = route;
  }
}

Set _hasCollided again to false in onCollisionEnd, changing // TODO 2:

_hasCollided = false;

Participant now has all the data it must know whether or not it has collided or not. You should utilize that info to ban motion. Add these 4 strategies to your Participant class:

bool canPlayerMoveUp() {
  if (_hasCollided && _collisionDirection == Course.up) {
    return false;
  }
  return true;
}
 
bool canPlayerMoveDown() {
  if (_hasCollided && _collisionDirection == Course.down) {
    return false;
  }
  return true;
}
 
bool canPlayerMoveLeft() {
  if (_hasCollided && _collisionDirection == Course.left) {
    return false;
  }
  return true;
}
 
bool canPlayerMoveRight() {
  if (_hasCollided && _collisionDirection == Course.proper) {
    return false;
  }
  return true;
}

These strategies will test whether or not the participant can transfer in a given route by querying the collision variables you created. Now, you should utilize these strategies in movePlayer to see whether or not the participant ought to transfer:

void movePlayer(double delta) {
  swap (route) {
    case Course.up:
      if (canPlayerMoveUp()) {
        animation = _runUpAnimation;
        moveUp(delta);
      }
      break;
    case Course.down:
      if (canPlayerMoveDown()) {
        animation = _runDownAnimation;
        moveDown(delta);
      }
      break;
    case Course.left:
      if (canPlayerMoveLeft()) {
        animation = _runLeftAnimation;
        moveLeft(delta);
      }
      break;
    case Course.proper:
      if (canPlayerMoveRight()) {
        animation = _runRightAnimation;
        moveRight(delta);
      }
      break;
    case Course.none:
      animation = _standingAnimation;
      break;
  }
}

Rebuild your recreation and attempt to run to the water’s edge or right into a fence. You’ll discover your participant will nonetheless animate, however you gained’t be capable of transfer previous the collision objects. Attempt working between the fences or barrels.

Bonus Part: Keyboard Enter

As a result of RayWorld is constructed with Flutter, it will probably additionally run as an internet app. Typically, for internet video games, individuals wish to use keyboard enter as a substitute of a joypad. Flame has an interface known as KeyboardEvents you may override in your recreation object to obtain notification of keyboard enter occasions.

For this bonus part, you’ll hear for keyboard occasions for the up, down, left and proper arrows, and use these occasions to set the participant’s route. You’ll really use the instruments offered Flutter itself. Add the next imports:

import 'package deal:flutter/widgets.dart';
import 'package deal:flutter/providers.dart';

Now, in RayWorldGame, override the onKeyEvent methodology:

@override
KeyEventResult onKeyEvent(
    RawKeyEvent occasion,
    Set<LogicalKeyboardKey> keysPressed,
  ) {
    remaining isKeyDown = occasion is RawKeyDownEvent;
    Course? keyDirection;

  // TODO 1

  // TODO 2

  return tremendous.onKeyEvent(occasion, keysPressed);
}

Change // TODO 1 with logic to learn RawKeyEvent and set the keyDirection:

if (occasion.logicalKey == LogicalKeyboardKey.keyA) {
  keyDirection = Course.left;
} else if (occasion.logicalKey == LogicalKeyboardKey.keyD) {
  keyDirection = Course.proper;
} else if (occasion.logicalKey == LogicalKeyboardKey.keyW) {
  keyDirection = Course.up;
} else if (occasion.logicalKey == LogicalKeyboardKey.keyS) {
  keyDirection = Course.down;
}

Right here, you’re listening for key adjustments with the keys W, A, S and D and setting the corresponding motion route.

Now, exchange // TODO 2 with logic to alter the participant’s route:

if (isKeyDown && keyDirection != null) {
  _player.route = keyDirection;
} else if (_player.route == keyDirection) {
  _player.route = Course.none;
}

The participant’s route is being up to date if a key’s being pressed, and if a key’s lifted the gamers route is ready to Course.none if it’s the energetic route.

Launch your recreation on the net or an emulator, and also you’ll now be capable of run round utilizing the W, A, S and D keys in your keyboard.

The place to Go From Right here?

You possibly can obtain the finished challenge information by clicking the Obtain Supplies button on the high or backside of the tutorial.

You now have all of the instruments to make an entire 2-D recreation utilizing the Flame Engine. However why cease there? You would attempt including:

• Extra recreation UI: Incorporate UI parts akin to a participant well being bar, an assault button and a soar button. You would construct these utilizing a Flame element or a Flutter Widget.
• Enemies: Populate RayWorld with enemies akin to goblins or aggressive animals that would assault your participant.
• Totally different ranges: Load new world sprites and tile maps into your recreation because the participant leaves the realm.

Try the awesome-flame GitHub repository to see what video games have already been developed utilizing the Flame Engine and to learn another nice Flame tutorials. Be certain that to remain tuned to raywenderlich.com for extra nice recreation growth tutorials.