In Flame, everything is a component in a tree. Game objects live in a World, and a CameraComponent looks at that world through a window. Move the camera and the world appears to scroll, without touching a single object.
This is for Flutter developers building their first side-scroller or any level bigger than the screen. It uses flame 1.38.2, the latest stable version in October 2026.
In short:
- A parent updates and draws its children, like Flutter widgets.
- Add game objects to
world. Add the HUD tocamera.viewport. prioritysets draw order. Higher draws on top.camera.follow(target)andsetBoundsgive you a scrolling level.
Components form a tree that runs itself
Every object extends Component. You attach children with the children: argument or with add and addAll, and Flame calls update and render down the tree for you. Most visible things extend PositionComponent, which adds position, size, scale, angle and anchor, as described on the components page.
A child's position is relative to its parent's top-left corner, whatever the parent's anchor is. Flame's docs call mixing this up a common pitfall.
Lifecycle runs onLoad, then onMount
Three callbacks matter. onLoad runs once and may be async, so load images there. onMount runs each time the component joins a tree. onRemove runs before it leaves.
For components, onLoad runs before onGameResize. For the game class itself, the order is reversed so sizes are known before assets load. Do not initialise late final fields in onMount, because it can run more than once.
Removal is queued until the end of the frame. Code that counts what is left must skip components where isRemoving is true.
Priority decides who draws on top
Each component has an integer priority, default 0. Among siblings, a higher value draws later, so it appears in front. Set it in the constructor, or assign a new value and Flame reorders before the next render.
final shadow = RectangleComponent(priority: -1);
final hero = RectangleComponent(priority: 1);
A world holds objects and a camera looks at it
FlameGame creates one World called world and one CameraComponent called camera. A component added straight to the game is not seen through the camera, so it will not line up with the rest.
By default the camera shows world position (0, 0) at the centre of the screen. For a fixed field with the origin at the top-left, pass CameraComponent.withFixedResolution to the game and set camera.viewfinder.anchor = Anchor.topLeft, as in the dodge game.
A game can have several worlds. Switching a camera from world A to world B swaps the view without unmounting A.
The viewport holds the HUD, the viewfinder moves with the world
Put anything that must stay still on screen in the viewport, and move or zoom the view through the viewfinder.
| Part | What it is | Put here |
|---|---|---|
camera.viewport |
The window on screen | Score, lives, buttons that stay still |
camera.viewfinder |
Where the camera looks, plus zoom | Effects that move or zoom the view |
camera.backdrop |
Drawn behind the world | A static background |
Children of the viewport appear in front of the world and never move. The default viewport fills the game canvas. FixedResolutionViewport keeps the aspect ratio with black bars.
Follow, bounds and culling make a scrolling level
One example shows follow and bounds, and the culling helpers come after it. A square moves right through a 2000-unit level while the camera tracks it and keeps its centre inside the bounds.
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/experimental.dart';
import 'package:flame/game.dart';
import 'package:flutter/material.dart';
class LevelGame extends FlameGame {
@override
Future<void> onLoad() async {
final hero = RectangleComponent(size: Vector2.all(40),
anchor: Anchor.center, paint: Paint()..color = Colors.cyan);
world.add(hero);
hero.add(MoveEffect.to(Vector2(1900, 0), EffectController(speed: 150)));
camera.follow(hero, horizontalOnly: true);
camera.setBounds(Rectangle.fromLTRB(0, -100, 2000, 100));
camera.viewport.add(FpsTextComponent(position: Vector2(8, 8)));
}
}
follow accepts a maxSpeed, plus horizontalOnly and verticalOnly. setBounds keeps the camera's centre inside a shape in world coordinates. In Flame 1.38.2 the Rectangle class comes from package:flame/experimental.dart. The FPS counter sits in the viewport, so it stays in the corner.
To skip off-screen work, camera.canSee(component) tells you whether a component overlaps the visible area, and camera.visibleWorldRect gives that area as a Rect.
Typed references remove casts
Four helpers keep code honest. The two reference mixins and ParentIsA fail fast in debug builds when the type is wrong.
- Mix in
HasGameReference<MyGame>to get a typedgame. - Mix in
HasWorldReference<MyWorld>to get a typedworld. - Mix in
ParentIsA<Parent>to force a parent type. - Give a component a
ComponentKey.named('player')and find it later withfindByKey.
You can also give the game a typed world with FlameGame<MyWorld>, so world needs no cast.
Flip the camera axis in 10 minutes
Paste the level example into a new Flame project, then change horizontalOnly: true to verticalOnly: true and watch what the camera does. Then move to menus, HUD and overlays to put a real score on screen.