fix: Overlays can now be properly added during onLoad (#1759)

* fix overlays being set in onLoad

* added tests

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

@@ -167,8 +167,6 @@ abstract class Game {
       );
     }
     _gameRenderBox = gameRenderBox;
-    overlays._game = this;
-
     onAttach();
   }
 
@@ -300,7 +298,7 @@ abstract class Game {
   /// overlays.add(pauseOverlayIdentifier); // marks 'PauseMenu' to be rendered.
   /// overlays.remove(pauseOverlayIdentifier); // hides 'PauseMenu'.
   /// ```
-  final overlays = _ActiveOverlays();
+  late final overlays = _ActiveOverlays(this);
 
   /// Used to change the mouse cursor of the GameWidget running this game.
   /// Setting the value to null will make the GameWidget defer the choice
@@ -335,20 +333,22 @@ abstract class Game {
 /// A helper class used to control the visibility of overlays on a [Game]
 /// instance. See [Game.overlays].
 class _ActiveOverlays {
-  Game? _game;
+  _ActiveOverlays(this._game);
+
+  final Game _game;
   final Set<String> _activeOverlays = {};
 
   /// Clear all active overlays.
   void clear() {
     _activeOverlays.clear();
-    _game?._refreshWidget();
+    _game._refreshWidget();
   }
 
   /// Marks the [overlayName] to be rendered.
   bool add(String overlayName) {
     final setChanged = _activeOverlays.add(overlayName);
     if (setChanged) {
-      _game?._refreshWidget();
+      _game._refreshWidget();
     }
     return setChanged;
   }
@@ -360,15 +360,15 @@ class _ActiveOverlays {
 
     final overlayCountAfterAdded = _activeOverlays.length;
     if (overlayCountBeforeAdded != overlayCountAfterAdded) {
-      _game?._refreshWidget();
+      _game._refreshWidget();
     }
   }
 
   /// Hides the [overlayName].
   bool remove(String overlayName) {
     final hasRemoved = _activeOverlays.remove(overlayName);
     if (hasRemoved) {
-      _game?._refreshWidget();
+      _game._refreshWidget();
     }
     return hasRemoved;
   }
@@ -380,7 +380,7 @@ class _ActiveOverlays {
 
     final overlayCountAfterRemoved = _activeOverlays.length;
     if (overlayCountBeforeRemoved != overlayCountAfterRemoved) {
-      _game?._refreshWidget();
+      _game._refreshWidget();
     }
   }
 

packages/flame/test/_resources/custom_flame_game.dart

@@ -0,0 +1,19 @@
+import 'package:flame/game.dart';
+
+class CustomFlameGame extends FlameGame {
+  CustomFlameGame({
+    super.children,
+    Future<void>? Function(FlameGame)? onLoad,
+    void Function(FlameGame)? onMount,
+  })  : _onLoad = onLoad,
+        _onMount = onMount;
+
+  final Future<void>? Function(FlameGame)? _onLoad;
+  final void Function(FlameGame)? _onMount;
+
+  @override
+  Future<void>? onLoad() => _onLoad?.call(this);
+
+  @override
+  void onMount() => _onMount?.call(this);
+}

packages/flame/test/game/active_overlays_test.dart

@@ -1,8 +1,90 @@
 import 'package:flame/game.dart';
+import 'package:flutter/widgets.dart';
 import 'package:flutter_test/flutter_test.dart';
 
+import '../_resources/custom_flame_game.dart';
+
 void main() {
   group('_ActiveOverlays', () {
+    testWidgets(
+      'Overlay can be added via initialActiveOverlays',
+      (tester) async {
+        const key1 = ValueKey('one');
+        const key2 = ValueKey('two');
+        await tester.pumpWidget(
+          GameWidget(
+            game: FlameGame(),
+            overlayBuilderMap: {
+              'first!': (_, __) => Container(key: key1),
+              'second': (_, __) => Container(key: key2),
+            },
+            initialActiveOverlays: const ['first!'],
+          ),
+        );
+        await tester.pump();
+
+        expect(find.byKey(key1), findsOneWidget);
+        expect(find.byKey(key2), findsNothing);
+      },
+    );
+
+    testWidgets(
+      'Overlay can be added in onLoad',
+      (tester) async {
+        const key1 = ValueKey('one');
+        const key2 = ValueKey('two');
+        await tester.pumpWidget(
+          GameWidget(
+            game: CustomFlameGame(
+              onLoad: (game) async {
+                game.overlays.add('first!');
+              },
+            ),
+            overlayBuilderMap: {
+              'first!': (_, __) => Container(key: key1),
+              'second': (_, __) => Container(key: key2),
+            },
+          ),
+        );
+        await tester.pump();
+
+        expect(find.byKey(key1), findsOneWidget);
+        expect(find.byKey(key2), findsNothing);
+      },
+    );
+
+    testWidgets(
+      'Overlay can be added and removed at runtime',
+      (tester) async {
+        const key1 = ValueKey('one');
+        const key2 = ValueKey('two');
+        final game = FlameGame();
+        await tester.pumpWidget(
+          GameWidget(
+            game: game,
+            overlayBuilderMap: {
+              'first!': (_, __) => Container(key: key1),
+              'second': (_, __) => Container(key: key2),
+            },
+          ),
+        );
+        await tester.pump();
+
+        expect(find.byKey(key1), findsNothing);
+        expect(find.byKey(key2), findsNothing);
+
+        game.overlays.add('second');
+        await tester.pump();
+        expect(find.byKey(key1), findsNothing);
+        expect(find.byKey(key2), findsOneWidget);
+
+        game.overlays.remove('second');
+        await tester.pump();
+        expect(find.byKey(key1), findsNothing);
+        expect(find.byKey(key2), findsNothing);
+      },
+    );
+
     group('add', () {
       test('can add an overlay', () {
         final overlays = FlameGame().overlays;