Draw the score as a TextComponent inside camera.viewport, so it stays fixed while the world moves. Draw menus, pause screens and Game Over cards as ordinary Flutter widgets using Flame overlays: name each one in overlayBuilderMap, then switch it on from the game with overlays.add('name').
This is for Flutter developers whose Flame game plays but has no score or menu yet. It uses flame 1.38.2, the latest stable version in October 2026. The running example extends the dodge game.
In short:
- Put the HUD in
camera.viewport, not in the world. - Use overlays for menus, buttons and text fields.
- Create the game with
GameWidget.controlledso rebuilds keep it. - Update text only when its value changes.
Draw the score in the viewport
Children of the viewport are drawn in front of the world and do not move with the camera. That makes it the place for a score, lives or a fuel bar.
class Score extends TextComponent with HasGameReference<DodgeGame> {
Score() : super(position: Vector2(16, 16), textRenderer: TextPaint(
style: const TextStyle(color: Colors.white, fontSize: 24)));
int _shown = -1;
@override
void update(double dt) {
if (game.score == _shown) return;
_shown = game.score;
text = 'Score $_shown';
}
}
// in onLoad: camera.viewport.add(Score());
Assigning text makes the component lay out its text again. So assign only when the value changed, as the guard does. In the GrowApps game starter, the score, level and lives readouts use the same guard, plus a FpsTextComponent in the corner.
Use a Flutter overlay for buttons
A TextComponent is fine for a number. For a button, a font, a layout or an input field, use a real widget. Flame's overlays page lets you show any widget over the game by name.
GameWidget<DodgeGame>.controlled(
gameFactory: DodgeGame.new,
overlayBuilderMap: {
'gameOver': (context, game) => Center(
child: ElevatedButton(
onPressed: game.restart,
child: const Text('Play again'),
),
),
},
)
The map key is the overlay's name, and the builder receives your typed game. initialActiveOverlays: ['menu'] shows one at start, after loading.
Switch overlays from the game
Four methods cover it: overlays.add('name'), overlays.remove('name'), overlays.toggle('name') and overlays.setActive('name', active: true). Note that active: is a named argument. overlays.isActive('name') reads the state. A second argument priority on add decides which overlay sits on top.
For Game Over, pause the world and show the card:
void gameOver() {
pauseEngine();
overlays.add('gameOver');
}
void restart() {
overlays.remove('gameOver');
world.removeAll(world.children.query<Rock>().toList());
resumeEngine();
}
pauseEngine stops updates and renders. resumeEngine restarts them. A game also pauses on its own when the app goes to the background, which you can turn off with pauseWhenBackgrounded = false.
Keep the game alive across rebuilds
If you build GameWidget(game: DodgeGame()) inside build, every rebuild makes a fresh game. Flame's docs warn about this. GameWidget.controlled(gameFactory: ...) creates the game once and keeps it. Alternatively, create the game in a State field.
Share state with ValueNotifier
An overlay that shows "Final score 120" needs the game's score. The simple route: make score a ValueNotifier<int> on the game, and read game.score.value in the Score component too. The overlay reads game.score.value when it opens. If an overlay stays open while the value changes, wrap it in a ValueListenableBuilder. The GrowApps game starter keeps score, lives and level in ValueNotifiers and its menus read them this way.
Block taps from falling through
A tap on an overlay should not also reach the field. Wrap the overlay in a GestureDetector with behavior: HitTestBehavior.opaque, and start the game from its onTap. In the starter, every title and end screen works this way.
Choose HUD or overlay
Numbers and in-game controls go in the viewport. Anything with a real button or layout is an overlay.
| Element | Use | Why |
|---|---|---|
| Score, lives, timer | Viewport TextComponent |
Cheap, stays fixed on screen |
| Joystick, in-game buttons | Viewport components | Part of the play field |
| Title, pause, settings | Overlay | Real buttons, fonts, layout |
| Game Over with retry | Overlay | Needs a button |
Add a Game Over card in 10 minutes
Add a score field (reset it in restart()), the Score component and the gameOver overlay above to the dodge game. Call gameOver() instead of restart() in the player's collision callback. Then read input in Flame to add a pause key.