From ceaf34a9e4cea4d4184e07253273ad846a4de77a Mon Sep 17 00:00:00 2001 From: Lisette Linse Date: Mon, 23 Mar 2026 20:58:39 +0100 Subject: [PATCH 1/3] feat: OverlayManager.setActive() Can be used to declarative describe the conditions for when an overlay should be visible. --- .../flame/lib/src/game/overlay_manager.dart | 18 +++++++++++++++ .../test/game/overlays_manager_test.dart | 22 +++++++++++++++++++ 2 files changed, 40 insertions(+) diff --git a/packages/flame/lib/src/game/overlay_manager.dart b/packages/flame/lib/src/game/overlay_manager.dart index 1204dcb1b76..8b15dae7d98 100644 --- a/packages/flame/lib/src/game/overlay_manager.dart +++ b/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, bool active, {int priority = 0}) { + if (active == isActive(overlayName)) { + return false; + } + if (active) { + return add(overlayName, priority: priority); + } else { + return remove(overlayName); + } + } + @internal List buildCurrentOverlayWidgets(BuildContext context) { final widgets = []; diff --git a/packages/flame/test/game/overlays_manager_test.dart b/packages/flame/test/game/overlays_manager_test.dart index f128a3783bb..99787aca804 100644 --- a/packages/flame/test/game/overlays_manager_test.dart +++ b/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', true); + expect(added, true); + expect(overlays.isActive('test'), true); + + final addedAgain = overlays.setActive('test', true); + expect(addedAgain, false); + expect(overlays.isActive('test'), true); + expect(overlays.activeOverlays.length, 1); + + final removed = overlays.setActive('test', false); + expect(removed, true); + expect(overlays.isActive('test'), false); + expect(overlays.activeOverlays.length, 0); + + final removedAgain = overlays.setActive('test', 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()) From 2f1a996e600f9eb1070b8f626eb442329133d262 Mon Sep 17 00:00:00 2001 From: Lisette Linse Date: Mon, 23 Mar 2026 21:40:03 +0100 Subject: [PATCH 2/3] fix: Use named parameter for boolean parameter --- packages/flame/lib/src/game/overlay_manager.dart | 2 +- packages/flame/test/game/overlays_manager_test.dart | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/flame/lib/src/game/overlay_manager.dart b/packages/flame/lib/src/game/overlay_manager.dart index 8b15dae7d98..c26fd3ad04c 100644 --- a/packages/flame/lib/src/game/overlay_manager.dart +++ b/packages/flame/lib/src/game/overlay_manager.dart @@ -118,7 +118,7 @@ class OverlayManager { /// [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, bool active, {int priority = 0}) { + bool setActive(String overlayName, {required bool active, int priority = 0}) { if (active == isActive(overlayName)) { return false; } diff --git a/packages/flame/test/game/overlays_manager_test.dart b/packages/flame/test/game/overlays_manager_test.dart index 99787aca804..5b78c55a6b2 100644 --- a/packages/flame/test/game/overlays_manager_test.dart +++ b/packages/flame/test/game/overlays_manager_test.dart @@ -115,21 +115,21 @@ void main() { test('can set overlay active', () { final overlays = FlameGame().overlays ..addEntry('test', (ctx, game) => Container()); - final added = overlays.setActive('test', true); + final added = overlays.setActive('test', active: true); expect(added, true); expect(overlays.isActive('test'), true); - final addedAgain = overlays.setActive('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', false); + 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', false); + final removedAgain = overlays.setActive('test', active: false); expect(removedAgain, false); expect(overlays.isActive('test'), false); }); From fe6839794c2d4d21752dbe55263ba57697308826 Mon Sep 17 00:00:00 2001 From: Lisette Linse Date: Tue, 24 Mar 2026 09:36:45 +0100 Subject: [PATCH 3/3] doc: Add OverlayManager.isActive and .setActive to documentation --- doc/flame/overlays.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/flame/overlays.md b/doc/flame/overlays.md index ae7dc848b66..55ec6b3d457 100644 --- a/doc/flame/overlays.md +++ b/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