feat!: Making add,addAll sync methods

doc/bridge_packages/flame_behaviors/getting_started.md

@@ -94,7 +94,7 @@ For instance a `TimerComponent` can implement a time-based behavioral activity:
 class MyBehavior extends Behavior {
   @override
   Future<void> onLoad() async {
-    await add(TimerComponent(period: 5, repeat: true, onTick: _onTick));
+    add(TimerComponent(period: 5, repeat: true, onTick: _onTick));
   }
 
   void _onTick() {

doc/bridge_packages/flame_bloc/bloc.md

@@ -22,7 +22,7 @@ We can do that by using `FlameBlocProvider` component:
 class MyGame extends FlameGame {
   @override
   Future<void> onLoad() async {
-    await add(
+    add(
       FlameBlocProvider<PlayerInventoryBloc, PlayerInventoryState>(
         create: () => PlayerInventoryBloc(),
         children: [
@@ -44,7 +44,7 @@ fashion:
 class MyGame extends FlameGame {
   @override
   Future<void> onLoad() async {
-    await add(
+    add(
       FlameMultiBlocProvider(
         providers: [
           FlameBlocProvider<PlayerInventoryBloc, PlayerInventoryState>(
@@ -72,7 +72,7 @@ By using `FlameBlocListener` component:
 class Player extends PositionComponent {
   @override
   Future<void> onLoad() async {
-    await add(
+    add(
       FlameBlocListener<PlayerInventoryBloc, PlayerInventoryState>(
         listener: (state) {
           updateGear(state);

doc/bridge_packages/flame_spine/flame_spine.md

@@ -40,7 +40,7 @@ class FlameSpineExample extends FlameGame {
 
   // Set the "walk" animation on track 0 in looping mode
   spineboy.animationState.setAnimationByName(0, 'walk', true);
-  await add(spineboy);
+  add(spineboy);
  }
 
  @override

doc/flame/components/components.md

@@ -212,6 +212,19 @@ class MyGame extends FlameGame {
 The two approaches can be combined freely: the children specified within the constructor will be
 added first, and then any additional child components after.
 
+The `add()`, `addAll()`, and `addToParent()` methods are synchronous: they return immediately
+without waiting for the child to load or mount. This makes them safe to call from anywhere,
+including inside `update()` or a loop that spawns many components, without having to `await` them
+or wrap them in `unawaited`. If you need to wait until a child has reached a given lifecycle stage,
+await its `loaded`, `mounted`, or `removed` future instead (see the lifecycle getters under
+[Component lifecycle](#component-lifecycle)):
+
+```dart
+world.add(coin);
+await coin.mounted;
+// The coin is now guaranteed to be mounted.
+```
+
 Note that the children added via either method 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.

doc/flame/examples/lib/anchor.dart

@@ -25,12 +25,12 @@ class AnchorGame extends FlameGame {
       paint: BasicPalette.blue.paint(),
     );
 
-    await _redComponent.addAll([
+    _redComponent.addAll([
       _blueComponent,
       CircleComponent(radius: 2, anchor: Anchor.center),
     ]);
 
-    await addAll([
+    addAll([
       _redComponent,
       _parentAnchorText,
       _childAnchorText,

doc/flame/examples/lib/time_scale.dart

@@ -10,7 +10,7 @@ class TimeScaleGame extends FlameGame with HasTimeScale {
 
   @override
   Future<void> onLoad() async {
-    await add(
+    add(
       EmberPlayer(
         position: size / 2,
         size: size / 4,

doc/flame/game.md

@@ -38,8 +38,8 @@ class MyCrate extends SpriteComponent {
 
 class MyWorld extends World {
   @override
-  Future<void> onLoad() async {
-    await add(MyCrate());
+  void onLoad() {
+    add(MyCrate());
   }
 }
 
@@ -236,8 +236,8 @@ application. This is a common scenario when building games: there is a single fu
 
 Adding this mixin provides performance advantages in certain scenarios. In particular, a component's
 `onLoad` method is guaranteed to start when that component is added to its parent, even if the
-parent is not yet mounted itself. Consequently, `await`-ing on `parent.add(component)` is guaranteed
-to always finish loading the component.
+parent is not yet mounted itself. Consequently, awaiting `component.loaded` after
+`parent.add(component)` is guaranteed to finish loading the component.
 
 Using this mixin is simple:
 

doc/tutorials/platformer/app/lib/overlays/hud.dart

@@ -44,7 +44,7 @@ class Hud extends PositionComponent with HasGameReference<EmberQuestGame> {
 
     for (var i = 1; i <= game.health; i++) {
       final positionX = 40 * i;
-      await add(
+      add(
         HeartHealthComponent(
           heartNumber: i,
           position: Vector2(positionX.toDouble(), 20),

doc/tutorials/platformer/step_6.md

@@ -128,7 +128,7 @@ class Hud extends PositionComponent with HasGameReference<EmberQuestGame> {
 
     for (var i = 1; i <= game.health; i++) {
       final positionX = 40 * i;
-      await add(
+      add(
         HeartHealthComponent(
           heartNumber: i,
           position: Vector2(positionX.toDouble(), 20),

examples/games/crystal_ball/lib/src/game/components/camera_target.dart

@@ -14,7 +14,7 @@ class CameraTarget extends PositionComponent
 
   @override
   Future<void> onLoad() async {
-    await add(moveEffect);
+    add(moveEffect);
   }
 
   void go({

examples/games/crystal_ball/lib/src/game/components/input_handler.dart

@@ -14,7 +14,7 @@ class InputHandler extends PositionComponent
 
   @override
   Future<void> onLoad() async {
-    await add(
+    add(
       KeyboardListenerComponent(
         keyDown: {
           LogicalKeyboardKey.arrowLeft: (_) => onLeftStart(),

examples/lib/stories/animations/benchmark_example.dart

@@ -20,7 +20,7 @@ starts to drop in FPS, this is without any sprite batching and such.
 
   @override
   Future<void> onLoad() async {
-    await camera.viewport.addAll([
+    camera.viewport.addAll([
       FpsTextComponent(
         position: size - Vector2(10, 50),
         anchor: Anchor.bottomRight,

examples/lib/stories/bridge_libraries/flame_forge2d/blob_example.dart

@@ -29,10 +29,12 @@ class BlobWorld extends Forge2DWorld
       ..dampingRatio = 1.0
       ..collideConnected = false;
 
-    await addAll([
+    final blobParts = [
       for (var i = 0; i < 20; i++)
         BlobPart(i, jointDef, blobRadius, blobCenter),
-    ]);
+    ];
+    addAll(blobParts);
+    await Future.wait(blobParts.map((part) => part.loaded));
     createJoint(ConstantVolumeJoint(physicsWorld, jointDef));
   }
 

examples/lib/stories/bridge_libraries/flame_forge2d/joints/rope_joint.dart

@@ -36,7 +36,8 @@ class RopeJointWorld extends Forge2DWorld
       width: handleWidth,
       height: 3,
     );
-    await add(box);
+    add(box);
+    await box.loaded;
 
     createPrismaticJoint(box.body, anchor);
     return box.body;
@@ -49,7 +50,8 @@ class RopeJointWorld extends Forge2DWorld
     for (var i = 0; i < length; i++) {
       final newPosition = prevBody.worldCenter + Vector2(0, 1);
       final ball = Ball(newPosition, radius: 0.5, color: Colors.white);
-      await add(ball);
+      add(ball);
+      await ball.loaded;
 
       createRopeJoint(ball.body, prevBody);
       prevBody = ball.body;

examples/lib/stories/bridge_libraries/flame_forge2d/joints/weld_joint.dart

@@ -40,7 +40,8 @@ class WeldJointWorld extends Forge2DWorld
       color: Colors.white,
     );
 
-    await addAll([leftPillar, rightPillar]);
+    addAll([leftPillar, rightPillar]);
+    await Future.wait([leftPillar.loaded, rightPillar.loaded]);
 
     createBridge(leftPillar, rightPillar);
   }
@@ -71,7 +72,8 @@ class WeldJointWorld extends Forge2DWorld
         width: sectionWidth,
         height: 1,
       );
-      await add(section);
+      add(section);
+      await section.loaded;
 
       if (prevSection != null) {
         createWeldJoint(

examples/lib/stories/bridge_libraries/flame_jenny/components/dialogue_box.dart

@@ -16,7 +16,7 @@ class DialogueBoxComponent extends SpriteComponent with HasGameReference {
       'dialogue_box.png',
       srcSize: spriteSize,
     );
-    await addAll([buttonRow, textBox]);
+    addAll([buttonRow, textBox]);
     return super.onLoad();
   }
 

examples/lib/stories/bridge_libraries/flame_spine/basic_spine_example.dart

@@ -41,7 +41,7 @@ class FlameSpineExample extends FlameGame with TapCallbacks {
 
     // Set the "walk" animation on track 0 in looping mode
     spineboy.animationState.setAnimation(0, 'walk', true);
-    await add(spineboy);
+    add(spineboy);
   }
 
   @override

examples/lib/stories/bridge_libraries/flame_spine/shared_data_spine_example.dart

@@ -45,7 +45,7 @@ class SharedDataSpineExample extends FlameGame with TapCallbacks {
       spineboy.animationState.setAnimation(0, 'walk', true);
       spineboys.add(spineboy);
     }
-    await addAll(spineboys);
+    addAll(spineboys);
   }
 
   @override

examples/lib/stories/camera_and_viewport/camera_component_example.dart

@@ -171,7 +171,8 @@ class AntWorld extends World {
   Future<void> onLoad() async {
     final random = Random();
     curve = DragonCurve();
-    await add(curve);
+    add(curve);
+    await curve.loaded;
     bgRect = curve.boundingRect().inflate(100);
 
     const baseColor = HSVColor.fromAHSV(1, 38.5, 0.63, 0.68);

examples/lib/stories/camera_and_viewport/camera_component_properties_example.dart

@@ -46,7 +46,7 @@ class CameraComponentPropertiesExample extends FlameGame {
         ..strokeWidth = 0.25
         ..color = const Color(0xaaffff00),
     );
-    await world.add(_cullRect);
+    world.add(_cullRect);
     camera.mounted.then((_) {
       updateSize(canvasSize);
     });

examples/lib/stories/collision_detection/multiple_worlds_example.dart

@@ -24,7 +24,7 @@ class MultipleWorldsExample extends FlameGame {
     final world2 = CollisionDetectionWorld();
     final camera1 = CameraComponent(world: world1);
     final camera2 = CameraComponent(world: world2);
-    await addAll([world1, world2, camera1, camera2]);
+    addAll([world1, world2, camera1, camera2]);
     final ember1 = CollidableEmber(position: Vector2(75, 75));
     final ember2 = CollidableEmber(position: Vector2(-75, 75));
     final ember3 = CollidableEmber(position: Vector2(75, -75));

examples/lib/stories/components/component_pool_example.dart

@@ -56,7 +56,7 @@ class _BallWorld extends World with TapCallbacks {
 
     // Add a stats display to show pool information
     statsDisplay = _StatsDisplay(pool: ballPool);
-    await add(statsDisplay);
+    add(statsDisplay);
   }
 
   @override

examples/lib/stories/components/keys_example.dart

@@ -77,7 +77,7 @@ class KeysExampleGame extends FlameGame {
     final mage = await loadSprite('mage.png');
     final ranger = await loadSprite('ranger.png');
 
-    await addAll([
+    addAll([
       SelectableClass(
         key: ComponentKey.named('knight'),
         sprite: knight,

examples/lib/stories/components/time_scale_example.dart

@@ -47,7 +47,7 @@ class TimeScaleExample extends FlameGame
     );
     gameSpeedText.position = Vector2(size.x * 0.5, size.y * 0.8);
 
-    await world.addAll([
+    world.addAll([
       _Chopper(
         position: Vector2(-100, -10),
         size: Vector2.all(64),
@@ -96,8 +96,8 @@ class _Chopper extends SpriteAnimationComponent
 
   @override
   Future<void> onLoad() async {
-    await add(CircleHitbox());
-    await add(_timer);
+    add(CircleHitbox());
+    add(_timer);
     return super.onLoad();
   }
 

examples/lib/stories/system/step_engine_example.dart

@@ -55,7 +55,7 @@ class StepEngineExample extends FlameGame
       hudComponents: [_controlsText],
     );
 
-    await addAll([world, cameraComponent]);
+    addAll([world, cameraComponent]);
   }
 
   @override

packages/flame/benchmark/collision_detection_benchmark.dart

@@ -40,7 +40,7 @@ class FlatCollisionBenchmark extends AsyncBenchmarkBase {
       ),
     );
 
-    await _game.addAll(_blocks);
+    _game.addAll(_blocks);
     await _game.ready();
   }
 
@@ -96,7 +96,7 @@ class NestedCollisionBenchmark extends AsyncBenchmarkBase {
       components.add(parent);
     }
 
-    await _game.addAll(components);
+    _game.addAll(components);
     await _game.ready();
   }
 

packages/flame/benchmark/component_churn_benchmark.dart

@@ -48,13 +48,13 @@ class ComponentChurnBenchmark extends AsyncBenchmarkBase {
   Future<void> setup() async {
     _game = FlameGame();
     await mountGame(_game);
-    await _game.world.addAll(
+    _game.world.addAll(
       List.generate(staticPopulation, (_) => Component()),
     );
     for (var i = 0; i < _liveBatches; i++) {
       final batch = _newBatch();
       _batches.addLast(batch);
-      await _game.world.addAll(batch);
+      _game.world.addAll(batch);
     }
     await _game.ready();
   }
@@ -65,7 +65,7 @@ class ComponentChurnBenchmark extends AsyncBenchmarkBase {
       _game.world.removeAll(_batches.removeFirst());
       final batch = _newBatch();
       _batches.addLast(batch);
-      await _game.world.addAll(batch);
+      _game.world.addAll(batch);
       _game.update(_dt);
     }
   }
@@ -97,7 +97,7 @@ class MassAddRemoveBenchmark extends AsyncBenchmarkBase {
   Future<void> run() async {
     for (var i = 0; i < _amountCycles; i++) {
       final components = List.generate(_amountComponents, (_) => Component());
-      await _game.world.addAll(components);
+      _game.world.addAll(components);
       _game.update(_dt);
       _game.world.removeAll(components);
       _game.update(_dt);

packages/flame/benchmark/priority_change_benchmark.dart

@@ -47,7 +47,7 @@ class SiblingPriorityChangeBenchmark extends AsyncBenchmarkBase {
         ),
       ),
     );
-    await _game.world.addAll(parents);
+    _game.world.addAll(parents);
     await _game.ready();
     _children = [
       for (final parent in parents) parent.children.toList(growable: false),
@@ -98,7 +98,7 @@ class YSortPriorityBenchmark extends AsyncBenchmarkBase {
     final random = Random(_randomSeed);
     _game = FlameGame();
     await mountGame(_game);
-    await _game.world.addAll(
+    _game.world.addAll(
       List.generate(_amountChildren, (i) => Component(priority: i)),
     );
     await _game.ready();