feat: Loading builder for Route

packages/flame/lib/src/components/route.dart

@@ -24,9 +24,11 @@ class Route extends PositionComponent
     with ParentIsA<RouterComponent>, HasTimeScale {
   Route(
     Component Function()? builder, {
+    Component Function()? loadingBuilder,
     this.transparent = false,
     this.maintainState = true,
   })  : _builder = builder,
+        _loadingBuilder = loadingBuilder,
         _renderEffect = Decorator();
 
   /// If true, then the route below this one will continue to be rendered when
@@ -53,6 +55,11 @@ class Route extends PositionComponent
   /// in which case the user must override the [build] method.
   final Component Function()? _builder;
 
+  /// The function that will be invoked that will build the loading page
+  /// component when this route first becomes active. Can be left `null`,
+  /// in which case it is not required.
+  final Component Function()? _loadingBuilder;
+
   /// This method is invoked when the route is pushed on top of the
   /// [RouterComponent]'s stack.
   ///
@@ -118,17 +125,31 @@ class Route extends PositionComponent
   /// also be added as a child component.
   Component? _page;
 
+  /// The loadingPage that was built and is now owned by this route. This
+  /// loadingPage will also be added as a child component.
+  Component? _loadingPage;
+
   /// Additional visual effect that may be applied to the page during rendering.
   final Decorator _renderEffect;
 
   /// Invoked by the [RouterComponent] when this route is pushed to the top
-  /// of the navigation stack.
+  /// of the navigation stack
   @internal
   void didPush(Route? previousRoute) {
-    _page ??= build()..addToParent(this);
+    _page ??= build();
+    (_loadingBuilder != null) ? _addLoadingPage() : _page!.addToParent(this);
     onPush(previousRoute);
   }
 
+  /// Adds the [_loadingPage] to the parent and invoked by [didPush] , when
+  /// [_loadingBuilder] is specified
+  Future<void> _addLoadingPage() async {
+    _loadingPage ??= _loadingBuilder!()..addToParent(this);
+    await _page!.addToParent(this);
+    await _page!.loaded;
+    _loadingPage!.removeFromParent();
+  }
+
   /// Invoked by the [RouterComponent] when this route is popped off the top
   /// of the navigation stack.
   /// If [maintainState] is false, the page component rendered by this route

packages/flame/test/components/route_test.dart

@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:ui';
 
 import 'package:flame/components.dart';
@@ -474,6 +475,51 @@ void main() {
         );
       },
     );
+    testWithFlameGame('Route with loading', (game) async {
+      final loadingComponent = PositionComponent(size: Vector2.all(100));
+      final pageComponent = _HeavyComponent()..size = Vector2.all(100);
+      final router = RouterComponent(
+        initialRoute: 'start',
+        routes: {
+          'start': Route(
+            Component.new,
+          ),
+          'new': Route(
+            () => pageComponent,
+            loadingBuilder: () => loadingComponent,
+          ),
+        },
+      )..addToParent(game);
+      await game.ready();
+
+      router.pushNamed('new');
+
+      // I can't perform this following checking, probably because the way it 
+      // was implemented, in assumption that line 512 actually logically works.
+      // If line 512, is doing nothing then I don't think, I can perform this 
+      // following check either, that is to check state when loading was 
+      // mounted before it was removed.
+
+      // expect(
+      //   loadingComponent.isMounted,
+      //   isTrue,
+      // );
+      // expect(
+      //   pageComponent.isMounted,
+      //   isFalse,
+      // );
+
+      game.update(pageComponent.dummyTime.inSeconds.toDouble());
+      await game.ready();
+      expect(
+        loadingComponent.isRemoved,
+        isFalse,
+      );
+      expect(
+        pageComponent.isMounted,
+        isTrue,
+      );
+    });
   });
 }
 
@@ -527,3 +573,12 @@ class _ColoredComponent extends PositionComponent {
     canvas.drawRect(size.toRect(), _paint);
   }
 }
+
+class _HeavyComponent extends PositionComponent {
+  final dummyTime = const Duration(seconds: 3);
+  @override
+  FutureOr<void> onLoad() async {
+    await Future.delayed(dummyTime);
+    return super.onLoad();
+  }
+}