feat: Add OverlayManager.setActive() (#3875)

Can be used to declarative describe the conditions for when an overlay
should be visible.


Adds `OverlayManager.setActive()` which can be used to set active state
of an overlay. This helps when you want to declarative describe the
conditions for when a given overlay should be visible.

For example like this:

```dart
game.overlays.setActive("hud", game.gameState.level > 0 && !game.gameState.paused);
```

instead of:

```dart
if (game.gameState.level > 0 && !game.gameState.paused) {
  game.overlays.add("hud");
} else {
  game.overlays.remove("hud");
}
```

Author: lea108

doc/flame/overlays.md

@@ -25,13 +25,17 @@ by providing an `overlayBuilderMap`.
 
   // Marks 'SecondaryMenu' to be rendered.
   overlays.add(secondaryOverlayIdentifier, priority: 1);
-  // Marks 'PauseMenu' to be rendered. Priority = 0 by default 
+  // Marks 'PauseMenu' to be rendered. Priority = 0 by default
   // which means the 'PauseMenu' will be displayed under the 'SecondaryMenu'
   overlays.add(pauseOverlayIdentifier);
-  // Marks 'PauseMenu' to not be rendered. 
+  // Marks 'PauseMenu' to not be rendered.
   overlays.remove(pauseOverlayIdentifier);
   // Toggles the 'PauseMenu' overlay.
   overlays.toggle(pauseOverlayIdentifier);
+  // Check if the 'PauseMenu' is being rendered
+  final hasPauseMenu = overlays.isActive(pauseOverlayIdentifier);
+  // Set active state ov 'SecondaryMenu' based on a condition
+  overlays.setActive(secondaryOverlayIdentifier, active: !hasPauseMenu);
 ```
 
 ```dart

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

@@ -111,6 +111,24 @@ class OverlayManager {
     }
   }
 
+  /// Set active state of [overlayName] to [active]. If [isActive] != [active]
+  /// this method adds or removes the overlay so the active state of the overlay
+  /// becomes [active].
+  ///
+  /// [priority] is used to sort widgets for [buildCurrentOverlayWidgets]
+  /// The smaller the priority, the sooner your component will be build
+  /// (see [add] for more details).
+  bool setActive(String overlayName, {required bool active, int priority = 0}) {
+    if (active == isActive(overlayName)) {
+      return false;
+    }
+    if (active) {
+      return add(overlayName, priority: priority);
+    } else {
+      return remove(overlayName);
+    }
+  }
+
   @internal
   List<Widget> buildCurrentOverlayWidgets(BuildContext context) {
     final widgets = <Widget>[];

packages/flame/test/game/overlays_manager_test.dart

@@ -112,6 +112,28 @@ void main() {
       expect(overlays.activeOverlays.length, 0);
     });
 
+    test('can set overlay active', () {
+      final overlays = FlameGame().overlays
+        ..addEntry('test', (ctx, game) => Container());
+      final added = overlays.setActive('test', active: true);
+      expect(added, true);
+      expect(overlays.isActive('test'), true);
+
+      final addedAgain = overlays.setActive('test', active: true);
+      expect(addedAgain, false);
+      expect(overlays.isActive('test'), true);
+      expect(overlays.activeOverlays.length, 1);
+
+      final removed = overlays.setActive('test', active: false);
+      expect(removed, true);
+      expect(overlays.isActive('test'), false);
+      expect(overlays.activeOverlays.length, 0);
+
+      final removedAgain = overlays.setActive('test', active: false);
+      expect(removedAgain, false);
+      expect(overlays.isActive('test'), false);
+    });
+
     test('can add multiple overlays at once', () {
       final overlays = FlameGame().overlays
         ..addEntry('test1', (ctx, game) => Container())