feat: Adding callbacks for EffectController (#1926)

doc/flame/effects.md

@@ -350,6 +350,8 @@ EffectController({
     int? repeatCount,
     bool infinite = false,
     double startDelay = 0.0,
+    VoidCallback? onMax,
+    VoidCallback? onMin,
 });
 ```
 
@@ -397,6 +399,12 @@ EffectController({
   Using this parameter is the simplest way to create a chain of effects that execute one after
   another (or with an overlap).
 
+- *`onMax`* -- callback function which will be invoked right after reaching its max progress and
+  before the optional pause and reverse stage.
+
+- *`onMin`* -- callback function which will be invoked right after reaching its lowest progress
+  at the end of the reverse stage and before the optional pause and forward stage.
+
 The effect controller returned by this factory constructor will be composited of multiple simpler
 effect controllers described further below. If this constructor proves to be too limited for your
 needs, you can always create your own combination from the same building blocks.

packages/flame/lib/src/effects/controllers/callback_controller.dart

@@ -0,0 +1,37 @@
+import 'dart:ui';
+import 'package:flame/effects.dart';
+
+/// This effect controller invokes the [callback] function and then immediately
+/// finishes. Use it as part of a more complex effect to insert callbacks at
+/// certain parts of that effect.
+class CallbackController extends DurationEffectController {
+  /// Creates a controller that invokes the given [callback] function.
+  /// The [progress] parameter specifies the progress level of the effect at the
+  /// time when the callback is invoked. It is the responsibility of the user to
+  /// ensure that this progress level is contiguous with respect to the progress
+  /// of the overall effect.
+  CallbackController(this.callback, {required double progress})
+      : _progress = progress,
+        super(0.0);
+
+  final VoidCallback callback;
+  final double _progress;
+
+  @override
+  double get progress => _progress;
+
+  @override
+  bool get completed => true;
+
+  @override
+  double advance(double dt) {
+    callback();
+    return dt;
+  }
+
+  @override
+  double recede(double dt) {
+    callback();
+    return dt;
+  }
+}

packages/flame/lib/src/effects/controllers/effect_controller.dart

@@ -1,3 +1,6 @@
+import 'dart:ui';
+
+import 'package:flame/src/effects/controllers/callback_controller.dart';
 import 'package:flame/src/effects/controllers/curved_effect_controller.dart';
 import 'package:flame/src/effects/controllers/delayed_effect_controller.dart';
 import 'package:flame/src/effects/controllers/infinite_effect_controller.dart';
@@ -71,6 +74,10 @@ abstract class EffectController {
   /// If the animation is finite and there are no "backward" or "atMin" stages
   /// then the animation will complete at `progress == 1`, otherwise it will
   /// complete at `progress == 0`.
+  ///
+  /// Before [atMaxDuration] and [atMinDuration] a callback function can be
+  /// provided which will be called after the corresponding [progress] has
+  /// finished.
   factory EffectController({
     double? duration,
     double? speed,
@@ -84,6 +91,8 @@ abstract class EffectController {
     double startDelay = 0.0,
     double atMaxDuration = 0.0,
     double atMinDuration = 0.0,
+    VoidCallback? onMax,
+    VoidCallback? onMin,
   }) {
     assert(
       (duration ?? 1) >= 0,
@@ -155,6 +164,11 @@ abstract class EffectController {
       );
     }
 
+    // ON MAX CALLBACK
+    if (onMax != null) {
+      items.add(CallbackController(onMax, progress: 1.0));
+    }
+
     // AT-MAX
     if (atMaxDuration != 0) {
       items.add(PauseEffectController(atMaxDuration, progress: 1.0));
@@ -193,6 +207,11 @@ abstract class EffectController {
       }
     }
 
+    // ON MIN CALLBACK
+    if (onMin != null) {
+      items.add(CallbackController(onMin, progress: 0.0));
+    }
+
     // AT-MIN
     if (atMinDuration != 0) {
       items.add(PauseEffectController(atMinDuration, progress: 0.0));

packages/flame/test/effects/controllers/effect_controller_test.dart

@@ -6,6 +6,13 @@ import 'package:flame/game.dart';
 import 'package:flame_test/flame_test.dart';
 import 'package:flutter/animation.dart';
 import 'package:flutter_test/flutter_test.dart';
+import 'package:mocktail/mocktail.dart';
+
+abstract class Callback {
+  void call();
+}
+
+class CallbackMock extends Mock implements Callback {}
 
 void main() {
   group('EffectController', () {
@@ -312,6 +319,38 @@ void main() {
       );
     });
 
+    test('onMax and onMin callbacks', () {
+      final mockOnMax = CallbackMock();
+      final mockOnMin = CallbackMock();
+      final ec = EffectController(
+        duration: 1,
+        reverseDuration: 1,
+        onMax: mockOnMax,
+        onMin: mockOnMin,
+        infinite: true,
+      );
+
+      ec.advance(1);
+      verifyNever(mockOnMax.call);
+      verifyNever(mockOnMin.call);
+
+      ec.advance(0.1);
+      verify(mockOnMax.call).called(1);
+      verifyNever(mockOnMin.call);
+
+      ec.advance(1); // after this call a .setToStart() is performed
+      verifyNever(mockOnMax.call);
+      verify(mockOnMin.call).called(1);
+
+      ec.advance(0.5);
+      verifyNever(mockOnMax.call);
+      verifyNever(mockOnMin.call);
+
+      ec.advance(0.5);
+      verify(mockOnMax.call).called(1);
+      verifyNever(mockOnMin.call);
+    });
+
     group('errors', () {
       test('empty', () {
         expect(