feat: Adding ClipComponent (#1769)

Adds a new component called ClipComponent that clips the canvas area based on its size and shape.

doc/flame/components.md

@@ -27,7 +27,7 @@ void main() {
 The `Component()` here could of course be any subclass of `Component`.
 
 Every `Component` has a few methods that you can optionally implement, which are used by the
-`FlameGame` class. 
+`FlameGame` class.
 
 
 ### Component lifecycle
@@ -201,7 +201,7 @@ an assertion error will be thrown.
 
 ### Ensuring a component has a given ancestor
 
-When a component requires to have a specific ancestor type somewhere in the 
+When a component requires to have a specific ancestor type somewhere in the
 component tree, `HasAncestor` mixin can be used to enforce that relationship.
 
 The mixin exposes the `ancestor` field that will be of the given type.
@@ -989,6 +989,25 @@ Check the example app
 [custom_painter_component](https://github.com/flame-engine/flame/blob/main/examples/lib/stories/widgets/custom_painter_example.dart)
 for details on how to use it.
 
+## ClipComponent
+
+A `ClipComponent` is a component that will clip the canvas to its size and shape. This means that
+if the component itself or any child of the `ClipComponent` renders outside of the
+`ClipComponent`'s boundaries, the part that is not inside the area will not be shown.
+
+A `ClipComponent` receives a builder function that should return the `Shape` that will define the
+clipped area, based on its size.
+
+To make it easier to use that component, there are three factories that offers common shapes:
+
+ - `ClipComponent.rectangle`: Clips the area in the form a rectangle based on its size.
+ - `ClipComponent.circle`: Clips the area in the form of a circle based on its size.
+ - `ClipComponent.polygon`: Clips the area in the form of a polygon based on the points received
+in the constructor.
+
+Check the example app
+[clip_component](https://github.com/flame-engine/flame/blob/main/examples/lib/stories/components/clip_component_example.dart)
+for details on how to use it.
 
 ## Effects
 

examples/lib/stories/components/clip_component_example.dart

@@ -0,0 +1,87 @@
+import 'dart:math';
+import 'dart:ui';
+
+import 'package:flame/components.dart';
+import 'package:flame/effects.dart';
+import 'package:flame/game.dart';
+import 'package:flame/input.dart';
+import 'package:flutter/material.dart' hide Gradient;
+
+class _Rectangle extends RectangleComponent {
+ _Rectangle()
+ : super(
+ size: Vector2(200, 200),
+ anchor: Anchor.center,
+ paint: Paint()
+ ..shader = Gradient.linear(
+ Offset.zero,
+ const Offset(0, 100),
+ [Colors.orange, Colors.blue],
+ ),
+ children: [
+ SequenceEffect(
+ [
+ RotateEffect.by(
+ pi * 2,
+ LinearEffectController(.4),
+ ),
+ RotateEffect.by(
+ 0,
+ LinearEffectController(.4),
+ ),
+ ],
+ infinite: true,
+ ),
+ ],
+ );
+}
+
+class ClipComponentExample extends FlameGame with TapDetector {
+ static String description = 'Tap on the objects to increase their size.';
+
+ @override
+ Future<void> onLoad() async {
+ addAll(
+ [
+ ClipComponent.circle(
+ position: Vector2(100, 100),
+ size: Vector2.all(50),
+ children: [_Rectangle()],
+ ),
+ ClipComponent.rectangle(
+ position: Vector2(200, 100),
+ size: Vector2.all(50),
+ children: [_Rectangle()],
+ ),
+ ClipComponent.polygon(
+ points: [
+ Vector2(1, 0),
+ Vector2(1, 1),
+ Vector2(0, 1),
+ Vector2(1, 0),
+ ],
+ position: Vector2(200, 200),
+ size: Vector2.all(50),
+ children: [_Rectangle()],
+ ),
+ ],
+ );
+ }
+
+ @override
+ void onTapUp(TapUpInfo info) {
+ final position = info.eventPosition.game;
+ final hit = children
+ .whereType<PositionComponent>()
+ .where(
+ (component) => component.containsLocalPoint(
+ position - component.position,
+ ),
+ )
+ .toList();
+
+ hit.forEach((component) {
+ component.size += Vector2.all(10);
+ });
+ }
+}

examples/lib/stories/components/components.dart

@@ -1,5 +1,6 @@
 import 'package:dashbook/dashbook.dart';
 import 'package:examples/commons/commons.dart';
+import 'package:examples/stories/components/clip_component_example.dart';
 import 'package:examples/stories/components/composability_example.dart';
 import 'package:examples/stories/components/debug_example.dart';
 import 'package:examples/stories/components/game_in_game_example.dart';
@@ -31,5 +32,11 @@ void addComponentsStories(Dashbook dashbook) {
  (_) => GameWidget(game: GameInGameExample()),
  codeLink: baseLink('components/game_in_game_example.dart'),
  info: GameInGameExample.description,
+ )
+ ..add(
+ 'ClipComponent',
+ (context) => GameWidget(game: ClipComponentExample()),
+ codeLink: baseLink('components/clip_component_example.dart'),
+ info: ClipComponentExample.description,
  );
 }

packages/flame/lib/components.dart

@@ -2,6 +2,7 @@
 export 'src/anchor.dart';
 export 'src/collisions/has_collision_detection.dart';
 export 'src/collisions/hitboxes/screen_hitbox.dart';
+export 'src/components/clip_component.dart';
 export 'src/components/core/component.dart';
 export 'src/components/core/component_set.dart';
 export 'src/components/core/position_type.dart';

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

@@ -0,0 +1,139 @@
+import 'dart:ui';
+
+import 'package:flame/components.dart';
+import 'package:flame/experimental.dart';
+
+/// A function that creates a shape based on a size represented by a [Vector2]
+typedef ShapeBuilder = Shape Function(Vector2 size);
+
+/// {@template clip_component}
+/// A component that will clip its content.
+/// {@endtemplate}
+class ClipComponent extends PositionComponent {
+ /// {@macro clip_component}
+ ///
+ /// Clips the canvas based its shape and size.
+ ClipComponent({
+ required ShapeBuilder builder,
+ super.position,
+ super.size,
+ super.scale,
+ super.angle,
+ super.anchor,
+ super.children,
+ super.priority,
+ }) : _builder = builder;
+
+ /// {@macro circle_clip_component}
+ ///
+ /// Clips the canvas in the form of a circle based on its size.
+ factory ClipComponent.circle({
+ Vector2? position,
+ Vector2? size,
+ Vector2? scale,
+ double? angle,
+ Anchor? anchor,
+ Iterable<Component>? children,
+ int? priority,
+ }) {
+ return ClipComponent(
+ builder: (size) => Circle(size / 2, size.x / 2),
+ position: position,
+ size: size,
+ scale: scale,
+ angle: angle,
+ anchor: anchor,
+ children: children,
+ priority: priority,
+ );
+ }
+
+ /// {@macro rectangle_clip_component}
+ ///
+ /// Clips the canvas in the form of a rectangle based on its size.
+ factory ClipComponent.rectangle({
+ Vector2? position,
+ Vector2? size,
+ Vector2? scale,
+ double? angle,
+ Anchor? anchor,
+ Iterable<Component>? children,
+ int? priority,
+ }) {
+ return ClipComponent(
+ builder: (size) => Rectangle.fromRect(size.toRect()),
+ position: position,
+ size: size,
+ scale: scale,
+ angle: angle,
+ anchor: anchor,
+ children: children,
+ priority: priority,
+ );
+ }
+
+ /// {@macro polygon_clip_component}
+ ///
+ /// Clips the canvas in the form of a polygon based on its size.
+ factory ClipComponent.polygon({
+ required List<Vector2> points,
+ Vector2? position,
+ Vector2? size,
+ Vector2? scale,
+ double? angle,
+ Anchor? anchor,
+ Iterable<Component>? children,
+ int? priority,
+ }) {
+ assert(
+ points.length > 2,
+ 'PolygonClipComponent requires at least 3 points.',
+ );
+
+ return ClipComponent(
+ builder: (size) {
+ final translatedPoints = points
+ .map(
+ (p) => p.clone()..multiply(size),
+ )
+ .toList();
+ return Polygon(translatedPoints);
+ },
+ position: position,
+ size: size,
+ scale: scale,
+ angle: angle,
+ anchor: anchor,
+ children: children,
+ priority: priority,
+ );
+ }
+
+ late Path _path;
+ late Shape _shape;
+ final ShapeBuilder _builder;
+
+ @override
+ Future<void> onLoad() async {
+ _prepare();
+ size.addListener(_prepare);
+ }
+
+ void _prepare() {
+ _shape = _builder(size);
+ _path = _shape.asPath();
+ }
+
+ @override
+ void render(Canvas canvas) => canvas.clipPath(_path);
+
+ @override
+ bool containsPoint(Vector2 point) {
+ return _shape.containsPoint(point - position);
+ }
+
+ @override
+ bool containsLocalPoint(Vector2 point) {
+ return _shape.containsPoint(point);
+ }
+}

packages/flame/test/components/clip_component_test.dart

@@ -0,0 +1,68 @@
+import 'package:flame/components.dart';
+import 'package:flame_test/flame_test.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+class _Rectangle extends RectangleComponent {
+ _Rectangle()
+ : super(
+ size: Vector2(200, 200),
+ anchor: Anchor.center,
+ paint: Paint()..color = Colors.blue,
+ );
+}
+
+void main() {
+ group('ClipComponent', () {
+ group('RectangleClipComponent', () {
+ testGolden(
+ 'renders correctly',
+ (game) async {
+ await game.add(
+ ClipComponent.rectangle(
+ size: Vector2(100, 100),
+ children: [_Rectangle()],
+ ),
+ );
+ },
+ goldenFile: '../_goldens/clip_component_rect.png',
+ );
+ });
+
+ group('CircleClipComponent', () {
+ testGolden(
+ 'renders correctly',
+ (game) async {
+ await game.add(
+ ClipComponent.circle(
+ size: Vector2(100, 100),
+ children: [_Rectangle()],
+ ),
+ );
+ },
+ goldenFile: '../_goldens/clip_component_circle.png',
+ );
+ });
+
+ group('PolygonClipComponent', () {
+ testGolden(
+ 'renders correctly',
+ (game) async {
+ await game.add(
+ ClipComponent.polygon(
+ points: [
+ Vector2(1, 0),
+ Vector2(1, 1),
+ Vector2(0, 1),
+ Vector2(1, 0),
+ ],
+ size: Vector2(100, 100),
+ children: [_Rectangle()],
+ ),
+ );
+ },
+ goldenFile: '../_goldens/clip_component_polygon.png',
+ );
+ });
+ });
+}