feat: Added children parameter to Component constructor (#1525)

doc/flame/components.md

@@ -93,6 +93,7 @@ the component we change the priority to 2.
 Sometimes it is useful to wrap other components inside of your component. For example by grouping
 visual components through a hierarchy. You can do this by adding child components to any component,
 for example `PositionComponent`.
+
 When you have child components on a component every time the parent is updated and rendered, all the
 children are rendered and updated with the same conditions.
 
@@ -122,6 +123,41 @@ class GameOverPanel extends PositionComponent with HasGameRef<MyGame> {
 }
 ```
 
+There are two methods for adding children components to your component. First,
+you have methods `add()`, `addAll()`, and `addToParent()`, which can be used
+at any time during the game. Traditionally, children will be created and added
+from the component's `onLoad()` method, but it is also common to add new
+children during the course of the game.
+
+The second method is to use the `children:` parameter in the component's
+constructor. This approach more closely resembles the standard Flutter API:
+```dart
+class MyGame extends FlameGame {
+  @override
+  Future<void> onLoad() async {
+    add(
+      PositionComponent(
+        position: Vector2(30, 0),
+        children: [
+          HighScoreDisplay(),
+          HitPointsDisplay(),
+          FpsCounter(),
+        ],
+      ),
+    );
+  }
+}
+```
+
+The two approaches can be combined freely: the children specified within the
+constructor will be added first, and then any additional child components
+after.
+
+Note that the children added via either methods are only guaranteed to be
+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.
+
 
 ### Querying child components
 
@@ -516,7 +552,7 @@ parallax), you can do it in a few different ways depending on how fine-grained y
 settings for each layer.
 
 They simplest way is to set the named optional parameters `baseVelocity` and
-`velocityMultiplierDelta` in the `load` helper function. For example if you want to move your 
+`velocityMultiplierDelta` in the `load` helper function. For example if you want to move your
 background images along the X-axis with a faster speed the "closer" the image is:
 
 ```dart

packages/flame/lib/src/collisions/hitboxes/composite_hitbox.dart

@@ -9,4 +9,22 @@ import '../../../components.dart';
 /// those hitboxes to an instance of this class and react to collisions to the
 /// whole hat, instead of for just each hitbox separately.
 class CompositeHitbox extends PositionComponent
-    with CollisionCallbacks, CollisionPassthrough {}
+    with CollisionCallbacks, CollisionPassthrough {
+  CompositeHitbox({
+    Vector2? position,
+    Vector2? size,
+    Vector2? scale,
+    double? angle,
+    Anchor? anchor,
+    Iterable<ShapeHitbox>? children,
+    int? priority,
+  }) : super(
+          position: position,
+          size: size,
+          scale: scale,
+          angle: angle,
+          anchor: anchor,
+          children: children,
+          priority: priority,
+        );
+}

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

@@ -17,7 +17,12 @@ import '../cache/value_cache.dart';
 /// called automatically once the component is added to the component tree in
 /// your game (with `game.add`).
 class Component {
-  Component({int? priority}) : _priority = priority ?? 0;
+  Component({Iterable<Component>? children, int? priority})
+      : _priority = priority ?? 0 {
+    if (children != null) {
+      addAll(children);
+    }
+  }
 
   /// What coordinate system this component should respect (i.e. should it
   /// observe camera, viewport, or use the raw canvas).

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

@@ -22,13 +22,15 @@ class CustomPainterComponent extends PositionComponent {
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   }) : super(
           position: position,
           size: size,
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         );
 

packages/flame/lib/src/components/input/button_component.dart

@@ -26,13 +26,15 @@ class ButtonComponent extends PositionComponent with Tappable {
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   }) : super(
           position: position,
           size: size ?? button?.size,
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         );
 

packages/flame/lib/src/components/input/hud_button_component.dart

@@ -34,6 +34,7 @@ class HudButtonComponent extends HudMarginComponent with Tappable {
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   }) : super(
           margin: margin,
@@ -42,6 +43,7 @@ class HudButtonComponent extends HudMarginComponent with Tappable {
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         );
 

packages/flame/lib/src/components/input/hud_margin_component.dart

@@ -30,6 +30,7 @@ class HudMarginComponent<T extends FlameGame> extends PositionComponent
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   })  : assert(
           margin != null || position != null,
@@ -41,6 +42,7 @@ class HudMarginComponent<T extends FlameGame> extends PositionComponent
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         );
 

packages/flame/lib/src/components/input/joystick_component.dart

@@ -53,6 +53,7 @@ class JoystickComponent extends HudMarginComponent with Draggable {
     double? size,
     double? knobRadius,
     Anchor anchor = Anchor.center,
+    Iterable<Component>? children,
     int? priority,
   })  : assert(
           size != null || background != null,
@@ -68,6 +69,7 @@ class JoystickComponent extends HudMarginComponent with Draggable {
           position: position,
           size: background?.size ?? Vector2.all(size ?? 0),
           anchor: anchor,
+          children: children,
           priority: priority,
         ) {
     this.knobRadius = knobRadius ?? this.size.x / 2;

packages/flame/lib/src/components/input/sprite_button_component.dart

@@ -27,6 +27,7 @@ class SpriteButtonComponent extends SpriteGroupComponent<_ButtonState>
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   }) : super(
           current: _ButtonState.up,
@@ -35,6 +36,7 @@ class SpriteButtonComponent extends SpriteGroupComponent<_ButtonState>
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         );
 

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

@@ -62,13 +62,15 @@ class IsometricTileMapComponent extends PositionComponent {
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   }) : super(
           position: position,
           size: size,
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         );
 

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

@@ -22,13 +22,15 @@ class NineTileBoxComponent extends PositionComponent {
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   }) : super(
           position: position,
           size: size,
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         );
 

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

@@ -66,6 +66,7 @@ class ParallaxComponent<T extends FlameGame> extends PositionComponent
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   })  : _parallax = parallax,
         isFullscreen = size == null && !(parallax?.isSized ?? false),
@@ -75,6 +76,7 @@ class ParallaxComponent<T extends FlameGame> extends PositionComponent
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         );
 

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

@@ -66,11 +66,12 @@ class PositionComponent extends Component
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   })  : transform = Transform2D(),
         _anchor = anchor ?? Anchor.topLeft,
         _size = NotifyingVector2.copy(size ?? Vector2.zero()),
-        super(priority: priority) {
+        super(children: children, priority: priority) {
     if (position != null) {
       transform.position = position;
     }

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

@@ -29,6 +29,7 @@ class SpriteAnimationComponent extends PositionComponent with HasPaint {
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   })  : removeOnFinish = removeOnFinish ?? false,
         playing = playing ?? true,
@@ -38,6 +39,7 @@ class SpriteAnimationComponent extends PositionComponent with HasPaint {
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         ) {
     if (paint != null) {

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

@@ -27,6 +27,7 @@ class SpriteAnimationGroupComponent<T> extends PositionComponent with HasPaint {
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   })  : removeOnFinish = removeOnFinish ?? const {},
         super(
@@ -35,6 +36,7 @@ class SpriteAnimationGroupComponent<T> extends PositionComponent with HasPaint {
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         ) {
     if (paint != null) {

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

@@ -25,13 +25,15 @@ class SpriteComponent extends PositionComponent with HasPaint {
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   }) : super(
           position: position,
           size: size ?? sprite?.srcSize,
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         ) {
     if (paint != null) {

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

@@ -25,13 +25,15 @@ class SpriteGroupComponent<T> extends PositionComponent with HasPaint {
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   }) : super(
           position: position,
           size: size,
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         ) {
     if (paint != null) {

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

@@ -69,6 +69,7 @@ class TextBoxComponent<T extends TextRenderer> extends TextComponent {
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   })  : _boxConfig = boxConfig ?? TextBoxConfig(),
         pixelRatio = pixelRatio ?? window.devicePixelRatio,
@@ -79,6 +80,7 @@ class TextBoxComponent<T extends TextRenderer> extends TextComponent {
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         );
 

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

@@ -33,6 +33,7 @@ class TextComponent<T extends TextRenderer> extends PositionComponent {
     Vector2? scale,
     double? angle,
     Anchor? anchor,
+    Iterable<Component>? children,
     int? priority,
   })  : _text = text ?? '',
         _textRenderer = textRenderer ?? TextRenderer.createDefault<T>(),
@@ -42,6 +43,7 @@ class TextComponent<T extends TextRenderer> extends PositionComponent {
           scale: scale,
           angle: angle,
           anchor: anchor,
+          children: children,
           priority: priority,
         ) {
     updateBounds();

packages/flame/lib/src/experimental/circular_viewport.dart

@@ -1,11 +1,13 @@
 import 'dart:ui';
 import 'package:vector_math/vector_math_64.dart';
 
+import '../components/component.dart';
 import 'viewport.dart';
 
 /// A fixed-size viewport in the shape of a circle.
 class CircularViewport extends Viewport {
-  CircularViewport(double radius) {
+  CircularViewport(double radius, {Iterable<Component>? children})
+      : super(children: children) {
     size = Vector2.all(2 * radius);
   }
 

packages/flame/lib/src/experimental/fixed_aspect_ratio_viewport.dart

@@ -2,11 +2,15 @@ import 'dart:ui';
 
 import 'package:vector_math/vector_math_64.dart';
 
+import '../components/component.dart';
 import 'viewport.dart';
 
 class FixedAspectRatioViewport extends Viewport {
-  FixedAspectRatioViewport({required this.aspectRatio})
-      : assert(aspectRatio > 0);
+  FixedAspectRatioViewport({
+    required this.aspectRatio,
+    Iterable<Component>? children,
+  })  : assert(aspectRatio > 0),
+        super(children: children);
 
   final double aspectRatio;
   Rect _clipRect = Rect.zero;