docs: Break out overlays docs (#2384)

The docs for overlays were a bit hard to find so I broke them out to its
own section.
They could need some some updating too with more examples and
instructions.

doc/flame/flame.md

@@ -1,4 +1,4 @@
-# flame
+# Flame
 
 - [File Structure](structure.md)
 - [Game Widget](game_widget.md)
@@ -12,6 +12,7 @@
 - [Camera Component](camera_component.md)
 - [Inputs](inputs/inputs.md)
 - [Rendering](rendering/rendering.md)
+- [Overlays](overlays.md)
 - [Other](other/other.md)
 
 ```{toctree}

doc/flame/game.md

@@ -197,51 +197,3 @@ A Flame `Game` can be paused and resumed in two ways:
 
 When pausing a Flame `Game`, the `GameLoop` is effectively paused, meaning that no updates or new
 renders will happen until it is resumed.
-
-
-## Flutter Widgets and Game instances
-
-Since a Flame game can be wrapped in a widget, it is quite easy to use it alongside other Flutter
-widgets. But still, there is the Widgets Overlay API that makes things even easier.
-
-`Game.overlays` enables any Flutter widget to be shown on top of a game instance, this makes it very
-easy to create things like a pause menu or an inventory screen for example.
-
-This management is done via the `game.overlays.add` and `game.overlays.remove` methods that mark an
-overlay to be shown or hidden, respectively, via a `String` argument that identifies the overlay.
-After that, it can be specified which widgets represent each overlay in the `GameWidget` declaration
-by setting an `overlayBuilderMap`.
-
-```dart
-void main() {
-  // Inside the game methods:
-  final pauseOverlayIdentifier = 'PauseMenu';
-
-  // Marks 'PauseMenu' to be rendered.
-  overlays.add(pauseOverlayIdentifier);
-  // Marks 'PauseMenu' to not be rendered.
-  overlays.remove(pauseOverlayIdentifier);
-}
-```
-
-```dart
-// On the widget declaration
-final game = MyGame();
-
-Widget build(BuildContext context) {
-  return GameWidget(
-    game: game,
-    overlayBuilderMap: {
-      'PauseMenu': (BuildContext context, MyGame game) {
-        return Text('A pause menu');
-      },
-    },
-  );
-}
-```
-
-The order of rendering for an overlay is determined by the order of the keys in the
-`overlayBuilderMap`.
-
-An example of this feature can be found
-[here](https://github.com/flame-engine/flame/blob/main/examples/lib/stories/system/overlays_example.dart).

doc/flame/overlays.md

@@ -0,0 +1,46 @@
+# Overlays
+
+Since a Flame game can be wrapped in a widget, it is quite easy to use it alongside other Flutter
+widgets in your tree. However, if you want to easily show widgets on top of your Flame game, like
+messages, menu screens or something of that nature, you can use the Widgets Overlay API to make
+things even easier.
+
+`Game.overlays` enables any Flutter widget to be shown on top of a game instance. This makes it very
+easy to create things like a pause menu or an inventory screen for example.
+
+The feature can be used via the `game.overlays.add` and `game.overlays.remove` methods that mark an
+overlay to be shown or hidden, respectively, via a `String` argument that identifies the overlay.
+After that, you can map each overlay to their corresponding Widget in your `GameWidget` declaration
+by providing an `overlayBuilderMap`.
+
+```dart
+  // Inside your game:
+  final pauseOverlayIdentifier = 'PauseMenu';
+
+  // Marks 'PauseMenu' to be rendered.
+  overlays.add(pauseOverlayIdentifier);
+  // Marks 'PauseMenu' to not be rendered.
+  overlays.remove(pauseOverlayIdentifier);
+```
+
+```dart
+// On the widget declaration
+final game = MyGame();
+
+Widget build(BuildContext context) {
+  return GameWidget(
+    game: game,
+    overlayBuilderMap: {
+      'PauseMenu': (BuildContext context, MyGame game) {
+        return Text('A pause menu');
+      },
+    },
+  );
+}
+```
+
+The order of rendering for an overlay is determined by the order of the keys in the
+`overlayBuilderMap`.
+
+An example of this feature can be found
+[here](https://github.com/flame-engine/flame/blob/main/examples/lib/stories/system/overlays_example.dart).