feat: Add onDispose to game.dart called from game_widget.dart (#…

…2659)

This adds, imo, the missing piece in the event lifecycle based on all the other lifecycle work I have been doing.

Currently, when dispose is called in game_widget.dart, it calls disposeCurrentGame which has the call for onRemove, at issue though is, disposeCurrentGame is also called by didUpdateWidget if the oldWidget.game != widget.game. It may not be needed, but I feel like because FlameGame is inherently a stateless set of widgets (children of the LeafRenderObjectWidget), the hook for onRemove is muddled with what is NOT actually a dispose event. So my thought is, introduce the onDispose method to game which gets called by making disposeCurrentGame({isDispose = false}) then in the actual overridden dispose method, pass that as true, so we can then call currentGame.onDispose() after the call to currentGame.onRemove().

packages/flame/lib/src/game/game.dart

@@ -213,6 +213,9 @@ abstract mixin class Game {
   /// do cleanups to avoid memory leaks.
   void onRemove() {}
 
+  /// Called when the GameWidget is disposed by Flutter.
+  void onDispose() {}
+
   /// Called after the game has left the widget tree.
   /// This can be overridden to add logic that requires the game
   /// not be on the flutter widget tree anymore.

packages/flame/lib/src/game/game_widget/game_widget.dart

@@ -254,8 +254,14 @@ class GameWidgetState<T extends Game> extends State<GameWidget<T>> {
     _loaderFuture = null;
   }
 
-  void disposeCurrentGame() {
+  /// [disposeCurrentGame] is called by two flutter events - `didUpdateWidget`
+  /// and `dispose`.  When the parameter [callGameOnDispose] is true, the
+  /// `currentGame`'s `onDispose` method will be called; otherwise, it will not.
+  void disposeCurrentGame({bool callGameOnDispose = false}) {
     currentGame.removeGameStateListener(_onGameStateChange);
+    if (callGameOnDispose) {
+      currentGame.onDispose();
+    }
   }
 
   @override
@@ -281,7 +287,7 @@ class GameWidgetState<T extends Game> extends State<GameWidget<T>> {
   @override
   void dispose() {
     super.dispose();
-    disposeCurrentGame();
+    disposeCurrentGame(callGameOnDispose: true);
     // If we received a focus node from the user, they are responsible
     // for disposing it
     if (widget.focusNode == null) {

packages/flame/test/game/game_widget/game_widget_lifecycle_test.dart

@@ -30,6 +30,12 @@ class _MyGame extends FlameGame {
     super.onRemove();
     events.add('onRemove');
   }
+
+  @override
+  void onDispose() {
+    super.onDispose();
+    events.add('onDispose');
+  }
 }
 
 class _TitlePage extends StatelessWidget {
@@ -185,6 +191,11 @@ void main() {
         true,
         reason: 'onRemove was not called',
       );
+      expect(
+        events.contains('onDispose'),
+        true,
+        reason: 'onDispose was not called',
+      );
     });
 
     testWidgets('on resize, parents are kept', (tester) async {
@@ -229,6 +240,7 @@ void main() {
           'onLoad',
           'onMount',
           'onRemove',
+          'onDispose',
           'onGameResize',
           'onMount',
         ],