Flame Engine Quick Reference
Component Lifecycle
onLoad() → onMount() → update(dt)/render(canvas) → onRemove()
Method Timing Purpose
onLoad()
Once, async Resource loading, initialization
onMount()
On tree addition Set parent/game references
update(dt)
Every frame State update (dt = delta seconds)
render(canvas)
Every frame Draw to screen
onRemove()
On removal Cleanup
Core Classes
Class Purpose Key Properties/Methods
FlameGame
Game root pauseEngine() , resumeEngine() , overlays
World
Hosts game components add() , children
Component
Base component add() , remove() , children , parent
PositionComponent
Position/size/rotation position , size , angle , anchor , scale
SpriteComponent
Static sprite sprite , paint
SpriteAnimationComponent
Animation animation , playing
CameraComponent
Camera control follow() , moveTo() , setBounds() , viewport
Shape Components
-
RectangleComponent
-
Rectangle
-
CircleComponent
-
Circle
-
PolygonComponent
-
Polygon
Collision Detection
Enable
// Add to Game or World class MyGame extends FlameGame with HasCollisionDetection {}
Hitbox Types
Hitbox Purpose
RectangleHitbox
Rectangular collision area
CircleHitbox
Circular collision area
PolygonHitbox
Polygon (convex only)
ScreenHitbox
Screen boundaries
CompositeHitbox
Composite hitbox
Collision Callbacks
class MyComponent extends PositionComponent with CollisionCallbacks { @override void onCollisionStart(Set<Vector2> points, PositionComponent other) {}
@override void onCollision(Set<Vector2> points, PositionComponent other) {}
@override void onCollisionEnd(PositionComponent other) {} }
Collision Type (Performance)
-
CollisionType.active
-
Checks against all hitboxes
-
CollisionType.passive
-
Only checked by active (better performance)
-
CollisionType.inactive
-
Ignored
Effects System
Effect Purpose Example
MoveEffect.to()
Move to target Character movement
MoveEffect.by()
Move by offset Relative movement
RotateEffect.to()
Rotate to angle Direction change
ScaleEffect.to()
Change size Zoom in/out
ColorEffect
Color/opacity Hit effect
SequenceEffect
Sequential execution Complex animation
OpacityEffect
Opacity Fade in/out
Effect Controller
MoveEffect.to( Vector2(100, 100), EffectController(duration: 1.0, curve: Curves.easeInOut), );
Camera & World
Camera Methods
Method Purpose
follow(target)
Follow target
moveTo(position)
Move to coordinates
moveBy(offset)
Move by offset
stop()
Stop movement
setBounds(shape)
Limit camera movement
canSee(component)
Check visibility
Viewport Types
Viewport Purpose
MaxViewport
Expand to max space (default)
FixedResolutionViewport
Fixed resolution + aspect ratio
FixedAspectRatioViewport
Fixed aspect ratio, scales
FixedSizeViewport
Fixed size
Bridge Packages
flame_riverpod (State Management)
// Game class MyGame extends FlameGame with RiverpodGameMixin {}
// Component class MyComponent extends Component with RiverpodComponentMixin { @override void onMount() { super.onMount(); final state = ref.watch(myProvider); } }
// Widget RiverpodAwareGameWidget<MyGame>( game: game, )
flame_forge2d (Physics Engine)
class MyGame extends Forge2DGame {}
class MyBody extends BodyComponent { @override Body createBody() { final shape = CircleShape()..radius = 10; final fixtureDef = FixtureDef(shape); final bodyDef = BodyDef(type: BodyType.dynamic); return world.createBody(bodyDef)..createFixture(fixtureDef); } }
flame_audio (Audio)
// Sound effects FlameAudio.play('explosion.mp3');
// BGM FlameAudio.bgm.play('background.mp3'); FlameAudio.bgm.stop(); FlameAudio.bgm.pause(); FlameAudio.bgm.resume();
Common Patterns
Add Component
await add(MyComponent()); // In onLoad add(MyComponent()); // In update
Remove Component
removeFromParent(); // Self component.removeFromParent(); // Other component
Query Children
children.query<Enemy>(); // Find by type componentsAtPoint(position); // Find by position findByKey(ComponentKey.named('player')); // Find by key
Priority (Z-order)
class MyComponent extends PositionComponent { MyComponent() : super(priority: 10); // Higher = rendered on top }
Official Docs
-
Flame Docs
-
Components
-
Collision
-
Effects
-
Camera