fix: Deprecate HasGameRef in favor of HasGameReference (#3559)

This deprecates `HasGameRef` and suggests users to use
`HasGameReference` instead.

doc/flame/components.md

@@ -1377,7 +1377,7 @@ class Player extends SpriteComponent with Notifier {
 Then our hud component could look like:
 
 ```dart
-class Hud extends PositionComponent with HasGameRef {
+class Hud extends PositionComponent with HasGameReference {
 
   @override
   void onLoad() {

doc/flame/inputs/other_inputs.md

@@ -46,7 +46,7 @@ class MyGame extends FlameGame {
   }
 }
 
-class Player extends SpriteComponent with HasGameRef {
+class Player extends SpriteComponent with HasGameReference {
   Player(this.joystick)
     : super(
         anchor: Anchor.center,

examples/games/rogue_shooter/lib/components/bullet_component.dart

@@ -3,7 +3,7 @@ import 'package:flame/components.dart';
 import 'package:rogue_shooter/components/enemy_component.dart';
 
 class BulletComponent extends SpriteAnimationComponent
-    with HasGameRef, CollisionCallbacks {
+    with HasGameReference, CollisionCallbacks {
   static const speed = 500.0;
   late final Vector2 velocity;
   final Vector2 deltaPosition = Vector2.zero();

examples/games/rogue_shooter/lib/components/enemy_creator.dart

@@ -3,7 +3,7 @@ import 'dart:math';
 import 'package:flame/components.dart';
 import 'package:rogue_shooter/components/enemy_component.dart';
 
-class EnemyCreator extends TimerComponent with HasGameRef {
+class EnemyCreator extends TimerComponent with HasGameReference {
   final Random random = Random();
   final _halfWidth = EnemyComponent.initialSize.x / 2;
 

examples/games/rogue_shooter/lib/components/explosion_component.dart

@@ -1,6 +1,7 @@
 import 'package:flame/components.dart';
 
-class ExplosionComponent extends SpriteAnimationComponent with HasGameRef {
+class ExplosionComponent extends SpriteAnimationComponent
+    with HasGameReference {
   ExplosionComponent({super.position})
       : super(
           size: Vector2.all(50),

examples/games/rogue_shooter/lib/components/player_component.dart

@@ -5,7 +5,7 @@ import 'package:rogue_shooter/components/enemy_component.dart';
 import 'package:rogue_shooter/components/explosion_component.dart';
 
 class PlayerComponent extends SpriteAnimationComponent
-    with HasGameRef, CollisionCallbacks {
+    with HasGameReference, CollisionCallbacks {
   late TimerComponent bulletCreator;
 
   PlayerComponent() : super(size: Vector2(50, 75), anchor: Anchor.center);

examples/games/rogue_shooter/lib/components/star_background_creator.dart

@@ -4,7 +4,7 @@ import 'package:flame/components.dart';
 import 'package:flame/sprite.dart';
 import 'package:rogue_shooter/components/star_component.dart';
 
-class StarBackGroundCreator extends Component with HasGameRef {
+class StarBackGroundCreator extends Component with HasGameReference {
   final gapSize = 12;
 
   late final SpriteSheet spriteSheet;

examples/games/rogue_shooter/lib/components/star_component.dart

@@ -1,6 +1,6 @@
 import 'package:flame/components.dart';
 
-class StarComponent extends SpriteAnimationComponent with HasGameRef {
+class StarComponent extends SpriteAnimationComponent with HasGameReference {
   static const speed = 10;
 
   StarComponent({super.animation, super.position})

examples/lib/stories/camera_and_viewport/follow_component_example.dart

@@ -180,7 +180,7 @@ class Map extends Component {
   }
 }
 
-class Rock extends SpriteComponent with HasGameRef, TapCallbacks {
+class Rock extends SpriteComponent with HasGameReference, TapCallbacks {
   Rock(Vector2 position)
       : super(
           position: position,

examples/lib/stories/collision_detection/collidable_animation_example.dart

@@ -53,7 +53,7 @@ class CollidableAnimationExample extends FlameGame with HasCollisionDetection {
 }
 
 class AnimatedComponent extends SpriteAnimationComponent
-    with CollisionCallbacks, HasGameRef {
+    with CollisionCallbacks, HasGameReference {
   final Vector2 velocity;
 
   AnimatedComponent(

examples/lib/stories/components/composability_example.dart

@@ -30,7 +30,7 @@ class ComposabilityExample extends FlameGame {
   }
 }
 
-class ParentSquare extends RectangleComponent with HasGameRef {
+class ParentSquare extends RectangleComponent with HasGameReference {
   static final defaultPaint = BasicPalette.white.paint()
     ..style = PaintingStyle.stroke;
 

examples/lib/stories/input/joystick_player.dart

@@ -3,7 +3,7 @@ import 'package:flame/components.dart';
 import 'package:flame/game.dart';
 
 class JoystickPlayer extends SpriteComponent
-    with HasGameRef, CollisionCallbacks {
+    with HasGameReference, CollisionCallbacks {
   /// Pixels/s
   double maxSpeed = 300.0;
   late final Vector2 _lastSize = size.clone();

packages/flame/lib/components.dart

@@ -23,6 +23,7 @@ export 'src/components/mixins/coordinate_transform.dart';
 export 'src/components/mixins/gesture_hitboxes.dart';
 export 'src/components/mixins/has_ancestor.dart';
 export 'src/components/mixins/has_decorator.dart' show HasDecorator;
+// ignore: deprecated_member_use_from_same_package
 export 'src/components/mixins/has_game_ref.dart' show HasGameRef;
 export 'src/components/mixins/has_game_reference.dart' show HasGameReference;
 export 'src/components/mixins/has_paint.dart';

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

@@ -452,7 +452,7 @@ class Component {
   ///   - it is invoked when the size of the game canvas is already known.
   ///
   /// If your loading logic requires knowing the size of the game canvas, then
-  /// add [HasGameRef] mixin and then query `game.size` or
+  /// add [HasGameReference] mixin and then query `game.size` or
   /// `game.canvasSize`.
   ///
   /// The default implementation returns `null`, indicating that there is no

packages/flame/lib/src/components/mixins/has_game_ref.dart

@@ -1,5 +1,4 @@
 import 'package:flame/src/components/core/component.dart';
-import 'package:flame/src/components/mixins/has_game_reference.dart';
 import 'package:flame/src/game/flame_game.dart';
 import 'package:flame/src/game/mixins/single_game_instance.dart';
 
@@ -9,9 +8,10 @@ import 'package:flame/src/game/mixins/single_game_instance.dart';
 /// The type [T] on the mixin is the type of your game class. This type will be
 /// the type of the [game] reference, and the mixin will check at runtime that
 /// the actual type matches the expectation.
-///
-/// [HasGameReference] is a newer version of this mixin, and will replace it in
-/// Flame v2.0.
+@Deprecated(
+  'Use HasGameReference instead. This mixin will be removed in a future '
+  'version of Flame.',
+)
 mixin HasGameRef<T extends FlameGame> on Component {
   T? _game;
 

packages/flame/test/components/mixins/has_game_ref_test.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: deprecated_member_use_from_same_package
+
 import 'package:flame/components.dart';
 import 'package:flame/game.dart';
 import 'package:flame_test/flame_test.dart';

packages/flame/test/game/flame_game_test.dart

@@ -420,7 +420,7 @@ class _MyTappableComponent extends _MyComponent with TapCallbacks {
   }
 }
 
-class _MyComponent extends PositionComponent with HasGameRef {
+class _MyComponent extends PositionComponent with HasGameReference {
   bool isUpdateCalled = false;
   bool isRenderCalled = false;
   int onRemoveCallCounter = 0;