A game with no score and no way to lose isn’t really a game yet – it’s a toy. This guide adds both to the moving box from our Flutter Flame beginner tutorial: a live score display, a game-over condition, and a restart flow, using Flame’s own overlay system rather than trying to build pause/restart UI out of game components.
Tracking and Displaying Score
Keep score as a plain property on your game class, and update a TextComponent whenever it changes – there’s no need for a separate state-management layer inside Flame itself.
class MyGame extends FlameGame with HasCollisionDetection {
int score = 0;
late TextComponent scoreText;
@override
Future<void> onLoad() async {
scoreText = TextComponent(
text: 'Score: 0',
position: Vector2(16, 16),
textRenderer: TextPaint(
style: const TextStyle(fontSize: 24, color: Colors.white),
),
);
add(scoreText);
}
void addScore(int points) {
score += points;
scoreText.text = 'Score: $score';
}
}
Call addScore() from wherever a scoring event happens – typically inside a collectible component’s onCollisionStart, covered in our collision detection guide.
Detecting Game Over
A game-over condition is just a check you run somewhere – most often inside a collision callback (hitting an enemy) or an update() method (health reaching zero, a timer running out). Keep a boolean flag so you don’t trigger it twice:
class MyGame extends FlameGame with HasCollisionDetection {
bool isGameOver = false;
void triggerGameOver() {
if (isGameOver) return;
isGameOver = true;
pauseEngine();
overlays.add('GameOver');
}
}
pauseEngine() is a real FlameGame method that stops the update loop entirely – components stop moving, animations freeze, and any logic inside update() stops running. It does not remove anything from the screen; whatever was drawn stays visible underneath your overlay.
Building the Game-Over Overlay
Flame overlays are plain Flutter widgets, registered on your GameWidget and shown/hidden by name via game.overlays.add()/remove(). This is the correct way to show UI during a pause – they render independently of the paused game loop.
GameWidget<MyGame>(
game: MyGame(),
overlayBuilderMap: {
'GameOver': (context, game) {
return Center(
child: Container(
padding: const EdgeInsets.all(24),
color: Colors.black87,
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
Text(
'Game OvernScore: ${game.score}',
textAlign: TextAlign.center,
style: const TextStyle(color: Colors.white, fontSize: 28),
),
const SizedBox(height: 16),
ElevatedButton(
onPressed: game.restart,
child: const Text('Play Again'),
),
],
),
),
);
},
},
)
Restarting Cleanly
Resetting a game is about resetting your own state – Flame has no built-in “reset” button, because it has no idea what counts as your game’s starting state. Reset every piece you’ve added explicitly, then resume the engine:
void restart() {
isGameOver = false;
score = 0;
scoreText.text = 'Score: 0';
player.position = Vector2(100, 100); // back to the start position
overlays.remove('GameOver');
resumeEngine();
}
If your game has more moving parts – enemies, collectibles, a scrolling background – reset each of their positions/states here too, or simply remove and re-add fresh instances of components that don’t need to persist across a run.
Frequently asked questions
Does pauseEngine() stop input too?
Yes, for anything tied to the update loop – components stop moving and reacting, since update() itself stops running. Overlays are unaffected because they’re plain Flutter widgets outside the paused game loop, which is exactly why the game-over UI above works correctly while paused.
How do you detect game-over from a collision?
Implement onCollisionStart on your player component (via the CollisionCallbacks mixin from our collision detection guide), check whether the other component is an enemy or hazard type, and call triggerGameOver() from inside that callback.
Does resumeEngine() reset the score?
No – resumeEngine() only resumes the update loop. Score, positions, and every other piece of game state stay exactly as they were when you paused. Resetting state is your own responsibility, handled in a dedicated restart() method like the one above.