flutter_unity_widget: embedding a Unity player inside a Flutter app

Embedding a Unity player inside a Flutter widget tree

The package wraps a Unity player build in a platform view, so the rendered 3D scene sits inside the ordinary widget hierarchy of a Flutter app and can be laid out, scrolled and stacked like any other view. The README describes the result as gamified features built in Unity and rendered in Flutter, in both fullscreen and embeddable mode, across Android, iOS, iPadOS and Web. GitHub reports the project as Dart with 2,307 stars, 593 forks and 272 open issues, which is an unusual amount of fork traffic for a plugin and tells you how many people copied it into their own tree.

Installation is a normal pub dependency with a version that tracks Unity releases rather than Flutter's semver:

dependencies:
  flutter_unity_widget: ^2022.2.1 # use the latest compatible version

The import is the obvious one:

import 'package:flutter_unity_widget/flutter_unity_widget.dart';

One detail in the README is worth repeating because it saves an afternoon: the plugin requires Flutter 3.16.0 or newer, and you cannot run the example without a Unity project that has already been exported into your Flutter project. An app that includes the widget but no exported Unity build fails at build time, not at runtime.

The manual Unity export step sits between you and a working build

There is no build magic here. The documented flow puts your Unity project inside a folder named `unity` in the Flutter project, imports a prebuilt unitypackage from the repository's `unitypackages/` directory, and then runs a Unity export that rewrites parts of the Flutter project's `/android` and `/ios` folders. The README is explicit that the expected path is `<flutter-project>/unity/__project-name__/...` and that a Unity project living somewhere else can fail the export partially.

That is the architectural trade-off in one sentence. The plugin is not a federated plugin that builds a Unity player on demand; it is a bridge that expects a Unity export to have already happened, with a specific directory layout and specific Player Settings. Inside those settings the README asks you to switch the Scripting Backend to IL2CPP, select ARMv7 and ARM64 on Android, and set Active Input Handling to `Input Manager (Old)` or `Both`, because the new input system has touch problems on Android in this arrangement.

The repository tree matches the story: top level `android/`, `ios/`, `windows/`, `lib/`, `test/`, `example/` and `unitypackages/`, plus a `files/` directory holding the preview GIFs. There is no `tool/` or `scripts/` directory, so nothing in the repo runs the export for you.

Unity version floors for iOS and Android publishing

The stated support range is Unity 2019.4.3 through 2022.3.x, with 2022.3 LTS recommended. Unity 6 is handled by a linked GitHub issue rather than by the support statement, which is a distinction worth keeping in mind: the range in the README is what the plugin claims, and issue 967 is where Unity 6 support is actually tracked.

The publishing requirements are stricter and they come from Apple and Google, not from the plugin author. Apple's privacy manifest rules need Unity 2021.3.35+, 2022.3.18+ or 6000.0.0+. Google's 16 KB page size requirement for apps targeting Android 15 and submitted from November 1, 2025 needs Unity 2021.3.48+ (Enterprise and Industry only), 2022.3.56+ or 6000.0.38+.

Read those two lists together and a real conflict appears. The support range tops out at 2022.3.x, yet the publishing floors require 6000.0.x for current store submissions, which is Unity 6. So a project that must ship to the App Store or Play today needs a Unity version the README does not claim to support, and the 272 open issues are where you would find out whether that combination works in practice. The README also asks you to use only OpenGLES3 as the Android graphics API for AR compatibility, which narrows your options further.

Platform limits the README states without softening

The notes section is unusually candid about what does not work. Export and build need Windows or macOS, and Ubuntu users are reported to hit a lot of errors in the Unity export. Emulator support is limited and needs special setup, so the advice is to develop on a physical device for Android and iOS. Windows desktop is not supported at all, because Flutter's PlatformView support is missing on that target; the README links the Flutter issue rather than pretending it is on the roadmap.

Those limits combine into a fairly specific profile: a mobile-first plugin for teams with a Mac or Windows workstation, real devices in hand, and a Unity scene that genuinely needs to live inside a Flutter app. A team shipping desktop or Linux tooling gets nothing here.

The messaging story is the other half of the value proposition. The README's preview section shows 30 fps captures of communication between Flutter and Unity, and the repository description points at an ARKit demo as the more advanced example. With 593 forks, the common pattern in the wild is that people need the Flutter-to-Unity and Unity-to-Flutter channel and have taken a copy of the plugin rather than fighting the export step.

Releases that were tagged after the fact

The release history needs a sentence of context. The v2022.2.1 and v2022.2.0 tags both carry the note that the tag was made retroactively to clean up the repository. The v2022.2.1 body records that the package went out on pub.dev on January 8, 2024, while the GitHub release itself is dated February 18, 2024. So the tag dates are not release dates, and anyone building a changelog from tags will get it wrong.

What the v2022.2.1 notes actually contain is a list of platform fixes: Unity lifecycle events not reaching iOS, a white background on Android being removed so Unity transparency works as it does on iOS, a webview package swap that moved `webview_flutter` from 2.x to 4.x, and web support for a base path that is not the site root. That is a web-and-mobile maintenance log, not a feature release.

The older v4.0.0 tag is more informative about the codebase. It records a migration from Objective-C to Swift on iOS and from Java to Kotlin on Android, an iOS unload crash fixed by requiring Unity 2019.4.3 or later, and a fix for Flutter channel ID mismatches. Those two channel ID fixes, one on each platform, in the same release, are a good summary of what makes native view embedding hard.

Superseded by Game Framework, with two facts that disagree

The first thing the README says is that this package has evolved into Game Framework, rebuilt from the ground up by the same author, with a CLI for export and sync, Unity and Unreal Engine support, cloud publishing, and bidirectional messaging maintained against current Flutter and Unity 6. New projects are pointed at gameframework.dev, and the README states plainly that flutter_unity_widget remains available but is no longer the recommended starting point.

The repository itself does not read like a parked project. GitHub reports it as not archived, with the last push on 2026-07-21, and the topics still include `flutter-package`, `flutter-plugin`, `unity` and `unityframework`. The successor announcement and the active repository are both true at once, and the practical reading is that maintenance continues for existing installs while new attention goes elsewhere.

The second disagreement is about licensing. GitHub reports the license as BSD-3-Clause. The README carries an MIT License badge. The repository tree has a top level `LICENSE` file, so the authoritative answer is the file itself, and it is worth opening before you copy this into a commercial app. Treat the badge and the metadata field as two claims to check rather than one settled fact.

For evaluation purposes, the fork count and issue count are the most useful numbers here. This is a package that many teams adopted and then carried, and the accumulated issues are effectively the operational documentation that the README does not provide.

Editorial conclusion

flutter_unity_widget still does the thing its name implies, and for an app that already has a Unity project and a Flutter shell it is a shorter path than writing your own platform view. What it is not is a good place to start today. The README points new projects at Game Framework, the README badge and the GitHub license field disagree about licensing, and every setup step is a manual export rather than a build hook. If you are maintaining an existing integration, read the version notes and the 272 open issues first. If you are starting one, spend your time on Game Framework instead.

Frequently asked questions

Official sources

1. Issues
2. juicycleff/flutter-unity-view-widget on GitHub
3. License: BSD-3-Clause
4. README
5. Releases