feat: Integration of flame_riverpod

packages/flame_riverpod/CHANGELOG.md

@@ -0,0 +1,58 @@
+## 4.0.0+2
+
+* Miscellaneous format post-processing on the files. 
+
+## 4.0.0+1
+
+* Miscellaneous tidy-up of package internals.
+
+## 4.0.0
+
+* Made [WidgetRef] property on [ComponentRef] private. It should not be accessed directly. 
+* Removed the [riverpodAwar`eGameProvider]. If required, this is better handled at the application-level.
+
+## 3.0.0
+
+* Changes to focus on [FlameGame].
+  * [riverpodAwareGameProvider] now expects a [FlameGame].
+  * Removed the [HasComponentRef] on Game.
+  * Renamed [RiverpodComponentMixin] to [HasComponentRef]
+* [HasComponentRef] now has a static setter for a WidgetRef. Components that use the new [HasComponentRef] mixin no
+longer need to explicitly provide a [ComponentRef].
+* Renamed the [WidgetRef] property on the [ComponentRef] to [widgetRef].
+* Updated Example to reflect changes.
+* Updated README to reflect changes.
+
+## 2.0.0
+
+* Pruned the public API, removing custom widget definitions (these have now been defined inside the example for 
+reference)
+* Renamed [RiverpodAwareGameMixin] -> [HasComponentRef] to bring closer to the Flame 'house-style' for mixins.
+
+## 1.1.0+2
+
+* Another correction to README and example code. onMount should not call super.onLoad.
+
+## 1.1.0+1
+
+* Correction to README to reflect API change.
+
+## 1.1.0
+
+* Added [RiverpodComponentMixin] to handle disposing of [ProviderSubscription]s.
+* Correction to the [RiverpodGameWidget] initializeGame constructor - param is now 
+ [RiverpodAwareGameMixin Function (ref)] as originally intended.
+
+## 1.0.0+1
+
+* Reduced package description length.
+* Ran dart format.
+
+## 1.0.0
+
+* Initial release.
+  * ComponentRef
+  * riverpodAwareGameProvider
+  * RiverpodAwareFlameGame
+  * RiverpodAwareGame
+  * RiverpodGameWidget

packages/flame_riverpod/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Blue Fire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/flame_riverpod/README.md

@@ -0,0 +1,76 @@
+# flame_riverpod
+
+Riverpod is a reactive caching and data-binding framework for Dart & Flutter.
+
+In `flutter_riverpod`, widgets can be configured to rebuild when the state
+of a provider changes.
+
+When using Flame, we are interacting with components, which are *not* Widgets.
+
+`flame_riverpod` provides the `ComponentRef` and `HasComponentRef` to
+facilitate managing state from Providers in your Flame Game.
+
+
+## Usage
+
+Your Widget that extends `FlameGame` should use the HasComponentRef mixin,
+and accept a WidgetRef inside its constructor, and should be wrapped in a
+ConsumerStatefulWidget, as per the example.
+
+The `listen` method can be used within any Component that uses the
+HasComponentMixin to subscribe to updates from a provider.
+
+Alternatively, you could use `ref.read` as you would elsewhere when consuming `flutter_riverpod`.
+
+Subscriptions to a provider are managed in accordance with the lifecycle
+of a Flame Component: initialization occurs when a Component is mounted, and disposal
+occurs when a Component is removed.
+
+```dart
+
+/// An excerpt from the Example. Check it out!
+class RefExampleGame extends FlameGame with HasComponentRef {
+  RefExampleGame(WidgetRef ref) {
+    HasComponentRef.widgetRef = ref;
+  }
+
+  @override
+  onLoad() async {
+    await super.onLoad();
+    add(TextComponent(text: 'Flame'));
+    add(RiverpodAwareTextComponent());
+  }
+}
+
+class RiverpodAwareTextComponent extends PositionComponent
+    with HasComponentRef {
+
+  late TextComponent textComponent;
+  int currentValue = 0;
+
+  /// [onMount] should be used over [onLoad] to initialize subscriptions,
+  /// cancellation is handled for the user inside [onRemove],
+  /// which is only called if the [Component] was mounted.
+  @override
+  void onMount() {
+    super.onMount();
+    add(textComponent = TextComponent(position: position + Vector2(0, 27)));
+
+    // "Watch" a provider using [listen] from the [HasComponentRef] mixin.
+    // Watch is not exposed directly as this would rebuild the ancestor that
+    // exposes the [WidgetRef] unnecessarily.
+    listen(countingStreamProvider, (p0, p1) {
+      if (p1.hasValue) {
+        currentValue = p1.value!;
+        textComponent.text = '$currentValue';
+      }
+    });
+  }
+}
+
+```
+
+
+## Credits
+
+[Mark Videon](https://markvideon.dev) for the initial groundwork and implementation.

packages/flame_riverpod/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:flame_lint/analysis_options.yaml

packages/flame_riverpod/example/README.md

@@ -0,0 +1,10 @@
+# flame_riverpod_example
+
+The example consists of a very simple FlameGame with a custom
+Component, updated alongside a comparable Flutter widget.
+
+Both the Component and the Widget depend on a `StreamProvider`
+that counts upwards indefinitely.
+
+Both a Flame Component and a Flutter Text Widget update in real-time from
+the same data source.

packages/flame_riverpod/example/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:flame_lint/analysis_options.yaml

packages/flame_riverpod/example/lib/main.dart

@@ -0,0 +1,158 @@
+import 'dart:async';
+
+import 'package:flame/components.dart' hide Timer;
+import 'package:flame/game.dart';
+import 'package:flame_riverpod/flame_riverpod.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+final countingStreamProvider = StreamProvider<int>((ref) {
+  return Stream.periodic(const Duration(seconds: 1), (inc) => inc);
+});
+
+/// Simple provider that returns a [FlameGame] instance.
+final riverpodAwareGameProvider =
+    StateNotifierProvider<RiverpodAwareGameNotifier, FlameGame?>((ref) {
+  return RiverpodAwareGameNotifier();
+});
+
+/// Simple [StateNotifier] that holds the current [FlameGame] instance.
+class RiverpodAwareGameNotifier extends StateNotifier<FlameGame?> {
+  RiverpodAwareGameNotifier() : super(null);
+
+  void set(FlameGame candidate) {
+    state = candidate;
+  }
+}
+
+void main() {
+  runApp(const ProviderScope(child: MyApp()));
+}
+
+class MyApp extends StatelessWidget {
+  const MyApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: 'Flutter Demo',
+      home: Row(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: const [
+          Expanded(child: FlutterCountingComponent()),
+          Expanded(
+            child: RiverpodGameWidget.initializeWithGame(
+              uninitializedGame: RefExampleGame.new,
+            ),
+          )
+        ],
+      ),
+    );
+  }
+}
+
+class FlutterCountingComponent extends ConsumerWidget {
+  const FlutterCountingComponent({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final textStyle = Theme.of(context)
+        .textTheme
+        .headlineSmall
+        ?.copyWith(color: Colors.white);
+
+    final stream = ref.watch(countingStreamProvider);
+    return Material(
+      color: Colors.transparent,
+      child: Column(
+        children: [
+          Text('Flutter', style: textStyle),
+          stream.when(
+            data: (value) => Text('$value', style: textStyle),
+            error: (error, stackTrace) => Text('$error', style: textStyle),
+            loading: () => Text('Loading...', style: textStyle),
+          )
+        ],
+      ),
+    );
+  }
+}
+
+class RefExampleGame extends FlameGame with HasComponentRef {
+  RefExampleGame(WidgetRef ref) {
+    // Note: WidgetRef is not stored and is used to build a [ComponentRef],
+    // a wrapper around it.
+    HasComponentRef.widgetRef = ref;
+  }
+
+  @override
+  Future<void> onLoad() async {
+    await super.onLoad();
+    add(TextComponent(text: 'Flame'));
+    add(RiverpodAwareTextComponent());
+  }
+}
+
+class RiverpodGameWidget extends ConsumerStatefulWidget {
+  const RiverpodGameWidget.readFromProvider({super.key})
+      : uninitializedGame = null;
+  const RiverpodGameWidget.initializeWithGame({
+    super.key,
+    required this.uninitializedGame,
+  });
+
+  final FlameGame Function(WidgetRef ref)? uninitializedGame;
+
+  @override
+  ConsumerState<RiverpodGameWidget> createState() => _RiverpodGameWidgetState();
+}
+
+class _RiverpodGameWidgetState extends ConsumerState<RiverpodGameWidget> {
+  @override
+  void initState() {
+    WidgetsBinding.instance.addPostFrameCallback((timeStamp) {
+      if (widget.uninitializedGame is FlameGame Function(WidgetRef ref)) {
+        ref
+            .read(riverpodAwareGameProvider.notifier)
+            .set(widget.uninitializedGame!(ref));
+      }
+    });
+    super.initState();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final game = ref.watch(riverpodAwareGameProvider);
+
+    if (game is! Game) {
+      return Container();
+    }
+
+    return GameWidget(game: game!);
+  }
+}
+
+class RiverpodAwareTextComponent extends PositionComponent
+    with HasComponentRef {
+  late TextComponent textComponent;
+  int currentValue = 0;
+
+  /// [onMount] should be used over [onLoad] to initialize subscriptions,
+  /// cancellation is handled for the user inside [onRemove],
+  /// which is only called if the [Component] was mounted.
+  @override
+  void onMount() {
+    super.onMount();
+    add(textComponent = TextComponent(position: position + Vector2(0, 27)));
+
+    // "Watch" a provider using [listen] from the [HasComponentRef] mixin.
+    // Watch is not exposed directly as this would rebuild the ancestor that
+    // exposes the [WidgetRef] unnecessarily.
+    listen(countingStreamProvider, (p0, p1) {
+      if (p1.hasValue) {
+        currentValue = p1.value!;
+        textComponent.text = '$currentValue';
+      }
+    });
+  }
+}

packages/flame_riverpod/example/pubspec.yaml

@@ -0,0 +1,20 @@
+name: flame_riverpod_example
+description: Showcasing the flame_riverpod functionality.
+publish_to: 'none' # Remove this line if you wish to publish to pub.dev
+version: 1.0.0+1
+environment:
+  sdk: '>=2.18.5 <3.0.0'
+dependencies:
+  flame: ^1.6.0
+  flame_riverpod: ^4.0.0+2
+  flutter:
+    sdk: flutter
+  flutter_riverpod: ^2.1.3
+
+dev_dependencies:
+  flame_lint: ^0.2.0
+  flutter_test:
+    sdk: flutter
+
+flutter:
+  uses-material-design: true