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 to camera.viewport.
  • priority sets draw order. Higher draws on top.
  • camera.follow(target) and setBounds give 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.

  1. Mix in HasGameReference<MyGame> to get a typed game.
  2. Mix in HasWorldReference<MyWorld> to get a typed world.
  3. Mix in ParentIsA<Parent> to force a parent type.
  4. Give a component a ComponentKey.named('player') and find it later with findByKey.

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.

Sources and further reading