Migrating from `flutter_unity_widget`

Game Framework is the next-generation successor to flutter_unity_widget, rebuilt from the ground up by the same author. It keeps the core idea — a Unity scene embedded in a Flutter widget — and adds a real CLI, Unreal support, cloud publishing, and lifecycle/messaging that hold up in production.

This guide maps every flutter_unity_widget concept to its Game Framework equivalent.

What changes at a glance

`flutter_unity_widget`	Game Framework
`flutter_unity_widget` (one package)	`gameframework` + `gameframework_unity`
`UnityWidget(...)`	`GameWidget(engineType: GameEngineType.unity, ...)`
`UnityWidgetController`	`GameEngineController`
`onUnityCreated: (c) {}`	`onEngineCreated: (c) {}`
`onUnityMessage: (msg) {}` (raw value)	`onMessage: (msg) {}` → use `msg.data` / `msg.method`
`onUnitySceneLoaded: (info) {}`	scene events arrive via `onMessage`
`controller.postMessage(o, m, d)`	`await controller.sendMessage(o, m, d)`
`controller.postJsonMessage(o, m, map)`	`await controller.sendJsonMessage(o, m, map)`
`controller.pause()` / `resume()` / `quit()`	same names, now `Future` (await them)
manual Unity export + copying `unityLibrary` / `UnityFramework`	`game export` + `game sync` (CLI)

Swap the dependency

Remove flutter_unity_widget and add the Game Framework packages:

pubspec.yaml

dependencies:
  # - flutter_unity_widget: ^x.y.z   # remove
  gameframework: ^0.0.3
  gameframework_unity: ^0.0.4

flutter pub get

Initialize the plugin

Call the Unity plugin initializer once in main() (there was no explicit init in flutter_unity_widget):

import 'package:gameframework_unity/gameframework_unity.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  UnityEnginePlugin.initialize();
  runApp(const MyApp());
}

Replace `UnityWidget` with `GameWidget`

Before:

import 'package:flutter_unity_widget/flutter_unity_widget.dart';

UnityWidget(
  onUnityCreated: (controller) => _controller = controller,
  onUnityMessage: (message) => print('From Unity: $message'),
)

After:

import 'package:gameframework/gameframework.dart';
import 'package:gameframework_unity/gameframework_unity.dart';

GameWidget(
  engineType: GameEngineType.unity,
  onEngineCreated: (controller) => _controller = controller,
  onMessage: (message) => print('From Unity: ${message.data}'),
)

onUnityMessage handed you the raw payload; onMessage gives you a message object — read message.data (the payload) and message.method (which handler fired). Update any code that treated the callback argument as a plain string.

Update the controller & messaging

The controller type changes from UnityWidgetController to GameEngineController, and the send methods are now async:

// Before
_controller.postMessage('GameManager', 'RotateCube', '360');
_controller.postJsonMessage('Player', 'TakeDamage', {'amount': 10});
_controller.pause();
_controller.resume();
_controller.quit();

// After
await _controller.sendMessage('GameManager', 'RotateCube', '360');
await _controller.sendJsonMessage('Player', 'TakeDamage', {'amount': 10});
await _controller.pause();
await _controller.resume();
await _controller.quit();

Game Framework also adds sendBinaryMessage(...) and state helpers like isReady(), isPaused(), and isLoaded(). See the Messaging API and Lifecycle API.

Replace manual Unity setup with the CLI

This is the biggest quality-of-life change. Instead of exporting Unity by hand and copying unityLibrary / UnityFramework into android/ and ios/, Game Framework's CLI does it:

# export the Unity build for your platforms
game export unity --platform android,ios

# sync the build into your Flutter project
game sync unity --platform android,ios

See Installation for CLI setup and the Quick Start for the full flow.

After migrating

Run it the same way you always have:

flutter run

New to the CLI or Unity-version handling? The Quick Start covers prerequisites (Unity Build Support modules, the Xcode iOS platform, matching your project's Unity version), and Troubleshooting lists the common first-run issues.

Questions or a mapping we missed? Open an issue on GitHub.

On this page