Flutter Flame: Collision Detection Explained

Once you’ve got a game loop and a moving player (covered in the beginner Flutter Flame tutorial), the next real milestone is making things react to each other – a player hitting a wall, a bullet hitting an enemy, a coin disappearing when collected. Flame handles this through a dedicated collision-detection system, not manual bounding-box math you write yourself.

Turning On Collision Detection

Collision detection isn’t active by default – your game class needs the HasCollisionDetection mixin, and any component that should respond to a collision needs the CollisionCallbacks mixin plus at least one hitbox child:

class BoxRunnerGame extends FlameGame with HasCollisionDetection {
  @override
  Future<void> onLoad() async {
    await add(Player());
    await add(Wall());
  }
}

Without HasCollisionDetection on the game class, hitboxes still exist but nothing ever checks them against each other – a very common “why isn’t my collision firing” mistake.

Adding Hitboxes

Flame ships three hitbox shapes: RectangleHitbox, CircleHitbox, and PolygonHitbox (for custom convex shapes). A hitbox is added as a child component, usually inside onLoad():

class Player extends RectangleComponent with CollisionCallbacks {
  Player() : super(size: Vector2(40, 40), paint: Paint()..color = const Color(0xFF3DDC84));

  @override
  Future<void> onLoad() async {
    await add(RectangleHitbox());
  }
}

class Wall extends RectangleComponent with CollisionCallbacks {
  Wall({required super.position}) : super(size: Vector2(20, 200), paint: Paint()..color = const Color(0xFF888888));

  @override
  Future<void> onLoad() async {
    await add(RectangleHitbox());
  }
}

By default a hitbox matches the component’s own size and position. If you need a hitbox smaller than the visible sprite (a common trick to make collisions feel fairer – give the player a bit of visual overlap before it “counts”), pass an explicit size and position to the hitbox itself instead of relying on the parent’s.

Responding to a Collision

With both mixins and hitboxes in place, override onCollisionStart, onCollision, or onCollisionEnd on the component that needs to react. Use Dart’s is check on the other component to tell what you hit:

class Player extends RectangleComponent with CollisionCallbacks {
  // ...onLoad as above...

  @override
  void onCollisionStart(Set<Vector2> intersectionPoints, PositionComponent other) {
    super.onCollisionStart(intersectionPoints, other);
    if (other is Wall) {
      // stop the player dead instead of letting it overlap the wall
      velocity = Vector2.zero();
    } else if (other is Coin) {
      other.removeFromParent();
      score += 10;
    }
  }

  @override
  void onCollisionEnd(PositionComponent other) {
    super.onCollisionEnd(other);
    if (other is HazardZone) {
      isInDanger = false;
    }
  }
}

onCollisionStart fires once, the instant two hitboxes begin overlapping. onCollision fires every single frame they continue to overlap (useful for continuous damage-over-time effects, but easy to accidentally spam logic in if you only meant to react once – that’s what onCollisionStart is for). onCollisionEnd fires once, the frame they stop overlapping.

Stopping Movement Precisely, Not Just Detecting It

A common beginner bug: setting velocity to zero in onCollisionStart still lets the player visually overlap the wall for one frame before stopping, because the position update that caused the overlap already happened. For a solid “can’t walk through walls” feel, push the component back out along the shortest axis using the intersection points Flame gives you, rather than only zeroing velocity:

@override
void onCollisionStart(Set<Vector2> intersectionPoints, PositionComponent other) {
  super.onCollisionStart(intersectionPoints, other);
  if (other is Wall && intersectionPoints.isNotEmpty) {
    final mid = (intersectionPoints.first + intersectionPoints.last) / 2;
    final pushDirection = (position - mid).normalized();
    position += pushDirection * 2; // small nudge out of the overlap
    velocity = Vector2.zero();
  }
}

Performance: Don’t Check Everything Against Everything

Flame’s default collision detection is broad-phase-optimized (it won’t naively check every pair every frame), but with hundreds of moving hitboxes it still adds up. Two practical levers:

  • Mark static, never-moving hitboxes (walls, floor) with isSolid = false isn’t the right flag here – instead give them a CollisionType.passive via hitbox.collisionType = CollisionType.passive, which tells Flame’s broad-phase algorithm this hitbox never needs to be checked against other passive hitboxes, only against active ones.
  • Keep hitbox shapes simple. A CircleHitbox is cheaper to test than a PolygonHitbox – don’t reach for a custom polygon unless a rectangle or circle genuinely doesn’t fit the shape.

Frequently Asked Questions

Why isn’t onCollisionStart firing at all?

The two most common causes: the game class is missing HasCollisionDetection, or one of the two components is missing a hitbox child (having CollisionCallbacks alone does nothing without an actual hitbox to detect with).

Should I use onCollision or onCollisionStart for damage?

For a one-time effect (losing a life, picking up a coin), use onCollisionStart. For continuous damage while standing in a hazard (lava, a damage zone), use onCollision, but add your own cooldown timer inside it – otherwise it fires every frame (60 times a second) and drains health instantly.

Can two PolygonHitboxes collide if one is concave?

No – Flame’s PolygonHitbox only supports convex shapes. For a concave shape (an L-shape, for example), compose it out of two or more convex hitboxes (e.g. two RectangleHitboxes) added as separate children to the same component instead of one polygon.