flame-engine · erickzanardo · Jul 22, 2026 · Jul 22, 2026
diff --git a/doc/bridge_packages/flame_spine/flame_spine.md b/doc/bridge_packages/flame_spine/flame_spine.md
@@ -18,7 +18,7 @@ Example:
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
   await initSpineFlutter();
-  runApp(const GameWidget.controlled(gameFactory: SpineExample.new));
+  runApp(const GameWidget.managed(gameFactory: SpineExample.new));
 }
 
 class FlameSpineExample extends FlameGame {

diff --git a/doc/flame/game.md b/doc/flame/game.md
@@ -84,7 +84,7 @@ will be thrown.
 If you instantiate your game in a build method your game will be rebuilt every
 time the Flutter tree gets rebuilt, which usually is more often than you'd like.
 To avoid this, you can either create an instance of your game first and
-reference it within your widget structure or use the `GameWidget.controlled`
+reference it within your widget structure or use the `GameWidget.managed`
 constructor.
 ```
 

diff --git a/doc/tutorials/platformer/app/lib/main.dart b/doc/tutorials/platformer/app/lib/main.dart
@@ -7,7 +7,7 @@ import 'overlays/main_menu.dart';
 
 void main() {
   runApp(
-    GameWidget<EmberQuestGame>.controlled(
+    GameWidget<EmberQuestGame>.managed(
       gameFactory: EmberQuestGame.new,
       overlayBuilderMap: {
         'MainMenu': (_, game) => MainMenu(game: game),

diff --git a/doc/tutorials/platformer/step_2.md b/doc/tutorials/platformer/step_2.md
@@ -79,7 +79,7 @@ import 'ember_quest.dart';
 
 void main() {
   runApp(
-    const GameWidget<EmberQuestGame>.controlled(
+    const GameWidget<EmberQuestGame>.managed(
       gameFactory: EmberQuestGame.new,
     ),
   );

diff --git a/doc/tutorials/platformer/step_7.md b/doc/tutorials/platformer/step_7.md
@@ -228,7 +228,7 @@ To display the menus, add the following code to `lib/main.dart`:
 ```dart
 void main() {
   runApp(
-    GameWidget<EmberQuestGame>.controlled(
+    GameWidget<EmberQuestGame>.managed(
       gameFactory: EmberQuestGame.new,
       overlayBuilderMap: {
         'MainMenu': (_, game) => MainMenu(game: game),

diff --git a/examples/lib/stories/camera_and_viewport/camera_and_viewport.dart b/examples/lib/stories/camera_and_viewport/camera_and_viewport.dart
@@ -40,7 +40,7 @@ void addCameraAndViewportStories(Dashbook dashbook) {
     ..add(
       'Fixed Resolution viewport',
       (context) {
-        return const GameWidget.controlled(
+        return const GameWidget.managed(
           gameFactory: FixedResolutionExample.new,
         );
       },

diff --git a/examples/lib/stories/components/components.dart b/examples/lib/stories/components/components.dart
@@ -45,7 +45,7 @@ void addComponentsStories(Dashbook dashbook) {
     )
     ..add(
       'Component Pool',
-      (_) => const GameWidget.controlled(
+      (_) => const GameWidget.managed(
         gameFactory: ComponentPoolExample.new,
       ),
       codeLink: baseLink('components/component_pool_example.dart'),
@@ -79,15 +79,15 @@ void addComponentsStories(Dashbook dashbook) {
     )
     ..add(
       'Spawn Component',
-      (_) => const GameWidget.controlled(
+      (_) => const GameWidget.managed(
         gameFactory: SpawnComponentExample.new,
       ),
       codeLink: baseLink('components/spawn_component_example.dart'),
       info: SpawnComponentExample.description,
     )
     ..add(
       'Time Scale',
-      (_) => const GameWidget.controlled(
+      (_) => const GameWidget.managed(
         gameFactory: TimeScaleExample.new,
       ),
       codeLink: baseLink('components/time_scale_example.dart'),

diff --git a/packages/flame/lib/src/game/game_widget/game_widget.dart b/packages/flame/lib/src/game/game_widget/game_widget.dart
@@ -76,14 +76,14 @@ class GameWidget<T extends Game> extends StatefulWidget {
   ///   Widget build(BuildContext context) {
   ///     return Container(
   ///       padding: EdgeInsets.all(20),
-  ///       child: GameWidget.controlled(
+  ///       child: GameWidget.managed(
   ///         gameFactory: MyGame.new,
   ///       ),
   ///     );
   ///   }
   /// }
   /// ```
-  const GameWidget.controlled({
+  const GameWidget.managed({
     required GameFactory<T> this.gameFactory,
     this.textDirection,
     this.loadingBuilder,
@@ -100,7 +100,7 @@ class GameWidget<T extends Game> extends StatefulWidget {
   }) : game = null;
 
   /// The game instance which this widget will render, if it was provided with
-  /// the default constructor. Otherwise, if the [GameWidget.controlled]
+  /// the default constructor. Otherwise, if the [GameWidget.managed]
   /// constructor was used, this will always be `null`.
   final T? game;
 

diff --git a/packages/flame/test/game/game_widget/game_widget_keyboard_test.dart b/packages/flame/test/game/game_widget/game_widget_keyboard_test.dart
@@ -141,15 +141,15 @@ void main() {
     );
   });
 
-  group('GameWidget.controlled', () {
+  group('GameWidget.managed', () {
     testWidgets('adds focus', (tester) async {
       final focusNode = FocusNode();
 
       final game = _KeyboardEventsGame();
 
       await tester.pumpWidget(
         _GamePage(
-          child: GameWidget.controlled(
+          child: GameWidget.managed(
             gameFactory: () => game,
             focusNode: focusNode,
           ),
@@ -164,7 +164,7 @@ void main() {
 
       await tester.pumpWidget(
         _GamePage(
-          child: GameWidget.controlled(
+          child: GameWidget.managed(
             gameFactory: () => game,
           ),
         ),
@@ -184,7 +184,7 @@ void main() {
 
         await tester.pumpWidget(
           _GamePage(
-            child: GameWidget.controlled(
+            child: GameWidget.managed(
               gameFactory: () => game,
             ),
           ),

diff --git a/...ame_widget_controlled_lifecycle_test.dart → ...t/game_widget_managed_lifecycle_test.dart b/...ame_widget_controlled_lifecycle_test.dart → ...t/game_widget_managed_lifecycle_test.dart
@@ -57,7 +57,7 @@ class _GamePage extends StatelessWidget {
       body: Stack(
         children: [
           Positioned.fill(
-            child: GameWidget.controlled(
+            child: GameWidget.managed(
               gameFactory: () => _MyGame(events),
             ),
           ),

diff --git a/packages/flame/test/game/game_widget/game_widget_test.dart b/packages/flame/test/game/game_widget/game_widget_test.dart
@@ -129,7 +129,7 @@ void main() {
   );
 
   group('Subscription is valid after game change', () {
-    testWidgets('Uncontrolled to uncontrolled', (tester) async {
+    testWidgets('Unmanaged to unmanaged', (tester) async {
       const key = Key('flame-game');
       final game1 = FlameGame();
       await tester.pumpWidget(GameWidget(key: key, game: game1));
@@ -147,7 +147,7 @@ void main() {
       expect(game1.gameStateListeners.length, 0);
     });
 
-    testWidgets('Uncontrolled to controlled', (tester) async {
+    testWidgets('Unmanaged to managed', (tester) async {
       const key = Key('flame-game');
       final game1 = FlameGame();
       await tester.pumpWidget(GameWidget(key: key, game: game1));
@@ -156,7 +156,7 @@ void main() {
 
       late final FlameGame game2;
       await tester.pumpWidget(
-        GameWidget.controlled(
+        GameWidget.managed(
           key: key,
           gameFactory: () => game2 = FlameGame(),
         ),
@@ -176,12 +176,12 @@ void main() {
       expect(game2.isMounted, true);
     });
 
-    testWidgets('Controlled to uncontrolled', (tester) async {
+    testWidgets('Managed to unmanaged', (tester) async {
       const key = Key('flame-game');
 
       late final FlameGame game1;
       await tester.pumpWidget(
-        GameWidget.controlled(
+        GameWidget.managed(
           key: key,
           gameFactory: () => game1 = FlameGame(),
         ),
@@ -207,12 +207,12 @@ void main() {
       expect(game2.isMounted, true);
     });
 
-    testWidgets('Controlled to controlled', (tester) async {
+    testWidgets('Managed to managed', (tester) async {
       const key = Key('flame-game');
 
       late FlameGame game1;
       await tester.pumpWidget(
-        GameWidget.controlled(
+        GameWidget.managed(
           key: key,
           gameFactory: () => game1 = FlameGame(),
         ),
@@ -223,7 +223,7 @@ void main() {
 
       FlameGame? game2;
       await tester.pumpWidget(
-        GameWidget.controlled(
+        GameWidget.managed(
           key: key,
           gameFactory: () => game2 = FlameGame(),
         ),

diff --git a/packages/flame_3d/example/lib/main.dart b/packages/flame_3d/example/lib/main.dart
@@ -10,7 +10,7 @@ Future<void> main() async {
   await GpuBackend.initialize(); // Optional but some backends might require it.
 
   runApp(
-    GameWidget.controlled(
+    GameWidget.managed(
       gameFactory: ExampleGame3D.new,
       overlayBuilderMap: {
         'console': (BuildContext context, ExampleGame3D game) {

diff --git a/packages/flame_behavior_tree/example/lib/main.dart b/packages/flame_behavior_tree/example/lib/main.dart
@@ -25,7 +25,7 @@ class MainApp extends StatelessWidget {
   Widget build(BuildContext context) {
     return MaterialApp(
       home: Scaffold(
-        body: GameWidget<MyGame>.controlled(
+        body: GameWidget<MyGame>.managed(
           gameFactory: () => MyGame(
             world: GameWorld(),
             camera: CameraComponent.withFixedResolution(

diff --git a/packages/flame_forge2d/example/lib/main.dart b/packages/flame_forge2d/example/lib/main.dart
@@ -6,7 +6,7 @@ import 'package:flame_forge2d/flame_forge2d.dart';
 import 'package:flutter/widgets.dart';
 
 void main() {
-  runApp(const GameWidget.controlled(gameFactory: Forge2DExample.new));
+  runApp(const GameWidget.managed(gameFactory: Forge2DExample.new));
 }
 
 class Forge2DExample extends Forge2DGame {

diff --git a/packages/flame_kenney_xml/example/lib/main.dart b/packages/flame_kenney_xml/example/lib/main.dart
@@ -11,7 +11,7 @@ import 'package:flutter/material.dart';
 /// sprite sheet to the screen when tapped.
 void main() {
   runApp(
-    GameWidget.controlled(
+    GameWidget.managed(
       gameFactory: () => FlameGame(world: KenneyWorld()),
     ),
   );

diff --git a/packages/flame_network_assets/example/lib/main.dart b/packages/flame_network_assets/example/lib/main.dart
@@ -8,7 +8,7 @@ import 'package:flame_network_assets/flame_network_assets.dart';
 import 'package:flutter/material.dart' hide Image;
 
 void main() {
-  runApp(const GameWidget.controlled(gameFactory: MyGame.new));
+  runApp(const GameWidget.managed(gameFactory: MyGame.new));
 }
 
 class MyGame extends FlameGame with TapCallbacks {

diff --git a/packages/flame_rive/example/lib/main.dart b/packages/flame_rive/example/lib/main.dart
@@ -8,7 +8,7 @@ import 'package:flutter/material.dart';
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
   await RiveNative.init();
-  runApp(const GameWidget.controlled(gameFactory: RiveExampleGame.new));
+  runApp(const GameWidget.managed(gameFactory: RiveExampleGame.new));
 }
 
 class RiveExampleGame extends FlameGame {

diff --git a/packages/flame_spine/example/lib/main.dart b/packages/flame_spine/example/lib/main.dart
@@ -7,7 +7,7 @@ import 'package:flutter/material.dart';
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
   await initSpineFlutter();
-  runApp(const GameWidget.controlled(gameFactory: SpineExample.new));
+  runApp(const GameWidget.managed(gameFactory: SpineExample.new));
 }
 
 class SpineExample extends FlameGame with TapCallbacks {

diff --git a/packages/flame_sprite_fusion/example/lib/main.dart b/packages/flame_sprite_fusion/example/lib/main.dart
@@ -15,7 +15,7 @@ class MyApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return MaterialApp(
-      home: GameWidget.controlled(
+      home: GameWidget.managed(
         gameFactory: () => PlatformerGame(
           camera: CameraComponent.withFixedResolution(width: 320, height: 180),
         ),

diff --git a/packages/flame_typled/example/lib/main.dart b/packages/flame_typled/example/lib/main.dart
@@ -15,7 +15,7 @@ class MyApp extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return const MaterialApp(
-      home: GameWidget.controlled(
+      home: GameWidget.managed(
         gameFactory: TypledExample.new,
       ),
     );