feat: Allow people to opt-out on repaint boundary

packages/flame/lib/src/game/game_render_box.dart

@@ -9,27 +9,34 @@ import 'package:flutter/widgets.dart' hide WidgetBuilder;
 /// render the game.
 class RenderGameWidget extends LeafRenderObjectWidget {
   final Game game;
+  final bool addRepaintBoundary;
 
   const RenderGameWidget({
     super.key,
     required this.game,
+    required this.addRepaintBoundary,
   });
 
   @override
   RenderBox createRenderObject(BuildContext context) {
-    return GameRenderBox(game, context);
+    return GameRenderBox(game, context, addRepaintBoundary);
   }
 
   @override
   void updateRenderObject(BuildContext context, GameRenderBox renderObject) {
     renderObject
       ..game = game
-      ..buildContext = context;
+      ..buildContext = context
+      ..isRepaintBoundary = addRepaintBoundary;
   }
 }
 
 class GameRenderBox extends RenderBox with WidgetsBindingObserver {
-  GameRenderBox(this._game, this.buildContext);
+  GameRenderBox(
+    this._game,
+    this.buildContext,
+    this._isRepaintBoundary,
+  );
 
   GameLoop? gameLoop;
 
@@ -56,8 +63,18 @@ class GameRenderBox extends RenderBox with WidgetsBindingObserver {
     }
   }
 
+  bool _isRepaintBoundary = false;
+
+  set isRepaintBoundary(bool value) {
+    if (_isRepaintBoundary == value) {
+      return;
+    }
+    _isRepaintBoundary = value;
+    markNeedsCompositingBitsUpdate();
+  }
+
   @override
-  bool get isRepaintBoundary => true;
+  bool get isRepaintBoundary => _isRepaintBoundary;
 
   @override
   bool get sizedByParent => true;

packages/flame/lib/src/game/game_widget/game_widget.dart

@@ -71,6 +71,11 @@ class GameWidget<T extends Game> extends StatefulWidget {
   final MouseCursor? mouseCursor;
   final List<String>? initialActiveOverlays;
 
+  /// Whether the game should assume the behavior of a [RepaintBoundary].
+  ///
+  /// Defaults to `true`.
+  final bool addRepaintBoundary;
+
   /// Renders a [game] in a flutter widget tree.
   ///
   /// Ex:
@@ -129,6 +134,7 @@ class GameWidget<T extends Game> extends StatefulWidget {
     this.focusNode,
     this.autofocus = true,
     this.mouseCursor,
+    this.addRepaintBoundary = true,
   }) : gameFactory = null {
     _initializeGame(game!);
   }
@@ -165,6 +171,7 @@ class GameWidget<T extends Game> extends StatefulWidget {
     this.focusNode,
     this.autofocus = true,
     this.mouseCursor,
+    this.addRepaintBoundary = true,
   }) : game = null;
 
   /// Renders a [game] in a flutter widget tree alongside widgets overlays.
@@ -314,6 +321,7 @@ class _GameWidgetState<T extends Game> extends State<GameWidget<T>> {
     return _protectedBuild(() {
       Widget? internalGameWidget = RenderGameWidget(
         game: currentGame,
+        addRepaintBoundary: widget.addRepaintBoundary,
       );
 
       assert(

packages/flame/test/game/flame_game_test.dart

@@ -101,7 +101,7 @@ void main() {
           await tester.pumpWidget(
             Builder(
               builder: (BuildContext context) {
-                renderBox = GameRenderBox(game, context);
+                renderBox = GameRenderBox(game, context, true);
                 return GameWidget(game: game);
               },
             ),

packages/flame/test/game/game_render_box_test.dart

@@ -0,0 +1,72 @@
+import 'package:flame/game.dart';
+import 'package:flame/src/game/game_render_box.dart';
+import 'package:flutter/rendering.dart';
+import 'package:flutter/widgets.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:mocktail/mocktail.dart';
+
+class _MockFlameGame extends Mock implements FlameGame {}
+
+class _MockBuildContext extends Mock implements BuildContext {}
+
+class _MockPipelineOwner extends Mock implements PipelineOwner {}
+
+final nodesNeedingCompositingBitsUpdate = <RenderObject>[];
+
+void main() {
+  TestWidgetsFlutterBinding.ensureInitialized();
+
+  setUp(nodesNeedingCompositingBitsUpdate.clear);
+
+  group('GameRenderBox', () {
+    test('game/attach', () {
+      final owner = _MockPipelineOwner();
+      final game = _MockFlameGame();
+      when(() => game.paused).thenReturn(true);
+
+      final BuildContext context = _MockBuildContext();
+      final renderBox = GameRenderBox(game, context, false);
+      renderBox.attach(owner);
+
+      verify(() => game.attach(owner, renderBox)).called(1);
+      expect(renderBox.gameLoop, isNotNull);
+      verify(() => game.paused).called(1);
+
+      final anotherGame = _MockFlameGame();
+      when(() => anotherGame.paused).thenReturn(true);
+
+      renderBox.game = anotherGame;
+      verify(game.detach).called(1);
+      verify(() => anotherGame.attach(owner, renderBox)).called(1);
+      verify(() => anotherGame.paused).called(1);
+      expect(renderBox.gameLoop, isNotNull);
+    });
+    test('buildContext', () {
+      final owner = _MockPipelineOwner();
+      final game = _MockFlameGame();
+      when(() => game.paused).thenReturn(true);
+
+      final BuildContext context = _MockBuildContext();
+      final renderBox = GameRenderBox(game, context, false);
+      renderBox.attach(owner);
+
+      expect(renderBox.buildContext, context);
+    });
+    test('isRepaintBoundary', () {
+      final owner = PipelineOwner();
+
+      final game = _MockFlameGame();
+      when(() => game.paused).thenReturn(true);
+
+      final BuildContext context = _MockBuildContext();
+      final renderBox = GameRenderBox(game, context, false);
+      renderBox.attach(owner);
+
+      expect(renderBox.isRepaintBoundary, false);
+
+      renderBox.isRepaintBoundary = true;
+
+      expect(renderBox.isRepaintBoundary, true);
+    });
+  });
+}