feat: Effect.onComplete callback as an alternative to onFinish() (#1201)

* Effect.onFinish is now a user-defined function

* review suggestion

* Restore onFinish method

* docs

* move method to its old place

* Rename onFinish -> onFinishCallback

* Update docs

doc/effects.md

@@ -80,6 +80,9 @@ functionality inherited by all other effects. This includes:
     removed from the game tree and garbage-collected once the effect completes. Set this to false
     if you plan to reuse the effect after it is finished.
 
+  - Optional user-provided `onFinishCallback`, which will be invoked when the effect has just
+    completed its execution but before it is removed from the game.
+
   - The `reset()` method reverts the effect to its original state, allowing it to run once again.
 
 
@@ -245,7 +248,7 @@ final effect = ColorEffect(
 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%.
 
-__Note :__Due to how this effect is implemented, and how Flutter's `ColorFilter` class works, this
+__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
 the last one will have effect.
 

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

@@ -44,6 +44,9 @@ abstract class Effect extends Component {
   /// in order to make it run once again.
   bool removeOnFinish;
 
+  /// Optional callback function to be invoked once the effect completes.
+  void Function()? onFinishCallback;
+
   /// Boolean indicators of the effect's state, their purpose is to ensure that
   /// the `onStart()` and `onFinish()` callbacks are called exactly once.
   bool _started;
@@ -134,13 +137,16 @@ abstract class Effect extends Component {
   void onStart() {}
 
   /// This method is called once when the effect is about to finish, but before
-  /// it is removed from parent. The notion of "about to finish" is defined by
-  /// the [controller]: this method is called when `controller.completed`
+  /// it is removed from its parent. The notion of "about to finish" is defined
+  /// by the [controller]: this method is called when `controller.completed`
   /// property first becomes true.
   ///
-  /// If the effect is reset, its `onFinish()` method will be called again after
+  /// If the effect is reset, its [onFinish] method will be called again after
   /// the effect has finished again.
-  void onFinish() {}
+  @mustCallSuper
+  void onFinish() {
+    onFinishCallback?.call();
+  }
 
   /// Apply the given [progress] level to the effect's target.
   ///

packages/flame/test/effects/effect_test.dart

@@ -9,7 +9,6 @@ class _MyEffect extends Effect {
 
   double x = -1;
   Function()? onStartCallback;
-  Function()? onFinishCallback;
 
   @override
   void apply(double progress) {
@@ -27,12 +26,6 @@ class _MyEffect extends Effect {
     super.onStart();
     onStartCallback?.call();
   }
-
-  @override
-  void onFinish() {
-    super.onFinish();
-    onFinishCallback?.call();
-  }
 }
 
 void main() {