Adding CustomPainterComponent (#1067)

* Adding CustomPainterComponent

* Apply suggestions from code review

Co-authored-by: Lukas Klingsbo <lukas.klingsbo@gmail.com>
Co-authored-by: Jochum van der Ploeg <jochum@vdploeg.net>

* PR suggestions

Co-authored-by: Lukas Klingsbo <lukas.klingsbo@gmail.com>
Co-authored-by: Jochum van der Ploeg <jochum@vdploeg.net>

doc/components.md

@@ -492,6 +492,21 @@ Check the example app
 [nine_tile_box](https://github.com/flame-engine/flame/blob/main/examples/lib/stories/utils/nine_tile_box.dart)
 for details on how to use it.
 
+## CustomPainterComponent
+
+A `CustomPainter` is a Flutter class used with the `CustomPaint` widget to render custom
+shapes inside a Flutter application.
+
+Flame provides a component that can render a `CustomPainter` called `CustomPainterComponent`, it
+receives a custom painter and renders it on the game canvas.
+
+This can be used for sharing custom rendering logic between your Flame game, and your Flutter
+widgets.
+
+Check the example app
+[custom_painter_component](https://github.com/flame-engine/flame/blob/main/examples/lib/stories/widgets/custom_painter_component.dart)
+for details on how to use it.
+
 ## Effects
 
 Flame provides a set of effects that can be applied to a certain type of components, these effects

examples/lib/stories/widgets/custom_painter_component.dart

@@ -0,0 +1,137 @@
+import 'package:dashbook/dashbook.dart';
+import 'package:flame/components.dart';
+import 'package:flame/game.dart';
+import 'package:flame/input.dart';
+import 'package:flutter/material.dart';
+
+Widget customPainterBuilder(DashbookContext ctx) {
+  return GameWidget(
+    game: CustomPainterGame(),
+    overlayBuilderMap: {
+      'HappyFace': (context, game) {
+        return Center(
+          child: Container(
+            color: Colors.white,
+            width: 200,
+            height: 200,
+            child: Column(
+              children: [
+                const Text(
+                  'Hey, I can be a widget too!',
+                  style: TextStyle(
+                    color: Colors.black,
+                  ),
+                ),
+                const SizedBox(height: 32),
+                SizedBox(
+                  height: 132,
+                  width: 132,
+                  child: CustomPaint(painter: PlayerCustomPainter()),
+                ),
+              ],
+            ),
+          ),
+        );
+      },
+    },
+  );
+}
+
+class PlayerCustomPainter extends CustomPainter {
+  late final facePaint = Paint()..color = Colors.yellow;
+
+  late final eyesPaint = Paint()..color = Colors.black;
+
+  @override
+  void paint(Canvas canvas, Size size) {
+    final faceRadius = size.height / 2;
+
+    canvas.drawCircle(
+      Offset(
+        faceRadius,
+        faceRadius,
+      ),
+      faceRadius,
+      facePaint,
+    );
+
+    final eyeSize = faceRadius * 0.15;
+
+    canvas.drawCircle(
+      Offset(
+        faceRadius - (eyeSize * 2),
+        faceRadius - eyeSize,
+      ),
+      eyeSize,
+      eyesPaint,
+    );
+
+    canvas.drawCircle(
+      Offset(
+        faceRadius + (eyeSize * 2),
+        faceRadius - eyeSize,
+      ),
+      eyeSize,
+      eyesPaint,
+    );
+  }
+
+  @override
+  bool shouldRepaint(CustomPainter oldDelegate) {
+    return false;
+  }
+}
+
+class Player extends CustomPainterComponent with HasGameRef<CustomPainterGame> {
+  static const speed = 150;
+
+  int direction = 1;
+
+  @override
+  Future<void> onLoad() async {
+    await super.onLoad();
+
+    painter = PlayerCustomPainter();
+    size = Vector2.all(100);
+
+    y = 200;
+  }
+
+  @override
+  void update(double dt) {
+    super.update(dt);
+
+    x += speed * direction * dt;
+
+    if ((x + width >= gameRef.size.x && direction > 0) ||
+        (x <= 0 && direction < 0)) {
+      direction *= -1;
+    }
+  }
+}
+
+class CustomPainterGame extends FlameGame with TapDetector {
+  static const info = '''
+      Example demonstration how to use the CustomPainterComponent.
+
+      On the screen you can see a component using a custom painter being
+      rendered on a FlameGame, and if you tap, that same painter is used to
+      show the happy face on a widget overlay.
+  ''';
+
+  @override
+  Future<void> onLoad() async {
+    await super.onLoad();
+
+    add(Player());
+  }
+
+  @override
+  void onTap() {
+    if (overlays.isActive('HappyFace')) {
+      overlays.remove('HappyFace');
+    } else {
+      overlays.add('HappyFace');
+    }
+  }
+}

examples/lib/stories/widgets/widgets.dart

@@ -1,6 +1,7 @@
 import 'package:dashbook/dashbook.dart';
 
 import '../../commons/commons.dart';
+import 'custom_painter_component.dart';
 import 'nine_tile_box.dart';
 import 'overlay.dart';
 import 'sprite_animation_widget.dart';
@@ -40,5 +41,11 @@ void addWidgetsStories(Dashbook dashbook) {
       'Overlay',
       overlayBuilder,
       codeLink: baseLink('widgets/overlay.dart'),
+    )
+    ..add(
+      'CustomPainterComponent',
+      customPainterBuilder,
+      codeLink: baseLink('widgets/custom_painter_component.dart'),
+      info: CustomPainterGame.info,
     );
 }

packages/flame/CHANGELOG.md

@@ -4,6 +4,7 @@
  - Added `StandardEffectController` class
  - Refactored `Effect` class to use `EffectController`, added `Transform2DEffect` class
  - Clarified `TimerComponent` example
+ - Add `CustomPainterComponent`
  - Alternative implementation of `RotateEffect`, based on `Transform2DEffect`
  - Fix `onGameResize` margin bug in `HudMarginComponent`
  - `PositionComponent.size` now returns a `NotifyingVector2`

packages/flame/lib/components.dart

@@ -1,6 +1,7 @@
 export 'src/anchor.dart';
 export 'src/components/component.dart';
 export 'src/components/component_set.dart';
+export 'src/components/custom_painter_component.dart';
 export 'src/components/input/joystick_component.dart';
 export 'src/components/isometric_tile_map_component.dart';
 export 'src/components/mixins/collidable.dart';

packages/flame/lib/src/components/custom_painter_component.dart

@@ -0,0 +1,36 @@
+import 'package:flutter/widgets.dart';
+
+import '../extensions/vector2.dart';
+import 'position_component.dart';
+
+/// A [PositionComponent] that renders a [CustomPainter] at the designated
+/// position, scaled to have the designated size and rotated to the specified
+/// angle.
+///
+/// This component is usefull to [CustomPainter]s between your Flutter UI and Flame game.
+///
+/// Note that given the active rendering nature of a game, `shouldRepaint` is ignored by
+/// this component.
+class CustomPainterComponent extends PositionComponent {
+  /// The [CustomPainter] used to render this component
+  CustomPainter? painter;
+
+  CustomPainterComponent({
+    this.painter,
+    Vector2? position,
+    Vector2? size,
+    int? priority,
+  }) : super(
+          position: position,
+          size: size,
+          priority: priority,
+        );
+
+  @override
+  @mustCallSuper
+  void render(Canvas canvas) {
+    super.render(canvas);
+
+    painter?.paint(canvas, size.toSize());
+  }
+}

packages/flame/test/components/custom_painter_component_test.dart

@@ -0,0 +1,21 @@
+import 'package:canvas_test/canvas_test.dart';
+import 'package:flame/components.dart';
+import 'package:flutter/material.dart';
+import 'package:mocktail/mocktail.dart';
+import 'package:test/test.dart';
+
+class MockCustomPainter extends Mock implements CustomPainter {}
+
+void main() {
+  test('correctly calls the paint method of the painter', () {
+    final painter = MockCustomPainter();
+    final component = CustomPainterComponent(
+      painter: painter,
+    )..size = Vector2.all(100);
+
+    final canvas = MockCanvas();
+    component.render(canvas);
+
+    verify(() => painter.paint(canvas, const Size(100, 100)));
+  });
+}