Merge branch 'main' into chore/remove-end-override

analysis_options.yaml

@@ -1,4 +1 @@
 include: package:very_good_analysis/analysis_options.2.4.0.yaml
-linter:
-  rules:
-    public_member_api_docs: false

lib/app/view/app.dart

@@ -5,6 +5,8 @@
 // license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'package:flutter_localizations/flutter_localizations.dart';
 import 'package:pinball/l10n/l10n.dart';

lib/bootstrap.dart

@@ -5,6 +5,8 @@
 // license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+// ignore_for_file: public_member_api_docs
+
 import 'dart:async';
 import 'dart:developer';
 

lib/game/bloc/game_bloc.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: public_member_api_docs
+
 import 'package:bloc/bloc.dart';
 import 'package:equatable/equatable.dart';
 import 'package:meta/meta.dart';

lib/game/bloc/game_event.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: public_member_api_docs
+
 part of 'game_bloc.dart';
 
 @immutable
@@ -5,16 +7,22 @@ abstract class GameEvent extends Equatable {
   const GameEvent();
 }
 
+/// {@template ball_lost_game_event}
 /// Event added when a user drops a ball off the screen.
+/// {@endtemplate}
 class BallLost extends GameEvent {
+  /// {@macro ball_lost_game_event}
   const BallLost();
 
   @override
   List<Object?> get props => [];
 }
 
+/// {@template scored_game_event}
 /// Event added when a user increases their score.
+/// {@endtemplate}
 class Scored extends GameEvent {
+  /// {@macro scored_game_event}
   const Scored({
     required this.points,
   }) : assert(points > 0, 'Points must be greater than 0');

lib/game/bloc/game_state.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: public_member_api_docs
+
 part of 'game_bloc.dart';
 
 /// {@template game_state}

lib/game/components/ball.dart

@@ -3,29 +3,36 @@ import 'package:flame_bloc/flame_bloc.dart';
 import 'package:flame_forge2d/flame_forge2d.dart';
 import 'package:pinball/game/game.dart';
 
+/// {@template ball}
+/// A solid, [BodyType.dynamic] sphere that rolls and bounces along the
+/// [PinballGame].
+/// {@endtemplate}
 class Ball extends PositionBodyComponent<PinballGame, SpriteComponent>
     with BlocComponent<GameBloc, GameState> {
+  /// {@macro ball}
   Ball({
     required Vector2 position,
   })  : _position = position,
-        super(size: ballSize);
+        super(size: Vector2.all(2));
-
-  static final ballSize = Vector2.all(2);
 
+  /// The initial position of the [Ball] body.
   final Vector2 _position;
 
+  /// Asset location of the sprite that renders with the [Ball].
+  ///
+  /// Sprite is preloaded by [PinballGameAssetsX].
   static const spritePath = 'components/ball.png';
 
   @override
   Future<void> onLoad() async {
     await super.onLoad();
     final sprite = await gameRef.loadSprite(spritePath);
-    positionComponent = SpriteComponent(sprite: sprite, size: ballSize);
+    positionComponent = SpriteComponent(sprite: sprite, size: size);
   }
 
   @override
   Body createBody() {
-    final shape = CircleShape()..radius = ballSize.x / 2;
+    final shape = CircleShape()..radius = size.x / 2;
 
     final fixtureDef = FixtureDef(shape)..density = 1;
 
@@ -37,6 +44,11 @@ class Ball extends PositionBodyComponent<PinballGame, SpriteComponent>
     return world.createBody(bodyDef)..createFixture(fixtureDef);
   }
 
+  /// Removes the [Ball] from a [PinballGame]; spawning a new [Ball] if
+  /// any are left.
+  ///
+  /// Triggered by [BottomWallBallContactCallback] when the [Ball] falls into
+  /// a [BottomWall].
   void lost() {
     shouldRemove = true;
 

lib/game/components/flipper.dart

@@ -1,9 +1,9 @@
 import 'dart:async';
 import 'dart:math' as math;
 
+import 'package:flame/components.dart' show SpriteComponent;
 import 'package:flame/input.dart';
 import 'package:flame_forge2d/flame_forge2d.dart';
-import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:pinball/game/game.dart';
 
@@ -12,19 +12,15 @@ import 'package:pinball/game/game.dart';
 ///
 /// [Flipper] can be controlled by the player in an arc motion.
 /// {@endtemplate flipper}
-class Flipper extends BodyComponent with KeyboardHandler {
+class Flipper extends PositionBodyComponent with KeyboardHandler {
   /// {@macro flipper}
   Flipper._({
     required Vector2 position,
     required this.side,
     required List<LogicalKeyboardKey> keys,
   })  : _position = position,
-        _keys = keys {
+        _keys = keys,
-    // TODO(alestiago): Use sprite instead of color when provided.
+        super(size: Vector2(width, height));
-    paint = Paint()
-      ..color = const Color(0xFF00FF00)
-      ..style = PaintingStyle.fill;
-  }
 
   /// A left positioned [Flipper].
   Flipper.left({
@@ -50,6 +46,11 @@ class Flipper extends BodyComponent with KeyboardHandler {
           ],
         );
 
+  /// Asset location of the sprite that renders with the [Flipper].
+  ///
+  /// Sprite is preloaded by [PinballGameAssetsX].
+  static const spritePath = 'components/flipper.png';
+
   /// The width of the [Flipper].
   static const width = 12.0;
 
@@ -75,6 +76,20 @@ class Flipper extends BodyComponent with KeyboardHandler {
   /// [onKeyEvent] method listens to when one of these keys is pressed.
   final List<LogicalKeyboardKey> _keys;
 
+  @override
+  Future<void> onLoad() async {
+    await super.onLoad();
+    final sprite = await gameRef.loadSprite(spritePath);
+    positionComponent = SpriteComponent(
+      sprite: sprite,
+      size: size,
+    );
+
+    if (side == BoardSide.right) {
+      positionComponent?.flipHorizontally();
+    }
+  }
+
   /// Applies downward linear velocity to the [Flipper], moving it to its
   /// resting position.
   void _moveDown() {
@@ -148,6 +163,7 @@ class Flipper extends BodyComponent with KeyboardHandler {
 
   // TODO(erickzanardo): Remove this once the issue is solved:
   // https://github.com/flame-engine/flame/issues/1417
+  // ignore: public_member_api_docs
   final Completer hasMounted = Completer<void>();
 
   @override

lib/game/components/wall.dart

@@ -6,13 +6,18 @@ import 'package:pinball/game/components/components.dart';
 /// {@template wall}
 /// A continuos generic and [BodyType.static] barrier that divides a game area.
 /// {@endtemplate}
+// TODO(alestiago): Remove [Wall] for [Pathway.straight].
 class Wall extends BodyComponent {
+  /// {@macro wall}
   Wall({
     required this.start,
     required this.end,
   });
 
+  /// The [start] of the [Wall].
   final Vector2 start;
+
+  /// The [end] of the [Wall].
   final Vector2 end;
 
   @override
@@ -39,6 +44,7 @@ class Wall extends BodyComponent {
 /// [BottomWallBallContactCallback].
 /// {@endtemplate}
 class BottomWall extends Wall {
+  /// {@macro bottom_wall}
   BottomWall(Forge2DGame game)
       : super(
           start: game.screenToWorld(game.camera.viewport.effectiveSize),

lib/game/game_assets.dart

@@ -6,6 +6,7 @@ extension PinballGameAssetsX on PinballGame {
   Future<void> preLoadAssets() async {
     await Future.wait([
       images.load(Ball.spritePath),
+      images.load(Flipper.spritePath),
     ]);
   }
 }

lib/game/pinball_game.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: public_member_api_docs
+
 import 'dart:async';
 import 'package:flame/input.dart';
 import 'package:flame_bloc/flame_bloc.dart';

lib/game/view/pinball_game_page.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: public_member_api_docs
+
 import 'package:flame/game.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';

lib/game/view/widgets/game_over_dialog.dart

@@ -1,6 +1,11 @@
 import 'package:flutter/material.dart';
+import 'package:pinball/game/game.dart';
 
+/// {@template game_over_dialog}
+/// [Dialog] displayed when the [PinballGame] is over.
+/// {@endtemplate}
 class GameOverDialog extends StatelessWidget {
+  /// {@macro game_over_dialog}
   const GameOverDialog({Key? key}) : super(key: key);
 
   @override

lib/l10n/l10n.dart

@@ -5,6 +5,8 @@
 // license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/widgets.dart';
 import 'package:flutter_gen/gen_l10n/app_localizations.dart';
 

lib/landing/view/landing_page.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'package:pinball/game/game.dart';
 import 'package:pinball/l10n/l10n.dart';

lib/theme/cubit/theme_cubit.dart

@@ -1,3 +1,6 @@
+// ignore_for_file: public_member_api_docs
+// TODO(allisonryan0002): Document this section when the API is stable.
+
 import 'package:bloc/bloc.dart';
 import 'package:equatable/equatable.dart';
 import 'package:pinball_theme/pinball_theme.dart';

lib/theme/cubit/theme_state.dart

@@ -1,3 +1,6 @@
+// ignore_for_file: public_member_api_docs
+// TODO(allisonryan0002): Document this section when the API is stable.
+
 part of 'theme_cubit.dart';
 
 class ThemeState extends Equatable {

test/game/components/anchor_test.dart

@@ -15,6 +15,7 @@ void main() {
       'loads correctly',
       (game) async {
         final anchor = Anchor(position: Vector2.zero());
+        await game.ready();
         await game.ensureAdd(anchor);
 
         expect(game.contains(anchor), isTrue);
@@ -25,6 +26,7 @@ void main() {
       flameTester.test(
         'positions correctly',
         (game) async {
+          await game.ready();
           final position = Vector2.all(10);
           final anchor = Anchor(position: position);
           await game.ensureAdd(anchor);
@@ -37,6 +39,7 @@ void main() {
       flameTester.test(
         'is static',
         (game) async {
+          await game.ready();
           final anchor = Anchor(position: Vector2.zero());
           await game.ensureAdd(anchor);
 

test/game/components/pathway_test.dart

@@ -18,6 +18,7 @@ void main() {
         flameTester.test(
           'has transparent color by default when no color is specified',
           (game) async {
+            await game.ready();
             final pathway = Pathway.straight(
               position: Vector2.zero(),
               start: Vector2(10, 10),
@@ -38,6 +39,7 @@ void main() {
         flameTester.test(
           'has a color when is specified',
           (game) async {
+            await game.ready();
             const defaultColor = Colors.blue;
 
             final pathway = Pathway.straight(
@@ -59,6 +61,7 @@ void main() {
       flameTester.test(
         'loads correctly',
         (game) async {
+          await game.ready();
           final pathway = Pathway.straight(
             position: Vector2.zero(),
             start: Vector2(10, 10),
@@ -75,6 +78,7 @@ void main() {
         flameTester.test(
           'positions correctly',
           (game) async {
+            await game.ready();
             final position = Vector2.all(10);
             final pathway = Pathway.straight(
               position: position,
@@ -92,6 +96,7 @@ void main() {
         flameTester.test(
           'is static',
           (game) async {
+            await game.ready();
             final pathway = Pathway.straight(
               position: Vector2.zero(),
               start: Vector2(10, 10),
@@ -109,6 +114,7 @@ void main() {
         flameTester.test(
           'has only one ChainShape when singleWall is true',
           (game) async {
+            await game.ready();
             final pathway = Pathway.straight(
               position: Vector2.zero(),
               start: Vector2(10, 10),
@@ -128,6 +134,7 @@ void main() {
         flameTester.test(
           'has two ChainShape when singleWall is false (default)',
           (game) async {
+            await game.ready();
             final pathway = Pathway.straight(
               position: Vector2.zero(),
               start: Vector2(10, 10),
@@ -150,6 +157,7 @@ void main() {
       flameTester.test(
         'loads correctly',
         (game) async {
+          await game.ready();
           final pathway = Pathway.arc(
             position: Vector2.zero(),
             width: width,
@@ -166,6 +174,7 @@ void main() {
         flameTester.test(
           'positions correctly',
           (game) async {
+            await game.ready();
             final position = Vector2.all(10);
             final pathway = Pathway.arc(
               position: position,
@@ -183,6 +192,7 @@ void main() {
         flameTester.test(
           'is static',
           (game) async {
+            await game.ready();
             final pathway = Pathway.arc(
               position: Vector2.zero(),
               width: width,
@@ -208,6 +218,7 @@ void main() {
       flameTester.test(
         'loads correctly',
         (game) async {
+          await game.ready();
           final pathway = Pathway.bezierCurve(
             position: Vector2.zero(),
             controlPoints: controlPoints,
@@ -223,6 +234,7 @@ void main() {
         flameTester.test(
           'positions correctly',
           (game) async {
+            await game.ready();
             final position = Vector2.all(10);
             final pathway = Pathway.bezierCurve(
               position: position,
@@ -239,6 +251,7 @@ void main() {
         flameTester.test(
           'is static',
           (game) async {
+            await game.ready();
             final pathway = Pathway.bezierCurve(
               position: Vector2.zero(),
               controlPoints: controlPoints,

test/game/components/plunger_test.dart

@@ -16,6 +16,7 @@ void main() {
     flameTester.test(
       'loads correctly',
       (game) async {
+        await game.ready();
         final plunger = Plunger(position: Vector2.zero());
         await game.ensureAdd(plunger);
 

test/game/components/wall_test.dart

@@ -37,6 +37,7 @@ void main() {
     flameTester.test(
       'loads correctly',
       (game) async {
+        await game.ready();
         final wall = Wall(
           start: Vector2.zero(),
           end: Vector2(100, 0),