feat: Added AlignComponent layout component

doc/flame/components.md

@@ -39,6 +39,9 @@ Every `Component` has a few methods that you can optionally implement, which are
 The `onGameResize` method is called whenever the screen is resized, and also when this component
 gets added into the component tree, before the `onMount`.
 
+The `onParentResize` method is similar: it is also called when the component is mounted into the
+component tree, and also whenever the parent of the current component changes its size.
+
 The `onRemove` method can be overridden to run code before the component is removed from the game,
 it is only run once even if the component is removed both by using the parents remove method and
 the `Component` remove method.

doc/flame/flame.md

@@ -12,6 +12,7 @@
 - [Camera Component](camera_component.md)
 - [Inputs](inputs/inputs.md)
 - [Rendering](rendering/rendering.md)
+- [Layout](layout/layout.md)
 - [Other](other/other.md)
 
 ```{toctree}
@@ -29,5 +30,6 @@ Camera & Viewport    <camera_and_viewport.md>
 Camera Component     <camera_component.md>
 Inputs               <inputs/inputs.md>
 Rendering            <rendering/rendering.md>
+Layout               <layout/layout.md>
 Other                <other/other.md>
 ```

doc/flame/layout/align_component.md

@@ -0,0 +1,10 @@
+# AlignComponent
+
+```{dartdoc}
+:package: flame
+:symbol: AlignComponent
+:file: src/layout/align_component.dart
+
+[Align]: https://api.flutter.dev/flutter/widgets/Align-class.html
+[Alignment]: https://api.flutter.dev/flutter/painting/Alignment-class.html
+```

doc/flame/layout/layout.md

@@ -0,0 +1,7 @@
+# Layout
+
+```{toctree}
+:hidden:
+
+AlignComponent   <align_component.md>
+```

examples/lib/main.dart

@@ -11,6 +11,7 @@ import 'package:examples/stories/effects/effects.dart';
 import 'package:examples/stories/experimental/experimental.dart';
 import 'package:examples/stories/games/games.dart';
 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/sprites/sprites.dart';
@@ -39,6 +40,7 @@ void main() {
   addEffectsStories(dashbook);
   addExperimentalStories(dashbook);
   addInputStories(dashbook);
+  addLayoutStories(dashbook);
   addParallaxStories(dashbook);
   addRenderingStories(dashbook);
   addTiledStories(dashbook);

examples/lib/stories/components/game_in_game_example.dart

@@ -36,9 +36,10 @@ class GameChangeTimer extends TimerComponent
   @override
   void onTick() {
     final child = gameRef.draggablesGame.square;
-    final newParent = child.parent == gameRef.draggablesGame
-        ? gameRef.composedGame.parentSquare
-        : gameRef.draggablesGame;
-    child.changeParent(newParent);
+    if (child.parent == gameRef.draggablesGame) {
+      child.parent = gameRef.composedGame.parentSquare;
+    } else {
+      child.parent = gameRef.draggablesGame;
+    }
   }
 }

examples/lib/stories/layout/align_component.dart

@@ -0,0 +1,94 @@
+import 'package:flame/components.dart';
+import 'package:flame/effects.dart';
+import 'package:flame/game.dart';
+import 'package:flame/layout.dart';
+
+class AlignComponentExample extends FlameGame {
+  static const String description = '''
+    In this example the AlignComponent is used to arrange the circles
+    so that there is one in the middle and 8 more surrounding it in
+    the shape of a diamond.
+
+    The arrangement will remain intact if you change the window size.
+  ''';
+
+  @override
+  void onLoad() {
+    addAll([
+      AlignComponent(
+        child: CircleComponent(radius: 40)
+          ..add(
+            SizeEffect.by(
+              Vector2.all(25),
+              EffectController(
+                infinite: true,
+                duration: 0.75,
+                reverseDuration: 0.5,
+              ),
+            ),
+          )
+          ..add(
+            AlignComponent(
+              alignment: Anchor.topCenter,
+              child: CircleComponent(radius: 10, anchor: Anchor.bottomCenter),
+              keepChildAnchor: true,
+            ),
+          )
+          ..add(
+            AlignComponent(
+              alignment: Anchor.bottomCenter,
+              child: CircleComponent(radius: 10, anchor: Anchor.topCenter),
+              keepChildAnchor: true,
+            ),
+          )
+          ..add(
+            AlignComponent(
+              alignment: Anchor.centerLeft,
+              child: CircleComponent(radius: 10, anchor: Anchor.centerRight),
+              keepChildAnchor: true,
+            ),
+          )
+          ..add(
+            AlignComponent(
+              alignment: Anchor.centerRight,
+              child: CircleComponent(radius: 10, anchor: Anchor.centerLeft),
+              keepChildAnchor: true,
+            ),
+          ),
+        alignment: Anchor.center,
+      ),
+      AlignComponent(
+        child: CircleComponent(radius: 30),
+        alignment: Anchor.topCenter,
+      ),
+      AlignComponent(
+        child: CircleComponent(radius: 30),
+        alignment: Anchor.bottomCenter,
+      ),
+      AlignComponent(
+        child: CircleComponent(radius: 30),
+        alignment: Anchor.centerLeft,
+      ),
+      AlignComponent(
+        child: CircleComponent(radius: 30),
+        alignment: Anchor.centerRight,
+      ),
+      AlignComponent(
+        child: CircleComponent(radius: 10),
+        alignment: const Anchor(0.25, 0.25),
+      ),
+      AlignComponent(
+        child: CircleComponent(radius: 10),
+        alignment: const Anchor(0.25, 0.75),
+      ),
+      AlignComponent(
+        child: CircleComponent(radius: 10),
+        alignment: const Anchor(0.75, 0.25),
+      ),
+      AlignComponent(
+        child: CircleComponent(radius: 10),
+        alignment: const Anchor(0.75, 0.75),
+      ),
+    ]);
+  }
+}

examples/lib/stories/layout/layout.dart

@@ -0,0 +1,13 @@
+import 'package:dashbook/dashbook.dart';
+import 'package:examples/commons/commons.dart';
+import 'package:examples/stories/layout/align_component.dart';
+import 'package:flame/game.dart';
+
+void addLayoutStories(Dashbook dashbook) {
+  dashbook.storiesOf('Layout').add(
+        'AlignComponent',
+        (_) => GameWidget(game: AlignComponentExample()),
+        codeLink: baseLink('layout/align_component.dart'),
+        info: AlignComponentExample.description,
+      );
+}

packages/flame/lib/layout.dart

@@ -0,0 +1 @@
+export 'src/layout/align_component.dart' show AlignComponent;

packages/flame/lib/src/camera/viewport.dart

@@ -66,6 +66,9 @@ abstract class Viewport extends Component
       camera.viewfinder.onViewportResize();
     }
     onViewportResize();
+    if (hasChildren) {
+      children.forEach((child) => child.onParentResize(_size));
+    }
   }
 
   /// Reference to the parent camera.

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

@@ -1,6 +1,7 @@
 import 'dart:async';
 
 import 'package:collection/collection.dart';
+import 'package:flame/effects.dart';
 import 'package:flame/src/cache/value_cache.dart';
 import 'package:flame/src/components/core/component_set.dart';
 import 'package:flame/src/components/core/component_tree_root.dart';
@@ -474,6 +475,14 @@ class Component {
   /// [onMount] call before.
   void onRemove() {}
 
+  /// Called whenever the parent of this component changes size; and also once
+  /// before [onMount].
+  ///
+  /// The component may change its own size or perform layout in response to
+  /// this call. If the component changes size, then it should call
+  /// [onParentResize] for all its children.
+  void onParentResize(Vector2 maxSize) {}
+
   /// This method is called periodically by the game engine to request that your
   /// component updates itself.
   ///
@@ -827,6 +836,9 @@ class Component {
     assert(isLoaded && !isLoading);
     _setMountingBit();
     onGameResize(_parent!.findGame()!.canvasSize);
+    if (_parent is SizeProvider) {
+      onParentResize((_parent! as SizeProvider).size);
+    }
     if (isRemoved) {
       _clearRemovedBit();
     } else if (isRemoving) {

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

@@ -68,6 +68,7 @@ class PositionComponent extends Component
         AngleProvider,
         PositionProvider,
         ScaleProvider,
+        SizeProvider,
         CoordinateTransform {
   PositionComponent({
     Vector2? position,
@@ -184,8 +185,16 @@ class PositionComponent extends Component
   /// This property can be reassigned at runtime, although this is not
   /// recommended. Instead, in order to make the [PositionComponent] larger
   /// or smaller, change its [scale].
+  @override
   NotifyingVector2 get size => _size;
-  set size(Vector2 size) => _size.setFrom(size);
+
+  @override
+  set size(Vector2 size) {
+    _size.setFrom(size);
+    if (hasChildren) {
+      children.forEach((child) => child.onParentResize(_size));
+    }
+  }
 
   /// The width of the component in local coordinates. Note that the object
   /// may visually appear larger or smaller due to application of [scale].

packages/flame/lib/src/game/flame_game.dart

@@ -2,6 +2,7 @@ import 'dart:ui';
 
 import 'package:flame/components.dart';
 import 'package:flame/src/components/core/component_tree_root.dart';
+import 'package:flame/src/effects/provider_interfaces.dart';
 import 'package:flame/src/game/camera/camera.dart';
 import 'package:flame/src/game/camera/camera_wrapper.dart';
 import 'package:flame/src/game/game.dart';
@@ -15,7 +16,7 @@ import 'package:meta/meta.dart';
 ///
 /// This is the recommended base class to use for most games made with Flame.
 /// It is based on the Flame Component System (also known as FCS).
-class FlameGame extends ComponentTreeRoot with Game {
+class FlameGame extends ComponentTreeRoot with Game implements SizeProvider {
   FlameGame({
     super.children,
     Camera? camera,
@@ -111,6 +112,7 @@ class FlameGame extends ComponentTreeRoot with Game {
     // there is no way to explicitly call the [Component]'s implementation,
     // we propagate the event to [FlameGame]'s children manually.
     handleResize(canvasSize);
+    children.forEach((child) => child.onParentResize(canvasSize));
   }
 
   /// Ensure that all pending tree operations finish.
@@ -182,4 +184,9 @@ class FlameGame extends ComponentTreeRoot with Game {
       }
     }
   }
+
+  @override
+  set size(Vector2 value) {
+    throw UnsupportedError('The size of FlameGame cannot be set explicitly');
+  }
 }