To detect a hit in Flame, add the HasCollisionDetection mixin to your game, give each object a child hitbox such as RectangleHitbox(), and add the CollisionCallbacks mixin to the component that should react. Override onCollisionStart to run code once per contact.
This is for Flutter developers whose game has a player, pickups or enemies. It targets flame 1.38.2, the latest stable version in October 2026.
In short:
- Hitboxes come in three shapes: rectangle, circle and convex polygon.
- Mark hitboxes passive unless they must test against each other.
onCollisionStartfires once.onCollisionfires every frame.- Fast objects can skip through thin ones. Flame does not stop this.
A coin pickup needs three pieces
The running example is a player square that collects coins. The game turns collisions on.
class CoinGame extends FlameGame with HasCollisionDetection {
int score = 0;
}
Each coin gets a circular hitbox. The player gets the callbacks.
class Coin extends CircleComponent {
Coin(Vector2 at) : super(position: at, radius: 10,
children: [CircleHitbox(collisionType: CollisionType.passive)]);
}
class Player extends RectangleComponent
with CollisionCallbacks, HasGameReference<CoinGame> {
Player() : super(size: Vector2.all(40), children: [RectangleHitbox()]);
@override
void onCollisionStart(Set<Vector2> points, PositionComponent other) {
super.onCollisionStart(points, other);
if (other is Coin) {
other.removeFromParent();
game.score++;
}
}
}
A hitbox with no arguments fills its parent. The other argument is the component you touched, so is checks tell you what it was. Flame calls the callback on both components if both have the mixin.
Active and passive types decide what gets tested
Per Flame's collision docs, each hitbox has a collisionType. Active is the default.
| Type | Tests against |
|---|---|
active |
Active and passive hitboxes |
passive |
Active hitboxes only |
inactive |
Nothing |
Two passive hitboxes are never tested against each other. So make walls, coins and bricks passive, and keep only the moving thing that must notice them active.
In a bullet game, Flame's performance page notes that its Rogue Shooter example makes enemies passive rather than bullets. Choose by asking which side never needs to detect its own kind.
Start fires once, the plain callback fires every frame
There are three callbacks: onCollisionStart, onCollision and onCollisionEnd. Start and end run once per contact. onCollision runs on every frame the shapes overlap, and the docs say it is also called at the start.
Use onCollisionStart for pickups, damage and sounds. Use onCollision only for continuous effects, like pushing a box out of a wall. In the dodge game, onCollisionStart is the right choice, because a hit should restart the round once.
When one object hits two things in a frame, callbacks come in an effectively random order. The docs suggest saving the hits in a list and resolving them together when collisionsCompletedNotifier fires.
Hitbox shapes: rectangle, circle, convex polygon
Use RectangleHitbox, CircleHitbox or PolygonHitbox. A polygon must be convex, or you will most likely run into problems. You can add several hitboxes to one component, and the docs give a snowman with a hat as three circles and two rectangles.
Hitboxes are hollow by default, so one can sit fully inside another without a collision. Set isSolid = true if you want the inside to count. Leave a play-area border hollow: a ball inside it then only touches the border when its outline crosses an edge.
To see your hitboxes, set renderShape = true on them while testing, as Flame's own example does.
Tunneling lets fast things pass through walls
Flame's docs say the built-in system ignores collisions between hitboxes that overshoot each other. That happens when objects move very fast, or when dt is large, for example after the app was in the background.
A rule of thumb from simple arithmetic: distance per frame is speed times dt. At 600 units per second and 60 frames per second, an object moves 10 units a frame. A wall 4 units thick can be skipped. Keep per-frame movement below the thinnest hitbox, or make walls thicker than they look.
Big maps may need a quad tree
The default broad phase is sweep and prune. For large fields with more than about a hundred collidable components, Flame offers HasQuadTreeCollisionDetection and an initializeCollisionDetection call with the map size.
The docs add a caution: always measure. A quad tree can be much slower than the default in some games.
Rays answer "what can I see?"
With HasCollisionDetection, collisionDetection.raycast(Ray2(...)) returns the first hit of a ray, or null. raycastAll fans many rays from one point, which suits line-of-sight and light effects. Each result gives the hitbox, the hit point, the surface normal and the reflected ray.
Test it in 10 minutes
Add a Coin at a fixed position, move the player with a drag, and print the score. Then delete the removeFromParent() line, switch to onCollision, and watch the score climb every frame while the two overlap. Next, read Forge2D physics if you need bouncing and stacking, which hitboxes alone do not do.