feat: add ParentIsA to force parent child relations

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'),
+ );
+ });
+ });
+}