refactor!: Replace Offset with opacityFrom and opacityTo in Col…

…orEffect (#2876)

`ColorEffect`'s API was a bit confusing because it used `Offset` for
getting values of opacity start and end from user. This PR changes that
to use optional `opacityFrom` and `opacityTo` double parameters. It also
adds validate checks on these value to make sure that are between 0 and
1.

doc/flame/effects.md

@@ -535,13 +535,14 @@ Usage example:
 ```dart
 final effect = ColorEffect(
   const Color(0xFF00FF00),
-  const Offset(0.0, 0.8),
   EffectController(duration: 1.5),
+  opacityFrom = 0.2,
+  opacityTo: 0.8,
 );
 ```
 
-The `Offset` argument will determine "how much" of the color that will be applied to the component,
-in this example the effect will start with 0% and will go up to 80%.
+The `opacityFrom` and `opacityTo` arguments will determine "how much" of the color that will be
+applied to the component. In this example the effect will start with 20% and will go up to 80%.
 
 **Note:** Due to how this effect is implemented, and how Flutter's `ColorFilter` class works, this
 effect can't be mixed with other `ColorEffect`s, when more than one is added to the component, only

doc/flame/examples/lib/color_effect.dart

@@ -18,16 +18,16 @@ class ColorEffectExample extends FlameGame {
           ember.add(
             ColorEffect(
               const Color(0xFF00FF00),
-              const Offset(0.0, 0.6),
               EffectController(duration: 1.5),
+              opacityTo: 0.6,
             ),
           );
         } else {
           ember.add(
             ColorEffect(
               const Color(0xFF1039DB),
-              const Offset(0.0, 0.6),
               EffectController(duration: 1.5),
+              opacityTo: 0.6,
             ),
           );
         }

examples/lib/stories/collision_detection/multiple_worlds_example.dart

@@ -69,11 +69,11 @@ class CollidableEmber extends Ember with CollisionCallbacks {
     add(
       ColorEffect(
         index < 2 ? Colors.red : Colors.green,
-        const Offset(0, 0.9),
         EffectController(
           duration: 0.2,
           alternate: true,
         ),
+        opacityTo: 0.9,
       ),
     );
   }

examples/lib/stories/effects/color_effect_example.dart

@@ -22,15 +22,13 @@ class ColorEffectExample extends FlameGame with TapDetector {
       )..add(
           ColorEffect(
             Colors.blue,
-            const Offset(
-              0.0,
-              0.8,
-            ), // Means, applies from 0% to 80% of the color
             EffectController(
               duration: 1.5,
               reverseDuration: 1.5,
               infinite: true,
             ),
+            // Means, applies from 0% to 80% of the color
+            opacityTo: 0.8,
           ),
         ),
     );

examples/lib/stories/effects/dual_effect_removal_example.dart

@@ -33,8 +33,8 @@ class DualEffectRemovalExample extends FlameGame with TapDetector {
     );
     colorEffect = ColorEffect(
       Colors.blue,
-      const Offset(0.0, 0.8),
       colorController,
+      opacityTo: 0.8,
     );
     mySprite.add(colorEffect);
 

packages/flame/lib/src/effects/color_effect.dart

@@ -18,11 +18,19 @@ class ColorEffect extends ComponentEffect<HasPaint> {
 
   ColorEffect(
     this.color,
-    Offset offset,
     EffectController controller, {
+    double opacityFrom = 0,
+    double opacityTo = 1,
     this.paintId,
     void Function()? onComplete,
-  })  : _tween = Tween(begin: offset.dx, end: offset.dy),
+  })  : assert(
+          opacityFrom >= 0 &&
+              opacityFrom <= 1 &&
+              opacityTo >= 0 &&
+              opacityTo <= 1,
+          'Opacity value should be between 0 and 1',
+        ),
+        _tween = Tween(begin: opacityFrom, end: opacityTo),
         super(controller, onComplete: onComplete);
 
   @override

packages/flame/test/effects/color_effect_test.dart

@@ -13,7 +13,7 @@ void main() {
       await game.ensureAdd(component);
       const color = Colors.red;
       await component.add(
-        ColorEffect(color, const Offset(0, 1), EffectController(duration: 1)),
+        ColorEffect(color, EffectController(duration: 1)),
       );
       game.update(0);
       expect(
@@ -43,7 +43,6 @@ void main() {
 
         final effect = ColorEffect(
           color,
-          const Offset(0, 1),
           EffectController(duration: 1),
         );
         await component.add(effect);
@@ -71,7 +70,6 @@ void main() {
 
         final effect = ColorEffect(
           Colors.red,
-          const Offset(0, 1),
           EffectController(duration: 1),
         );
         await component.ensureAdd(effect);
@@ -85,5 +83,53 @@ void main() {
         );
       },
     );
+
+    test('Validates opacity values', () {
+      expect(
+        () => ColorEffect(
+          Colors.blue,
+          EffectController(duration: 1),
+          opacityTo: 1.1,
+        ),
+        throwsAssertionError,
+      );
+
+      expect(
+        () => ColorEffect(
+          Colors.blue,
+          EffectController(duration: 1),
+          opacityFrom: 255,
+        ),
+        throwsAssertionError,
+      );
+
+      expect(
+        () => ColorEffect(
+          Colors.blue,
+          EffectController(duration: 1),
+          opacityTo: -254,
+        ),
+        throwsAssertionError,
+      );
+
+      expect(
+        () => ColorEffect(
+          Colors.blue,
+          EffectController(duration: 1),
+          opacityFrom: -0.5,
+        ),
+        throwsAssertionError,
+      );
+
+      expect(
+        () => ColorEffect(
+          Colors.blue,
+          EffectController(duration: 1),
+          opacityFrom: 0.1,
+          opacityTo: 0.9,
+        ),
+        returnsNormally,
+      );
+    });
   });
 }