feat: Add WorldRoute to enable swapping worlds from the RouterCompone…

…nt (flame-engine#3372)

This PR adds the `WorldRoute` which acts as a normal route, but instead
of adding a new component (page), it swaps out the world that the camera
(either the default camera or an explicitly passed in one) is watching.

.gitignore

@@ -37,6 +37,7 @@ desktop/
 coverage/
 pubspec.lock
 pubspec_overrides.yaml
+.fvmrc
 
 # Sphinx related
 __pycache__/

doc/flame/examples/lib/router.dart

@@ -14,50 +14,22 @@ class RouterGame extends FlameGame {
     add(
       router = RouterComponent(
         routes: {
-          'splash': Route(SplashScreenPage.new),
           'home': Route(StartPage.new),
-          'level1': Route(Level1Page.new),
-          'level2': Route(Level2Page.new),
+          'level1': WorldRoute(Level1Page.new),
+          'level2': WorldRoute(Level2Page.new, maintainState: false),
           'pause': PauseRoute(),
         },
-        initialRoute: 'splash',
+        initialRoute: 'home',
       ),
     );
   }
 }
 
-class SplashScreenPage extends Component
-    with TapCallbacks, HasGameReference<RouterGame> {
-  @override
-  Future<void> onLoad() async {
-    addAll([
-      Background(const Color(0xff282828)),
-      TextBoxComponent(
-        text: '[Router demo]',
-        textRenderer: TextPaint(
-          style: const TextStyle(
-            color: Color(0x66ffffff),
-            fontSize: 16,
-          ),
-        ),
-        align: Anchor.center,
-        size: game.canvasSize,
-      ),
-    ]);
-  }
-
-  @override
-  bool containsLocalPoint(Vector2 point) => true;
-
-  @override
-  void onTapUp(TapUpEvent event) => game.router.pushNamed('home');
-}
-
 class StartPage extends Component with HasGameReference<RouterGame> {
   StartPage() {
     addAll([
       _logo = TextComponent(
-        text: 'Syzygy',
+        text: 'Your Game',
         textRenderer: TextPaint(
           style: const TextStyle(
             fontSize: 64,
@@ -231,22 +203,28 @@ class PauseButton extends SimpleButton with HasGameReference<RouterGame> {
             ..lineTo(26, 30),
           position: Vector2(60, 10),
         );
+
+  bool isPaused = false;
+
   @override
-  void action() => game.router.pushNamed('pause');
+  void action() {
+    if (isPaused) {
+      game.router.pop();
+    } else {
+      game.router.pushNamed('pause');
+    }
+    isPaused = !isPaused;
+  }
 }
 
-class Level1Page extends Component {
+class Level1Page extends DecoratedWorld with HasGameReference {
   @override
   Future<void> onLoad() async {
-    final game = findGame()!;
     addAll([
       Background(const Color(0xbb2a074f)),
-      BackButton(),
-      PauseButton(),
       Planet(
         radius: 25,
         color: const Color(0xfffff188),
-        position: game.size / 2,
         children: [
           Orbit(
             radius: 110,
@@ -267,20 +245,33 @@ class Level1Page extends Component {
       ),
     ]);
   }
+
+  final hudComponents = <Component>[];
+
+  @override
+  void onMount() {
+    hudComponents.addAll([
+      BackButton(),
+      PauseButton(),
+    ]);
+    game.camera.viewport.addAll(hudComponents);
+  }
+
+  @override
+  void onRemove() {
+    game.camera.viewport.removeAll(hudComponents);
+    super.onRemove();
+  }
 }
 
-class Level2Page extends Component {
+class Level2Page extends DecoratedWorld with HasGameReference {
   @override
   Future<void> onLoad() async {
-    final game = findGame()!;
     addAll([
       Background(const Color(0xff052b44)),
-      BackButton(),
-      PauseButton(),
       Planet(
         radius: 30,
         color: const Color(0xFFFFFFff),
-        position: game.size / 2,
         children: [
           Orbit(
             radius: 60,
@@ -311,6 +302,23 @@ class Level2Page extends Component {
       ),
     ]);
   }
+
+  final hudComponents = <Component>[];
+
+  @override
+  void onMount() {
+    hudComponents.addAll([
+      BackButton(),
+      PauseButton(),
+    ]);
+    game.camera.viewport.addAll(hudComponents);
+  }
+
+  @override
+  void onRemove() {
+    game.camera.viewport.removeAll(hudComponents);
+    super.onRemove();
+  }
 }
 
 class Planet extends PositionComponent {
@@ -367,18 +375,19 @@ class PauseRoute extends Route {
 
   @override
   void onPush(Route? previousRoute) {
-    previousRoute!
-      ..stopTime()
-      ..addRenderEffect(
-        PaintDecorator.grayscale(opacity: 0.5)..addBlur(3.0),
-      );
+    if (previousRoute is WorldRoute && previousRoute.world is DecoratedWorld) {
+      (previousRoute.world! as DecoratedWorld).timeScale = 0;
+      (previousRoute.world! as DecoratedWorld).decorator =
+          PaintDecorator.grayscale(opacity: 0.5)..addBlur(3.0);
+    }
   }
 
   @override
   void onPop(Route nextRoute) {
-    nextRoute
-      ..resumeTime()
-      ..removeRenderEffect();
+    if (nextRoute is WorldRoute && nextRoute.world is DecoratedWorld) {
+      (nextRoute.world! as DecoratedWorld).timeScale = 1;
+      (nextRoute.world! as DecoratedWorld).decorator = null;
+    }
   }
 }
 
@@ -412,3 +421,16 @@ class PausePage extends Component
   @override
   void onTapUp(TapUpEvent event) => game.router.pop();
 }
+
+class DecoratedWorld extends World with HasTimeScale {
+  PaintDecorator? decorator;
+
+  @override
+  void renderFromCamera(Canvas canvas) {
+    if (decorator == null) {
+      super.renderFromCamera(canvas);
+    } else {
+      decorator!.applyChain(super.renderFromCamera, canvas);
+    }
+  }
+}

doc/flame/router.md

@@ -90,6 +90,46 @@ The current route can be replaced using `pushReplacementNamed` or `pushReplaceme
 simply executes `pop` on the current route and then `pushNamed` or `pushRoute`.
 
 
+## WorldRoute
+
+The **WorldRoute** is a special route that allows setting active game worlds via the router. These
+Such routes can be used, for example, for swapping levels implemented as separate worlds in your
+game.
+
+By default, the `WorldRoute` will replace the current world with the new one and by default it will
+keep the state of the world after being popped from the stack. If you want the world to be recreated
+each time the route is activated, set `maintainState` to `false`.
+
+If you are not using the built-in `CameraComponent` you can pass in the camera that you want to use
+explicitly in the constructor.
+
+```dart
+final router = RouterComponent(
+  routes: {
+    'level1': WorldRoute(MyWorld1.new),
+    'level2': WorldRoute(MyWorld2.new, maintainState: false),
+  },
+);
+
+class MyWorld1 extends World {
+  @override
+  Future<void> onLoad() async {
+    add(BackgroundComponent());
+    add(PlayerComponent());
+  }
+}
+
+class MyWorld2 extends World {
+   @override
+   Future<void> onLoad() async {
+      add(BackgroundComponent());
+      add(PlayerComponent());
+      add(EnemyComponent());
+   }
+}
+```
+
+
 ## OverlayRoute
 
 The **OverlayRoute** is a special route that allows adding game overlays via the router. These

examples/lib/main.dart

@@ -30,6 +30,7 @@ import 'package:examples/stories/input/input.dart';
 import 'package:examples/stories/layout/layout.dart';
 import 'package:examples/stories/parallax/parallax.dart';
 import 'package:examples/stories/rendering/rendering.dart';
+import 'package:examples/stories/router/router.dart';
 import 'package:examples/stories/sprites/sprites.dart';
 import 'package:examples/stories/structure/structure.dart';
 import 'package:examples/stories/svg/svg.dart';
@@ -88,6 +89,7 @@ void runAsDashbook() {
   addLayoutStories(dashbook);
   addParallaxStories(dashbook);
   addRenderingStories(dashbook);
+  addRouterStories(dashbook);
   addTiledStories(dashbook);
   addSpritesStories(dashbook);
   addSvgStories(dashbook);

examples/lib/stories/router/router.dart

@@ -0,0 +1,13 @@
+import 'package:dashbook/dashbook.dart';
+import 'package:examples/commons/commons.dart';
+import 'package:examples/stories/router/router_world_example.dart';
+import 'package:flame/game.dart';
+
+void addRouterStories(Dashbook dashbook) {
+  dashbook.storiesOf('Router').add(
+        'Router with multiple worlds',
+        (_) => GameWidget(game: RouterWorldExample()),
+        codeLink: baseLink('router/router_world_example.dart'),
+        info: RouterWorldExample.description,
+      );
+}