feat!: Pause game when backgrounded

.github/.cspell/gamedev_dictionary.txt

@@ -24,6 +24,8 @@ arial # name of a typeface
 arities # plural of arity
 arity # number of parameters a function takes
 autofocus # auto focus event
+backgrounded # moving the app to the background
+backgrounding # moving the app to the background
 backpressure # strategy to deal with excess flow of data
 backquote # another word for backtick
 backtick # the back tick character "`"
@@ -39,6 +41,7 @@ coord # coordinate
 coords # plural of coord
 deduplication # removal of duplicates
 easings # Easing functions specify the rate of change of a parameter over time
+foregrounded # moving the app to the foreground
 fullscreen # mode in which a program or app occupies the entire screen with no borders
 goldens # test files used as reference for Golden Tests
 hardcoding # putting a value as a literal instead of computing it

doc/flame/game.md

@@ -226,3 +226,21 @@ While the game is paused, it is possible to advanced it frame by frame using the
 method.
 It might not be much useful in the final game, but can be very helpful in inspecting game state step
 by step during the development cycle.
+
+
+### Backgrounding
+
+The game will be automatically paused when the app is sent to the background,
+and resumed when it comes back to the foreground. This behavior can be disabled by setting
+`pauseWhenBackgrounded` to `false`.
+
+```dart
+class MyGame extends FlameGame {
+  MyGame() {
+    pauseWhenBackgrounded = false;
+  }
+}
+```
+
+On the current Flutter stable (3.13), this flag is effectively ignored on
+non-mobile platforms including the web.

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

@@ -255,4 +255,44 @@ class FlameGame<W extends World> extends ComponentTreeRoot
       }
     }
   }
+
+  /// Whether the game should pause when the app is backgrounded.
+  ///
+  /// On the latest Flutter stable at the time of writing (3.13),
+  /// this is only working on Android and iOS.
+  ///
+  /// Defaults to true.
+  bool pauseWhenBackgrounded = true;
+  bool _pausedBecauseBackgrounded = false;
+
+  @override
+  @mustCallSuper
+  void lifecycleStateChange(AppLifecycleState state) {
+    switch (state) {
+      case AppLifecycleState.resumed:
+      case AppLifecycleState.inactive:
+        if (_pausedBecauseBackgrounded) {
+          resumeEngine();
+        }
+      case AppLifecycleState.paused:
+      case AppLifecycleState.detached:
+      case AppLifecycleState.hidden:
+        if (pauseWhenBackgrounded && !paused) {
+          pauseEngine();
+          _pausedBecauseBackgrounded = true;
+        }
+    }
+  }
+
+  @override
+  void pauseEngine() {
+    _pausedBecauseBackgrounded = false;
+    super.pauseEngine();
+  }
+
+  @override
+  void resumeEngine() {
+    _pausedBecauseBackgrounded = false;
+    super.resumeEngine();
+  }
 }

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

@@ -254,6 +254,9 @@ class GameWidgetState<T extends Game> extends State<GameWidget<T>> {
       currentGame = widget.game!;
     }
     currentGame.addGameStateListener(_onGameStateChange);
+    currentGame.lifecycleStateChange(
+      WidgetsBinding.instance.lifecycleState ?? AppLifecycleState.resumed,
+    );
     _loaderFuture = null;
   }
 
@@ -262,6 +265,7 @@ class GameWidgetState<T extends Game> extends State<GameWidget<T>> {
   /// `currentGame`'s `onDispose` method will be called; otherwise, it will not.
   void disposeCurrentGame({bool callGameOnDispose = false}) {
     currentGame.removeGameStateListener(_onGameStateChange);
+    currentGame.lifecycleStateChange(AppLifecycleState.paused);
     currentGame.onRemove();
     if (callGameOnDispose) {
       currentGame.onDispose();

packages/flame/test/game/flame_game_test.dart

@@ -698,6 +698,28 @@ void main() {
         });
       });
     });
+
+    group('pauseWhenBackgrounded:', () {
+      testWithFlameGame('true', (game) async {
+        game.pauseWhenBackgrounded = true;
+
+        game.lifecycleStateChange(AppLifecycleState.paused);
+        expect(game.paused, true);
+
+        game.lifecycleStateChange(AppLifecycleState.resumed);
+        expect(game.paused, false);
+      });
+
+      testWithFlameGame('false', (game) async {
+        game.pauseWhenBackgrounded = false;
+
+        game.lifecycleStateChange(AppLifecycleState.paused);
+        expect(game.paused, false);
+
+        game.lifecycleStateChange(AppLifecycleState.resumed);
+        expect(game.paused, false);
+      });
+    });
   });
 }