diff --git a/doc/flame/migration.md b/doc/flame/migration.md index d145b5fe0e2..cd7ef208859 100644 --- a/doc/flame/migration.md +++ b/doc/flame/migration.md @@ -7,6 +7,27 @@ major versions of Flame, together with the steps required to migrate your code. ## Migrating from v1.38.0 to v2.0.0 +### `HasGameRef` removed in favour of `HasGameReference` + +The deprecated `HasGameRef` mixin has been removed. Use `HasGameReference` instead, which is +otherwise identical apart from not offering the `gameRef` alias — use `game`: + +```dart +// Before +class MyComponent extends Component with HasGameRef { + void doSomething() => gameRef.score++; +} + +// After +class MyComponent extends Component with HasGameReference { + void doSomething() => game.score++; +} +``` + +The `game` getter, its setter (useful for mocking in tests), and the `findGame()` override all +behave exactly as before. + + ### `onDragCancel` no longer delegates to `onDragEnd` `DragCallbacks.onDragCancel` used to convert the cancellation into an `onDragEnd` event by default, diff --git a/doc/tutorials/platformer/step_2.md b/doc/tutorials/platformer/step_2.md index df3b788711d..c546ae6e7b0 100644 --- a/doc/tutorials/platformer/step_2.md +++ b/doc/tutorials/platformer/step_2.md @@ -152,7 +152,7 @@ class EmberPlayer extends SpriteAnimationComponent } ``` -This file uses the `HasGameRef` mixin which allows us to reach back to `ember_quest.dart` and +This file uses the `HasGameReference` mixin which allows us to reach back to `ember_quest.dart` and leverage any of the variables or methods that are defined in the game class. You can see this in use with the line `game.images.fromCache('ember.png')`. Earlier, we loaded all the files into cache, so to use that file now, we call `fromCache` so it can be leveraged by the `SpriteAnimation`. diff --git a/doc/tutorials/platformer/step_3.md b/doc/tutorials/platformer/step_3.md index bcf9190e704..e6e09e2084c 100644 --- a/doc/tutorials/platformer/step_3.md +++ b/doc/tutorials/platformer/step_3.md @@ -342,8 +342,8 @@ class PlatformBlock extends SpriteComponent } ``` -We are going to extend the Flame `SpriteComponent` and we will need the `HasGameRef` mixin to access -our game class just like we did before. We are starting with the empty `onLoad` and `update` +We are going to extend the Flame `SpriteComponent` and we will need the `HasGameReference` mixin to +access our game class just like we did before. We are starting with the empty `onLoad` and `update` methods and we will begin adding code to create the functionality that is necessary for the game. The secret to any gaming engine is the game loop. This is an infinite loop that calls all the diff --git a/packages/flame/lib/components.dart b/packages/flame/lib/components.dart index 134b3554c2c..24404ee066c 100644 --- a/packages/flame/lib/components.dart +++ b/packages/flame/lib/components.dart @@ -28,8 +28,6 @@ export 'src/components/mixins/has_ancestor.dart'; export 'src/components/mixins/has_auto_batched_children.dart' show HasAutoBatchedChildren; 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'; export 'src/components/mixins/has_time_scale.dart'; diff --git a/packages/flame/lib/src/components/mixins/has_game_ref.dart b/packages/flame/lib/src/components/mixins/has_game_ref.dart deleted file mode 100644 index decb1b624ef..00000000000 --- a/packages/flame/lib/src/components/mixins/has_game_ref.dart +++ /dev/null @@ -1,49 +0,0 @@ -import 'package:flame/src/components/core/component.dart'; -import 'package:flame/src/game/flame_game.dart'; -import 'package:flame/src/game/mixins/single_game_instance.dart'; - -/// [HasGameRef] mixin provides property [game] (or [gameRef]), which is the -/// cached accessor for the top-level game instance. -/// -/// 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. -@Deprecated( - 'Use HasGameReference instead. This mixin will be removed in a future ' - 'version of Flame.', -) -mixin HasGameRef on Component { - T? _game; - - /// Reference to the top-level Game instance that owns this component. - /// - /// This property is accessible in the component's `onLoad` and later. It may - /// be accessible earlier too, but only if your game uses the - /// [SingleGameInstance] mixin. - T get game => _game ??= _findGameAndCheck(); - - /// Allows you to set the game instance explicitly. This may be useful in - /// tests, or if you're planning to move the component to another game - /// instance. - set game(T? value) => _game = value; - - /// Equivalent to the [game] property. - T get gameRef => game; - - @override - FlameGame? findGame() => _game ?? super.findGame(); - - T _findGameAndCheck() { - final game = findGame(); - assert( - game != null, - 'Could not find Game instance: the component is detached from the ' - 'component tree', - ); - assert( - game! is T, - 'Found game of type ${game.runtimeType}, while type $T was expected', - ); - return game! as T; - } -} diff --git a/packages/flame/test/components/mixins/has_game_ref_test.dart b/packages/flame/test/components/mixins/has_game_ref_test.dart deleted file mode 100644 index 89172539f3e..00000000000 --- a/packages/flame/test/components/mixins/has_game_ref_test.dart +++ /dev/null @@ -1,44 +0,0 @@ -// 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'; -import 'package:mocktail/mocktail.dart'; -import 'package:test/test.dart'; - -class _MyGame extends FlameGame { - bool calledFoo = false; - void foo() { - calledFoo = true; - } -} - -class _FooComponent extends Component with HasGameRef<_MyGame> { - void foo() { - gameRef.foo(); - } -} - -class _BarComponent extends Component with HasGameRef<_MyGame> {} - -class _MockFlameGame extends Mock implements _MyGame {} - -void main() { - group('HasGameRef', () { - testWithGame<_MyGame>('simple test', _MyGame.new, (game) async { - final c = _FooComponent(); - game.add(c); - c.foo(); - expect(game.calledFoo, true); - }); - - testWithGame<_MyGame>('gameRef can be mocked', _MyGame.new, (game) async { - final component = _BarComponent(); - await game.ensureAdd(component); - - component.game = _MockFlameGame(); - - expect(component.gameRef, isA<_MockFlameGame>()); - }); - }); -} diff --git a/packages/flame/test/components/mixins/has_world_test.dart b/packages/flame/test/components/mixins/has_world_test.dart index 3c41c9e21ac..7ff371808dc 100644 --- a/packages/flame/test/components/mixins/has_world_test.dart +++ b/packages/flame/test/components/mixins/has_world_test.dart @@ -20,7 +20,7 @@ class _ParentComponent extends Component { class _ChildComponent extends _ParentComponent with HasWorldReference {} void main() { - group('HasGameRef', () { + group('HasWorldReference', () { testWithGame('onRemove calls super', FlameGame.new, ( game, ) async { diff --git a/packages/flame/test/experimental/has_game_reference_test.dart b/packages/flame/test/experimental/has_game_reference_test.dart index 400c39505fd..46f404b12c5 100644 --- a/packages/flame/test/experimental/has_game_reference_test.dart +++ b/packages/flame/test/experimental/has_game_reference_test.dart @@ -94,7 +94,7 @@ void main() { expect(game.calledFoo, true); }); - testWithGame<_MyGame>('gameRef can be mocked', _MyGame.new, (game) async { + testWithGame<_MyGame>('game can be mocked', _MyGame.new, (game) async { final component = _BarComponent(); await game.ensureAdd(component); diff --git a/packages/flame/test/experimental/has_world_test.dart b/packages/flame/test/experimental/has_world_test.dart index 19bd431f3dd..7c6c168c44b 100644 --- a/packages/flame/test/experimental/has_world_test.dart +++ b/packages/flame/test/experimental/has_world_test.dart @@ -70,7 +70,7 @@ void main() { expect(c.world.calledFoo, isTrue); }); - testWithGame<_MyGame>('gameRef can be mocked', _MyGame.new, (game) async { + testWithGame<_MyGame>('game can be mocked', _MyGame.new, (game) async { final component = _BarComponent(); await game.world.ensureAdd(component);