docs: Fix examples for v1.9.0 (#2757)

Fixed up some examples that needed fixing before releasing v1.9.0

examples/lib/stories/animations/benchmark_example.dart

@@ -21,16 +21,16 @@ starts to drop in FPS, this is without any sprite batching and such.
   Future<void> onLoad() async {
     await camera.viewport.addAll([
       FpsTextComponent(
-        position: size - Vector2(0, 50),
+        position: size - Vector2(10, 50),
         anchor: Anchor.bottomRight,
       ),
       emberCounter = TextComponent(
-        position: size - Vector2(0, 25),
+        position: size - Vector2(10, 25),
         anchor: Anchor.bottomRight,
         priority: 1,
       ),
     ]);
-    world.add(Ember(size: emberSize, position: size / 2));
+    world.add(Ember(size: emberSize));
     children.register<Ember>();
   }
 

examples/lib/stories/camera_and_viewport/camera_and_viewport.dart

@@ -2,6 +2,7 @@ import 'package:dashbook/dashbook.dart';
 import 'package:examples/commons/commons.dart';
 import 'package:examples/stories/camera_and_viewport/camera_component_example.dart';
 import 'package:examples/stories/camera_and_viewport/camera_component_properties_example.dart';
+import 'package:examples/stories/camera_and_viewport/camera_follow_and_world_bounds.dart';
 import 'package:examples/stories/camera_and_viewport/coordinate_systems_example.dart';
 import 'package:examples/stories/camera_and_viewport/fixed_resolution_example.dart';
 import 'package:examples/stories/camera_and_viewport/follow_component_example.dart';
@@ -74,5 +75,12 @@ void addCameraAndViewportStories(Dashbook dashbook) {
         'camera_and_viewport/camera_component_properties_example.dart',
       ),
       info: CameraComponentPropertiesExample.description,
+    )
+    ..add(
+      'Follow and World bounds',
+      (_) => GameWidget(game: CameraFollowAndWorldBoundsExample()),
+      codeLink:
+          baseLink('camera_and_viewport/camera_follow_and_world_bounds.dart'),
+      info: CameraFollowAndWorldBoundsExample.description,
     );
 }

examples/lib/stories/camera_and_viewport/fixed_resolution_example.dart

@@ -14,22 +14,18 @@ class FixedResolutionExample extends FlameGame
     Resize the window or change device orientation to see the difference.
   ''';
 
-  final Vector2 viewportResolution;
-
   FixedResolutionExample({
-    required this.viewportResolution,
+    required Vector2 viewportResolution,
-  });
+  }) : super(
+          camera: CameraComponent.withFixedResolution(
+            width: viewportResolution.x,
+            height: viewportResolution.y,
+          ),
+        );
 
   @override
   Future<void> onLoad() async {
     final flameSprite = await loadSprite('layers/player.png');
-    final world = World();
-    final cameraComponent = CameraComponent.withFixedResolution(
-      width: viewportResolution.x,
-      height: viewportResolution.y,
-      world: world,
-    );
-    addAll([world, cameraComponent]);
 
     world.add(Background());
     world.add(

examples/lib/stories/camera_and_viewport/follow_component_example.dart

@@ -23,20 +23,19 @@ class FollowComponentExample extends FlameGame
     respects the camera transformation.
   ''';
 
-  FollowComponentExample({required this.viewportResolution});
+  FollowComponentExample({required this.viewportResolution})
+      : super(
+          camera: CameraComponent.withFixedResolution(
+            width: viewportResolution.x,
+            height: viewportResolution.y,
+          ),
+        );
 
   late MovableEmber ember;
   final Vector2 viewportResolution;
 
   @override
   Future<void> onLoad() async {
-    final world = World();
-    camera = CameraComponent.withFixedResolution(
-      width: viewportResolution.x,
-      height: viewportResolution.y,
-      world: world,
-    );
-
     world.add(Map());
     world.add(ember = MovableEmber());
     camera.setBounds(Map.bounds);
@@ -58,6 +57,8 @@ class MovableEmber extends Ember<FollowComponentExample>
   final Vector2 velocity = Vector2.zero();
   late final TextComponent positionText;
   late final Vector2 textPosition;
+  late final maxPosition = Vector2.all(Map.size - size.x / 2);
+  late final minPosition = -maxPosition;
 
   MovableEmber() : super(priority: 2);
 
@@ -78,6 +79,7 @@ class MovableEmber extends Ember<FollowComponentExample>
     super.update(dt);
     final deltaPosition = velocity * (speed * dt);
     position.add(deltaPosition);
+    position.clamp(minPosition, maxPosition);
     positionText.text = '(${x.toInt()}, ${y.toInt()})';
   }
 

examples/lib/stories/camera_and_viewport/zoom_example.dart

@@ -9,24 +9,20 @@ class ZoomExample extends FlameGame with ScrollDetector, ScaleDetector {
   ''';
 
   ZoomExample({
-    required this.viewportResolution,
+    required Vector2 viewportResolution,
-  });
+  }) : super(
-
+          camera: CameraComponent.withFixedResolution(
-  final Vector2 viewportResolution;
+            width: viewportResolution.x,
-  late SpriteComponent flame;
+            height: viewportResolution.y,
+          ),
+        );
 
   @override
   Future<void> onLoad() async {
     final flameSprite = await loadSprite('flame.png');
 
-    camera = CameraComponent.withFixedResolution(
-      world: world,
-      width: viewportResolution.x,
-      height: viewportResolution.y,
-    );
-
     world.add(
-      flame = SpriteComponent(
+      SpriteComponent(
         sprite: flameSprite,
         size: Vector2(149, 211),
       )..anchor = Anchor.center,

examples/lib/stories/collision_detection/quadtree_example.dart

@@ -204,23 +204,24 @@ class Player extends SpriteComponent
     required super.position,
     required super.size,
     required super.priority,
-  }) {
-    Sprite.load(
-      'retro_tiles.png',
-      srcSize: Vector2.all(tileSize),
-      srcPosition: Vector2(tileSize * 3, tileSize),
-    ).then((value) {
-      sprite = value;
   });
 
-    add(hitbox);
-  }
-
-  final hitbox = RectangleHitbox();
   bool canMoveLeft = true;
   bool canMoveRight = true;
   bool canMoveTop = true;
   bool canMoveBottom = true;
+  final hitbox = RectangleHitbox();
+
+  @override
+  Future<void> onLoad() async {
+    sprite = await Sprite.load(
+      'retro_tiles.png',
+      srcSize: Vector2.all(tileSize),
+      srcPosition: Vector2(tileSize * 3, tileSize),
+    );
+
+    add(hitbox);
+  }
 
   @override
   void onCollisionStart(

examples/lib/stories/components/keys_example.dart

@@ -36,9 +36,9 @@ class _KeysExampleWidgetState extends State<KeysExampleWidget> {
           child: GameWidget(game: game),
         ),
         Positioned(
-          left: 0,
+          left: 20,
           top: 222,
-          width: 340,
+          width: 300,
           child: Row(
             mainAxisAlignment: MainAxisAlignment.spaceBetween,
             children: [

examples/lib/stories/experimental/experimental.dart

@@ -1,21 +1,13 @@
 import 'package:dashbook/dashbook.dart';
 import 'package:examples/commons/commons.dart';
-import 'package:examples/stories/experimental/camera_follow_and_world_bounds.dart';
 import 'package:examples/stories/experimental/shapes.dart';
 import 'package:flame/game.dart';
 
 void addExperimentalStories(Dashbook dashbook) {
-  dashbook.storiesOf('Experimental')
+  dashbook.storiesOf('Experimental').add(
-    ..add(
         'Shapes',
         (_) => GameWidget(game: ShapesExample()),
         codeLink: baseLink('experimental/shapes.dart'),
         info: ShapesExample.description,
-    )
-    ..add(
-      'Follow and World bounds',
-      (_) => GameWidget(game: CameraFollowAndWorldBoundsExample()),
-      codeLink: baseLink('experimental/camera_follow_and_world_bounds.dart'),
-      info: CameraFollowAndWorldBoundsExample.description,
       );
 }

examples/lib/stories/input/gesture_hitboxes_example.dart

@@ -27,12 +27,12 @@ class _GestureHitboxesWorld extends World with TapCallbacks {
     final shapeSize =
         Vector2.all(100) + Vector2.all(50.0).scaled(_rng.nextDouble());
     final shapeAngle = _rng.nextDouble() * 6;
-    final hitbox = () {
+    ShapeHitbox hitbox;
     switch (shapeType) {
       case Shapes.circle:
-          return CircleHitbox();
+        hitbox = CircleHitbox();
       case Shapes.rectangle:
-          return RectangleHitbox();
+        hitbox = RectangleHitbox();
       case Shapes.polygon:
         final points = [
           -Vector2.random(_rng),
@@ -40,9 +40,8 @@ class _GestureHitboxesWorld extends World with TapCallbacks {
           Vector2.random(_rng),
           Vector2.random(_rng)..y *= -1,
         ];
-          return PolygonHitbox.relative(points, parentSize: shapeSize);
+        hitbox = PolygonHitbox.relative(points, parentSize: shapeSize);
     }
-    }();
     return MyShapeComponent(
       hitbox: hitbox,
       position: position,

examples/lib/stories/input/joystick_advanced_example.dart

@@ -33,7 +33,7 @@ class JoystickAdvancedExample extends FlameGame with HasCollisionDetection {
       columns: 6,
       rows: 1,
     );
-    world.add(ScreenHitbox()..anchor = camera.viewfinder.anchor);
+    world.add(ScreenHitbox());
     joystick = JoystickComponent(
       knob: SpriteComponent(
         sprite: sheet.getSpriteById(1),
@@ -179,14 +179,16 @@ class JoystickAdvancedExample extends FlameGame with HasCollisionDetection {
     )..add(directionText);
 
     world.add(player);
-    camera.viewport.add(joystick);
+    camera.viewport.addAll([
-    camera.viewport.add(flipButton);
+      joystick,
-    camera.viewport.add(flopButton);
+      flipButton,
-    camera.viewport.add(buttonComponent);
+      flopButton,
-    camera.viewport.add(spriteButtonComponent);
+      buttonComponent,
-    camera.viewport.add(shapeButton);
+      spriteButtonComponent,
-    camera.viewport.add(speedWithMargin);
+      shapeButton,
-    camera.viewport.add(directionWithMargin);
+      speedWithMargin,
+      directionWithMargin,
+    ]);
   }
 
   @override

examples/lib/stories/input/joystick_example.dart

@@ -25,7 +25,7 @@ class JoystickExample extends FlameGame {
     );
     player = JoystickPlayer(joystick);
 
-    add(player);
+    world.add(player);
-    add(joystick);
+    camera.viewport.add(joystick);
   }
 }

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

@@ -7,13 +7,17 @@ import 'package:flame/src/collisions/hitboxes/rectangle_hitbox.dart';
 /// viewport of the game.
 class ScreenHitbox<T extends FlameGame> extends PositionComponent
     with CollisionCallbacks, HasGameReference<T> {
+  bool _hasWorldAncestor = false;
   @override
   Future<void> onLoad() async {
     await super.onLoad();
     add(RectangleHitbox());
+    _hasWorldAncestor = findParent<World>() != null;
+    if (_hasWorldAncestor) {
       game.camera.viewfinder.transform.addListener(_updatePosition);
       _updatePosition();
     }
+  }
 
   void _updatePosition() {
     final viewfinder = game.camera.viewfinder;
@@ -26,6 +30,8 @@ class ScreenHitbox<T extends FlameGame> extends PositionComponent
   void onGameResize(Vector2 size) {
     super.onGameResize(size);
     this.size = size;
+    if (_hasWorldAncestor) {
       _updatePosition();
     }
+  }
 }

packages/flame/lib/src/extensions/vector2.dart

@@ -108,6 +108,13 @@ extension Vector2Extension on Vector2 {
     }
   }
 
+  /// Clamps this vector so that it is within or equals to the bounds defined by
+  /// [min] and [max].
+  void clamp(Vector2 min, Vector2 max) {
+    x = x.clamp(min.x, max.x);
+    y = y.clamp(min.y, max.y);
+  }
+
   /// Project this onto [other].
   ///
   /// [other] needs to have a length > 0;