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 - RectangleCircleComponent - CirclePolygonComponent - 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 hitboxesCollisionType.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
majiayu000