feat: Add OverlayManager.setActive()

[lea108]

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

Description

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:

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

instead of:

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

Checklist

• I have followed the Contributor Guide when preparing my PR.
• I have updated/added tests for ALL new/updated/fixed functionality.
• I have updated/added relevant documentation in docs and added dartdoc comments with ///.
• I have updated/added relevant examples in examples or docs.

Breaking Change?

• Yes, this PR is a breaking change.
• No, this PR is not a breaking change.

Related Issues

Closes #3853

[lea108]

I did take a look on the example for overlays, but you kinda either use toggle/add/remove or setActive().

There is one example of using it in my game elevate that is more natural in changeScene(): (where I wrote an extension method with the name setVisible instead of setActive which I later is the more natural name in relation to the existing isActive method)
https://github.com/lea108/elevate/blob/flame-game-jam/lib/game.dart#L89

[spydon]

Code looks good, can we update the docs and add/modify an example to use it?

[ufrshubham]

LGTM! Thanks for adding this 🤘🏼

[lea108]

Sorry, just realized I got two white space changes in, should I undo those?

[spydon]

Sorry, just realized I got two white space changes in, should I undo those?

Nah it's fine, it removed whitespace right?

[luanpotter]

LGTM

[lea108]

Sorry, just realized I got two white space changes in, should I undo those?

Nah it's fine, it removed whitespace right?

Yes exactly. I accidentally included removed whitespace during git add -p.

[lea108]

Code looks good, can we update the docs and add/modify an example to use it?

I've updated the docs which now exemplifies how isActive() and setActive() can be used.

I have took a look at overlay_example.dart. It doesn't cover the toggle() or isAcitve() method and I wonder how much I should make it heavier to shoe horn in toggle(), isActive(), setActive() in the same example as currently using if (...) { add() } else { remove() } as it may end up more convoluted than being a guide into using overlays?

[spydon]

Code looks good, can we update the docs and add/modify an example to use it?

I've updated the docs which now exemplifies how isActive() and setActive() can be used.

I have took a look at overlay_example.dart. It doesn't cover the toggle() or isAcitve() method and I wonder how much I should make it heavier to shoe horn in toggle(), isActive(), setActive() in the same example as currently using if (...) { add() } else { remove() } as it may end up more convoluted than being a guide into using overlays?

Yeah, I think this is probably fine as it is.