flame 0.8.1

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 88

🔥 flame

A minimalist Flutter game engine.

Now audio works on iOS, thanks to @feroult!

Roadmap

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

These features are things that I saw evolving into games using flutter that I believe should be introduced into the engine:

  • Rotation around sprint center (currently it rotates around the corner)
  • Find an unobtrusive compromise to automatically call Flame.util.enableEvents(); and fix the --supermixin problem
  • Think of a good structure to add tests (might be hard to do)

Goals

The goal of this project is to provided a minimalist 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, audio, a game loop and a component/object system.

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

Usage

Just drop it in your pubspec.yaml:

dependencies:
  flame: ^0.6.1

And start using it! There is a very good QuickStart tutorial here, with everything you need to know!

Structure

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

An example:

  Flame.audio.play('explosion.mp3');

  Flame.images.load('player.png');
  Flame.images.load('enemy.png');

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:

flutter:
  assets:
    - 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 audio, it's really simple! Just run, at any moment:

    import 'package:flame/flame.dart';

    Flame.audio.play('explosion.mp3');

Or, if you prefer:

    import 'package:flame/audio.dart';

    Audio audio = new Audio();
    audio.play('explosion.mp3');

You must have an appropriate folder structure and add the files to the pubspec.yaml file, as explained above.

It has to be an MP3 or a OGG file (tested with WAV and it didn't work).

This uses the audioplayers lib, in order to allow playing multiple sounds simultaneously (crucial in a game).

If you want to play indefinitely, just use loop:

    Flame.audio.loop('music.mp3');

Beware: in order to use loop or any platform binding callbacks, you need to call this utility function first thing on your application code:

    Flame.util.enableEvents();

TODO: find a way to know if events are enabled and call this automatically somehow.

Finally, you can pre-load your audios. Audios need to be stored in the memory the first time they are requested; therefore, the first time you play each mp3 you might get a delay. In order to pre-load your audios, just use:

    Flame.audio.load('explosion.mp3');

You can load all your audios in beginning so that they always play smoothly.

There's lots of logs; that's reminiscent of the original AudioPlayer plugin. Useful while debug, but afterwards you can disable them with:

    Flame.audio.disableLog();

Images

Flutter has a collection of types related to images, and converting everything properly form a local asset to the Image that can be drawn on Canvas is a small pain.

This module allows you to obtain an Image that can be drawn on a Canvas using the drawImageRect method.

Just use:

    import 'package:flame/flame.dart';

    // inside an async context
    Image image = await Flame.images.load('player.png');
    
    // or
    Flame.images.load('player.png').then((Image image) {
      var paint = new Paint()..color = new Color(0xffffffff);
      var rect = new Rect.fromLTWH(0.0, 0.0, image.width.toDouble(), image.height.toDouble());
      canvas.drawImageRect(image, rect, rect, paint);
    });

Similarly to Audio, you can instantiate your own copy of Image:

    Image image = await new Images().load('asd');

If you are using the Component module, you probably should not use this one; use SpriteComponent instead!

You must have an appropriate folder structure and add the files to the pubspec.yaml file, as explained above.

It has to be a PNG file. It can have transparency.

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 and angle to your Components, as well as some useful methods like distance and angleBetween.

And finally, the most complete implementation, SpriteComponent, which makes rendering sprites really easy:

    import 'package:flame/component.dart';

    const size = 128.0; // size that will be drawn on the screen
    // it will resize the image according
    var player = new SpriteComponent.square(size, 'player.png');
    // the image sprite will be loaded by the Images module
    
    // screen coordinates
    player.x = ...
    player.y = ...
    player.angle = ...
    // tip: use canvas.translate to convert coordiantes
    
    player.render(canvas); // it will render if the image is ready

You can also use the rectangle constructor if you want a non-square sprite:

    var object = new SpriteComponent.rectangle(width, height, imagePath);

Game Loop

The Game Loop module is a simple abstraction over the game loop concept.

Extend the abstract class Game and just implement render and update; they will be called properly once you start.

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

    class MyGame extends Game {
        var objs = <Component>[];

        update(double t) {
            components.forEach((Component obj) => obj.update(t));
        }

        render(Canvas canvas) {
            components.forEach((Component obj) => obj.render(canvas));
        }
    }    
   
    var game = new MyGame();
    game.objs.add(new SpriteObject( ... ));
    game.start();

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.

Util

This module will incorporate a few utility functions that are good to have in any game environment. For now, there is only two:

  • initialDimensions : returns a Future with the dimension (Size) of the screen. This has to be done in a hacky way because of the reasons described in the code.
  • enableEvents : this is also a hack that allows you to use the Service bindings with platform specific code callbacks. Normally they would only work if you called runApp with a widget, since we draw on canvas for the game, that's never called. This makes sure it works.
  • text : helper to write text to the Canvas; the methods are a bit convoluted, this might give a hand.

Ideas are appreciated!

Credits

[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

1. Depend on it

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


dependencies:
  flame: "^0.8.1"

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter packages get

Alternatively, your editor might support packages 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';
        
Version Uploaded Documentation Archive
0.8.1 Dec 22, 2017 Go to the documentation of flame 0.8.1 Download flame 0.8.1 archive
0.8.0 Dec 22, 2017 Go to the documentation of flame 0.8.0 Download flame 0.8.0 archive
0.6.2 Nov 15, 2017 Go to the documentation of flame 0.6.2 Download flame 0.6.2 archive
0.6.1 Nov 13, 2017 Go to the documentation of flame 0.6.1 Download flame 0.6.1 archive
0.6.0 Nov 12, 2017 Go to the documentation of flame 0.6.0 Download flame 0.6.0 archive
0.5.0 Oct 29, 2017 Go to the documentation of flame 0.5.0 Download flame 0.5.0 archive
0.4.0 Oct 22, 2017 Go to the documentation of flame 0.4.0 Download flame 0.4.0 archive
0.3.0 Oct 22, 2017 Go to the documentation of flame 0.3.0 Download flame 0.3.0 archive
0.2.0 Oct 22, 2017 Go to the documentation of flame 0.2.0 Download flame 0.2.0 archive
0.1.0 Oct 22, 2017 Go to the documentation of flame 0.1.0 Download flame 0.1.0 archive

All 11 versions...

Analysis

This feature is new.
We welcome feedback.
More details: scoring.

We analyzed this package, and provided a score, details, and suggestions below.

  • completed on Feb 3, 2018
  • Dart: 2.0.0-dev.20.0
  • pana: 0.10.1
  • Flutter: 0.0.22

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
76 / 100
Health:
Code health derived from static analysis. [more]
99 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100 / 100
Overall score:
Weighted score of the above. [more]
88

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Suggestions

  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Package is pre-v1 release.

    While there is nothing inherently wrong with versions of 0.*.*, it usually means that the author is still experimenting with the general direction API.

  • Maintain an example.

    Create a short demo in the example/ directory to show how to use this package. Common file name patterns include: main.dart, example.dart or you could also use flame.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.13.0 <2.0.0
audioplayers ^0.4.0 0.4.1
box2d ^0.3.0 0.3.0 0.4.0
flutter 0.0.0
path_provider ^0.2.1+1 0.2.2 0.3.1
Transitive dependencies
async 2.0.3
charcode 1.1.1
collection 1.14.5
convert 2.0.1
crypto 2.0.2+1
http 0.11.3+16
http_parser 3.1.1
meta 1.1.1 1.1.2
path 1.5.1
sky_engine 0.0.99
source_span 1.4.0
string_scanner 1.0.2
typed_data 1.1.4 1.1.5
uuid 0.5.3
vector_math 2.0.5
Dev dependencies
test 0.12.24+8