feat: add ParentIsA to force parent child relations (#1566)

doc/flame/components.md

@@ -158,6 +158,25 @@ available eventually: after they are loaded and mounted. We can only assure
 that they will appear in the children list in the same order as they were
 scheduled for addition.
 
+### Ensuring a component has a given parent
+
+When a component requires to be added to a specific parent type the 
+`ParentIsA` mixin can be used to enforce a strongly typed parent.
+
+Example:
+
+```dart
+class MyComponent extends Component with ParentIsA<MyParentComponent> {
+  @override
+  Future<void> onLoad() async {
+    // parent is of type MyParentComponent
+    print(parent.myValue);
+  }
+}
+```
+
+If you try to add `MyComponent` to a parent that is not `MyParentComponent`, 
+an assertion error will be thrown.
 
 ### Querying child components
 
@@ -305,7 +324,6 @@ Future<void> onLoad() async {
 Remember that most components that are rendered on the screen are `PositionComponent`s, so
 this pattern can be used in for example [](#spritecomponent) and [](#spriteanimationcomponent) too.
 
-
 ### Render PositionComponent
 
 When implementing the `render` method for a component that extends `PositionComponent` remember to

packages/flame/lib/components.dart

@@ -14,6 +14,7 @@ export 'src/components/mixins/has_game_ref.dart';
 export 'src/components/mixins/has_paint.dart';
 export 'src/components/mixins/hoverable.dart';
 export 'src/components/mixins/keyboard_handler.dart';
+export 'src/components/mixins/parent_is_a.dart';
 export 'src/components/mixins/single_child_particle.dart';
 export 'src/components/mixins/tappable.dart';
 export 'src/components/nine_tile_box_component.dart';

packages/flame/lib/src/components/mixins/parent_is_a.dart

@@ -0,0 +1,13 @@
+import '../../../components.dart';
+
+/// A mixin that ensures a parent is of the given type [T].
+mixin ParentIsA<T extends Component> on Component {
+  @override
+  T get parent => super.parent! as T;
+
+  @override
+  void onMount() {
+    assert(super.parent is T, 'Parent must be of type $T');
+    super.onMount();
+  }
+}

packages/flame/test/components/mixins/parent_is_a_test.dart

@@ -0,0 +1,35 @@
+import 'package:flame/components.dart';
+import 'package:flame_test/flame_test.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+class ParentComponent extends Component {}
+
+class DifferentComponent extends Component {}
+
+class TestComponent extends Component with ParentIsA<ParentComponent> {}
+
+void main() {
+  group('ParentIsA', () {
+    testWithFlameGame('successfully sets the parent link', (game) async {
+      final parent = ParentComponent();
+      final component = TestComponent();
+
+      await parent.add(component);
+      await game.add(parent);
+
+      expect(component.parent, isA<ParentComponent>());
+    });
+
+    test('throws assertion error when the wrong parent is used', () {
+      final parent = DifferentComponent();
+      final component = TestComponent();
+
+      parent.add(component);
+
+      expect(
+        component.onMount,
+        failsAssert('Parent must be of type ParentComponent'),
+      );
+    });
+  });
+}