illume
A Widget-based Game Engine for Flutter
Illume is a simple Flutter game engine which uses widgets to create game objects instead of sprites in normal game engines. This allows the app and game part to be quite integrated and use a lot of common components without needing graphics work to create sprites and backgrounds (which was honestly my main motivation, since I don't know anything about graphic design). It's also quite easy to create and manage the game state as shown in the features ahead. A lot of functionality still needs to be implemented including physics - only normal box-based collision is currently implemented.
Some parts were inspired by other game engines, primarily Flame.
DISCLAIMER: Since widgets are heavier than sprites drawn on a canvas, this engine is going to be less performant than others. It is in a very early stage and I plan to add a lot of features but this is primarily due to my interest in having widget-based game engines -- any serious game development should still be carried out with more mature engines like Flame. This is just meant as an experiment to satisfy my curiosity. I quite like - and still heavily use the main Flutter game engines whose development teams I respect a lot.
Features
Use Widgets directly to build your game objects
class FlappyWidget extends GameObject {
@override
Widget build(BuildContext context) {
return Container(
color: Colors.blue,
child: const Text('Demo'),
);
}
@override
void init() {}
@override
void onCollision(List<Collision> collisions) { }
@override
void onScreenSizeChange(Vector2 size) {}
@override
void update(Duration delta) {}
//...
}
Easy game development without large separation between widgets and games
You can add a game to your app simply by adding an Illume widget and an IllumeController. (More info given in usage section)
class _MyHomePageState extends State<MyHomePage> {
IllumeController gameController = IllumeController();
FlappyWidget flappyWidget = FlappyWidget();
@override
void initState() {
super.initState();
gameController.startGame();
gameController.gameObjects.add(flappyWidget);
}
@override
Widget build(BuildContext context) {
return Scaffold(
body: Illume(
illumeController: gameController,
),
);
}
}
// Definition of game object given later
IllumeController allows easy manipulation of game state
IllumeController gameController = IllumeController();
gameController.startGame();
gameController.gameObjects.add(DemoObject());
gameController.stopGame();
// etc
The controller is also available for use in all game objects so no need for an abundance of callbacks.
Collision detection
Collision detection is enabled by default for all objects which can be turned off. Every object is notified of collisions as well as given the Rect of intersection so collisions can be better understood. This is a very early prototype so no complex physics (Box2d-ish) exist but I hope to add this in the future.
class FlappyWidget extends GameObject {
//...
@override
void onCollision(List<Collision> collisions) {
// This gives a list of objects which are colliding with this one
// as well as the rect of intersection.
}
//...
}
Gesture Detection
This is technically NOT a feature of illume since we can use the default Flutter gesture detecting widgets like the GestureDetector to power our apps. Check the example provided in the repo for more but here is a short demo:
@override
Widget build(BuildContext context) {
return GestureDetector(
onTap: () {
flappyWidget.jump();
},
child: Scaffold(
appBar: AppBar(
title: Text('Illume Demo'),
),
body: Illume(
illumeController: gameController,
),
),
);
}
Usage
Step 1
Add the dependency first:
dependencies:
illume: ^0.1.0
Step 2
Add the Illume widget and associated IllumeController wherever you need to create a game:
IllumeController gameController = IllumeController();
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
title: Text('Illume Demo'),
),
body: Illume(
illumeController: gameController,
),
);
}
Step 3
Define your GameObject by extending the class:
class FlappyWidget extends GameObject {
var velocity = 0.0;
var acceleration = 0.2;
@override
Widget build(BuildContext context) {
return Container(
color: Colors.blue,
child: const Text('Demo'),
);
}
@override
void init() {
size = Vector2.all(50);
alignment = GameObjectAlignment.center;
position = (gameSize / 2);
}
@override
void onCollision(List<Collision> collisions) {
illumeController.stopGame();
}
@override
void onScreenSizeChange(Vector2 size) {
// This is a quick demo but you really should shift your positions in a
// real world app or at least lock orientation.
}
@override
void update(Duration delta) {
position += Vector2(0, velocity);
velocity = velocity + acceleration;
}
void jump() {
velocity = -5;
}
}
Note: In the object there are various properties -
gameSizegives the max size for the game.alignmentallows you to align the center to the center of the widget or the top left corner of the widget.positionis the position of the widget.sizeis the size of the widget.illumeControlleris the game controller for the game.
Step 4
Add the object to the game and start the game:
FlappyWidget flappyWidget = FlappyWidget();
@override
void initState() {
super.initState();
gameController.startGame();
gameController.gameObjects.add(flappyWidget);
}
Check out the full example for the demo flappy bird game (This is a very basic demo for now, I'll add a far better one later).
7.3k Jan 8, 2023
67 Dec 24, 2022
72 Dec 21, 2022
9 Dec 13, 2022
1 Dec 28, 2021
10 Oct 26, 2022
3 Feb 3, 2022
3 Feb 17, 2022
2 Mar 22, 2022