XRAPH/Work/Engine embedding
Dart · since 2019

Flutter Unity Widget

A Flutter widget that hosts a Unity player and passes messages both ways. It started as a weekend attempt to put a 3D configurator inside a Flutter app and became the package most people use for that. Six years and several thousand issues later, GameFramework is the rewrite.

Language
Dart
Category
Engine embedding
Since
2019
Stars
2,305
In production
03+
Repository Docs
02

Anatomy

4 modules
01

View

Platform view embedding the Unity player surface in the Flutter tree.

02

Bridge

Bidirectional Dart ↔ engine messaging with typed payloads.

03

Lifecycle

Pause, resume and dispose tied to the widget, not the app.

04

Build hooks

Gradle and Xcode export steps kept out of the host project.

03

Why it exists

Design notes

#What it is

An embeddable Unity view for Flutter, with messaging in both directions between Dart and the engine. Published in March 2019, and for most of the six years since, the default answer to putting 3D content inside a Flutter app.

#How it started

I wanted a 3D product configurator inside a Flutter app. Unity could render it; Flutter could not host Unity. A weekend of gluing a Unity player into a platform view with a message channel produced something that worked, and I published it because there was no reason not to.

I did not intend to maintain a package. I intended to solve one screen.

#What maintaining it was actually like

Roughly 60% of issues were build configuration on someone else's machine. Perhaps 20% were real bugs, concentrated heavily in lifecycle: what happens when the app backgrounds, when the widget is disposed, when Flutter hot-reloads underneath a running engine. Around 15% were requests for platforms or engine versions I had no way to test.

Every Unity release, every Flutter release and every Gradle release could generate a week of work, and none of them were coordinated with each other or with me.

The single highest-leverage change in six years was requiring a minimal reproduction with exact versions. It closed roughly half the incoming issues before I read them, mostly because assembling a reproduction is how people find their own misconfiguration.

#What it was used for

The part that made six years of maintenance worth it was seeing where it ended up.

Wallace and Gromit: The Big Fix Up. Fictioneers, a joint venture including Aardman, built a large scale location-based augmented reality production on it. It went on to win industry awards for its craft and remains the most visible thing built on the package. Unity content rendered inside a Flutter application, in the hands of the public, on hardware nobody controlled.

Genopets. A mobile game with substantial Unity content running inside a Flutter application, shipped at consumer scale.

Beyond those, product configurators, training simulators and museum installations. Real products with real users, built by teams who did not have to spend a weekend on platform views. That return does not appear in a star count.

The Big Fix Up · Genopets

#Further reading

I wrote up the augmented reality toolkit built on this package for Potato, covering project structure, the build configuration on both platforms, and the parts of the Unity export that need attention: Building with Flutter Unity: AR Experience Toolkit.

#What replaced it

GameFramework, with the accretion dropped: the engine is a plugin rather than a hard dependency, messaging is typed instead of stringly, and lifecycle handling lives in the core rather than being something each integrator rediscovers. Game CLI handles the build configuration that generated most of the original's issue volume.

04

Signals

GitHub
Stars
2,305
Language
Dart
Since
2019
Adopters
03