Repository files navigation

Flutter unity 3D widget for embedding unity in flutter. Now you can make awesome gamified features of your app in Unity and get it rendered in a Flutter app both in fullscreen and embeddable mode. Works great onAndroid, iPad OS, iOS, Web.

• Use Windows or Mac to export and build your project.
  Users on Ubuntu have reported a lot of errors in the Unity export.
• Emulator support is limited and requires special setup. Please use a physical device for Android and iOS.
• Supports Unity 2019.4.3 up to 2022.3.x, we recommend the latest 2022.3 LTS.
  Checkthis github issue for support of Unity 6.
• Use only OpenGLES3 as Graphics API on Android for AR compatibility.
• Windows isn't supported because of the lack ofFlutter PlatformView support.

Need me to respond, tag meRex Isaac Raphael.

This plugin expects you to atleast know how to use Unity Engine. If you have issues with how unity widget is presented, you can please modify your unity project build settings as you seem fit.

Moving forward, versioning of the package will change to match unity releases after proper test. Mind you this does not mean the packageis not compatible with other versions, it just mean it's been tested to work with a unity version.

This plugin requires Flutter >= 3.16.0.

First depend on the library by adding this to your packagespubspec.yaml:

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

Now inside your Dart code you can import it.

import'package:flutter_unity_widget/flutter_unity_widget.dart';

You will need to open and export a Unity project, even for running the example. Your build will fail if you only include the widget in Flutter!

30 fps gifs, showcasing communication between Flutter and Unity:

In the tutorial below, there are steps specific to each platform, denoted by a ℹ️ icon followed bythe platform name (Android or iOS). You can click on its icon to expand it.

• An existing Flutter project (if there is none, you cancreate a new one)

• An existing Unity project (if there is none, you cancreate a new one).

• Afuw-XXXX.unitypackage file, found in theunitypackages folder.Try to use the most recent unitypackage available.

If you want to publish your app for Android or iOS, you need to satisfy certain Unity version requirements.

iOS
Apple'sprivacy manifest requirements need a minimal Unity version of:

• 2021.3.35+
• 2022.3.18+
• 6000.0.0+

Android

Starting November 1st, 2025, all new apps and updates to existing apps submitted to Google Play and targeting Android 15+ devices must support 16 KB page sizes.

This requiresUnity versions:

• 2021.3.48+ (Enterprise and Industry only)
• 2022.3.56+
• 6000.0.38+

These instructions assume you are using a new Unity project. If you open the example project from this repository, you can move on to the next sectionUnity Exporting.

1. Create a folder namedunity in your Flutter project folder and move the Unity project into there.
   The Unity export will modify some files in the/android and/ios folders of your flutter project. If your Unity project is in a different location the export might (partially) fail.

The expected path is/unity/project-name/...

2. Make sure you have downloaded afuw-XXXX.unitypackage file mentioned inprerequisites.

3. Using Unity (hub), open the Unity project.Go toAssets > Import Package > Custom Package and select the downloadedfuw-XXXX.unitypackage file. Click onImport.

4. Go toFile > Build Settings > Player Settingsand change the following under theOther settings > Configuration section:

• InScripting Backend, change to IL2CPP

• (Android)Target Architectures, select ARMv7 and ARM64

• (Android) For the best compatibility setActive Input Handling toInput Manager (Old) orBoth.
  (The new input system has some issues with touch input on Android)

• (iOS) SelectTarget SDK depending on where you will run your app (simulator or physical device).
  We recommend starting with a physical device and theDevice SDK setting, due to limited simulator support.

• (Web) SetPublishing settings > Compression format to Brotli or Disabled.
  Some users report that Unity gets stuck on the loading screen with the Gzip setting, due to MIME type errors.

5. InFile > Build Settings, make sure to have at least 1 scene added to your build.

Some options in theBuild settings window get overridden by the plugin's export script.Attempting to change settings likeDevelopment Build,Script Debugging andExport project in this window will not make a difference.If you end up having to change a build setting that doesn't seem to respond, take a lookat the export scriptFlutterUnityIntegration\Editor\Build.cs.

1. After importing the unitypackage, you should now see aFlutter option at the top of the Unity editor.

2. Click onFlutter and select the appropriate export option:

• For android useExport Android Debug orExport Android Release.
  This will export toandroid/unityLibrary.
• For iOS useExport iOS Debug orExport iOS Release.
  This will export toios/UnityLibrary.
• Do not useFlutter > ExportPlatform plugin as it was specially added to work withflutter_unity_cli for larger projects.

If you use git, you will probably want to add these unityLibrary folders to your gitignore file.These folders can get huge and are not guaranteed to work on another computer.

Proceed to the next section to handle iOS and Android specific setup after the export.

After exporting Unity, you will need to make some small changes in your iOS or Android project.
You will likely need to do thisonly once. These changes remain on future Unity exports.

    // macndk.dir=/Applications/Unity/Hub/Editor/2020.3.19f1/PlaybackEngines/AndroidPlayer/NDK    // windowsndk.dir=C:\\Program Files\\Unity\\Hub\\Editor\\2021.3.13f1\\Editor\\Data\\PlaybackEngines\\AndroidPlayer\\NDK

android {  ndkVersion"21.3.6528147"}

     dependencies {         // build.gradle+        implementation project(':flutter_unity_widget')         // build.gradle.kts (Flutter 3.29+)+        implementation(project(":flutter_unity_widget"))     }

// MainActivity.kt+ import com.xraph.plugin.flutter_unity_widget.FlutterUnityActivity;+ class MainActivity: FlutterUnityActivity() {- class MainActivity: FlutterActivity() {

// MainActivity.kt// only do this if your activity does not inherit FlutterActivityimportcom.xraph.plugin.flutter_unity_widget.IFlutterUnityActivity;classMainActivity:CustomActivity(), IFlutterUnityActivity {// unity will try to read this mUnityPlayer property    @JvmFieldvar mUnityPlayer: java.lang.Object?=null;// implement this function so the plugin can set mUnityPlayeroverridefunsetUnityPlayer(unityPlayer: java.lang.Object?) {        mUnityPlayer= unityPlayer;    }}

// build.gradle+    include ":unityLibrary"+    project(":unityLibrary").projectDir = file("./unityLibrary")// build.gradle.kts (Flutter 3.29+)+    include(":unityLibrary")+    project(":unityLibrary").projectDir = file("./unityLibrary")

     dependencies {          // app/build.gradle+        implementation project(':unityLibrary')         // app/build.gradle.kts (Flutter 3.29+)+        implementation(project(":unityLibrary"))     }

allprojects {    repositories {+       flatDir {            // build.gradle+           dirs "${project(':unityLibrary').projectDir}/libs"            // build.gradle.kts (Flutter 3.29+)+           dirs(file("${project(":unityLibrary").projectDir}/libs"))+       }        google()        mavenCentral()    }}

     buildTypes {         release {             signingConfig signingConfigs.debug         }+        debug {+            signingConfig signingConfigs.debug+        }+        profile {+            signingConfig signingConfigs.debug+        }+        innerTest {+            matchingFallbacks = ['debug', 'release']+        }+   }

+    -keep class com.xraph.plugin.** {*;}

+    <activity+        android:name="com.xraph.plugin.flutter_unity_widget.OverrideUnityActivity"+        android:theme="@style/UnityThemeSelector"+        android:screenOrientation="fullSensor"+        android:launchMode="singleTask"+        android:configChanges="mcc|mnc|locale|touchscreen|keyboard|keyboardHidden|navigation|orientation|screenLayout|uiMode|screenSize|smallestScreenSize|fontScale|layoutDirection|density"+        android:hardwareAccelerated="false"+        android:process=":Unity">+    <meta-data android:name="com.xraph.plugin.flutter_unity_widget.OverrideUnityActivity" android:value="true" />+    </activity>

ℹ️iOS

1. Open theios/Runner.xcworkspace (workspace, not the project) file in Xcode, right-click on the Navigator (not on an item), go toAdd Files to "Runner" and addtheios/UnityLibrary/Unity-Iphone.xcodeproj file.

2. (Optional) Select theUnity-iPhone/Data folder and change the Target Membership for Data folder to UnityFramework.

3.1. If you're using Swift, open theios/Runner/AppDelegate.swift file and change the following:

     import UIKit     import Flutter+    import flutter_unity_widget     @UIApplicationMain     @objc class AppDelegate: FlutterAppDelegate {         override func application(             _ application: UIApplication,             didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?         ) -> Bool {+            InitUnityIntegrationWithOptions(argc: CommandLine.argc, argv: CommandLine.unsafeArgv, launchOptions)             GeneratedPluginRegistrant.register(with: self)             return super.application(application, didFinishLaunchingWithOptions: launchOptions)         }     }

3.2. If you're using Objective-C, open theios/Runner/main.m file and change the following:

+    #import "flutter_unity_widget.swift.h"     int main(int argc, char * argv[]) {          @autoreleasepool {+             InitUnityIntegration(argc, argv);              return UIApplicationMain(argc, argv, nil, NSStringFromClass([AppDelegate class]));          }     }

4. Add theUnityFramework.framework file as a library to the Runner project.

5. Unity plugins that make use of native code (Vuforia, openCV, etc.) might need to be added to Runner like UnityFramework.
   Check the contents of the/ios/UnityLibrary/Frameworks/ directory. Any<name>.framework located in (subdirectories of) this directory is a framework that you can add to Runner.

6. Make sure pods are installed after your Unity export, either usingflutter run or by runningpod install in the ios folder.

7. If you use Xcode 14 or newer, and Unity older than 2021.3.17f1 or 2022.2.2f1, your app might crash when running from Xcode.
   Disable theThread Performance Checker feature in Xcode to fix this.
   - In Xcode go toProduct > Scheme > Edit Scheme...
   - Now WithRun selected on the left, got to theDiagnostics tab and uncheck the checkbox forThread Performance Checker.

---

The following setup for AR is done after making an export from Unity.

Warning: Flutter 3.22 has introduced a crash when using AR on Android < 13#957

     <dict>+        <key>NSCameraUsageDescription</key>+        <string>$(PRODUCT_NAME) uses Cameras</string>     </dict>

     <dict>+        <key>NSCameraUsageDescription</key>+        <string>$(PRODUCT_NAME) uses Cameras</string>     </dict>

We recommend using a physical iOS or Android device, as emulator support is limited.
Below are the limited options to use an emulator.

1. On aUnityWidget widget, get theUnityWidgetController received by theonUnityCreated callback.

2. Use the methodpostMessage to send a string, using the GameObject name and the name of a behaviour method that should be called.

// Snippet of postMessage usage in the example project._unityWidgetController?.postMessage('Cube',// GameObject name'SetRotationSpeed',// Function name in attached C# script  speed,// Function parameter (string));

1. Select the GameObject that should execute the communication and go toInspector > Add Component > Unity Message Manager.

2. Create a newMonoBehaviour subclass and add to the same GameObject as a script.

3. On this new behaviour, callGetComponent<UnityMessageManager>() to get aUnityMessageManager.

4. Use the methodSendMessageToFlutter to send a string. Receive this message using theonUnityMessage callback of aUnityWidget.

// Send a basic string to FlutterSendMessageToFlutter("Hello there!");

// If you want to send multiple parameters or objects, use a JSON string.// This is a random object serialized to JSON using Json.net.JObjecto=JObject.FromObject(new{id=1,name="Object 1",whatever=12});SendMessageToFlutter(o.ToString());

import'package:flutter/material.dart';import'package:flutter_unity_widget/flutter_unity_widget.dart';voidmain() {runApp(constMaterialApp(      home:UnityDemoScreen(),    ),  );}classUnityDemoScreenextendsStatefulWidget {constUnityDemoScreen({Key? key}):super(key: key);@overrideState<UnityDemoScreen>createState()=>_UnityDemoScreenState();}class_UnityDemoScreenStateextendsState<UnityDemoScreen> {UnityWidgetController? _unityWidgetController;@overrideWidgetbuild(BuildContext context) {returnScaffold(      body:Container(        color:Colors.yellow,        child:UnityWidget(          onUnityCreated: onUnityCreated,        ),      ),    );  }// Callback that connects the created controller to the unity controllervoidonUnityCreated(UnityWidgetController controller) {    _unityWidgetController= controller;  }}

import'package:flutter/material.dart';import'package:flutter_unity_widget/flutter_unity_widget.dart';voidmain() {runApp(constMaterialApp(      home:UnityDemoScreen(),    ),  );}classUnityDemoScreenextendsStatefulWidget {constUnityDemoScreen({Key? key}):super(key: key);@overrideState<UnityDemoScreen>createState()=>_UnityDemoScreenState();}class_UnityDemoScreenStateextendsState<UnityDemoScreen> {UnityWidgetController? _unityWidgetController;double _sliderValue=0.0;@overrideWidgetbuild(BuildContext context) {returnScaffold(      appBar:AppBar(        title:constText('Unity Flutter Demo'),      ),      body:Stack(        children:<Widget>[UnityWidget(            onUnityCreated: onUnityCreated,            onUnityMessage: onUnityMessage,            onUnitySceneLoaded: onUnitySceneLoaded,          ),// Flutter UI Stacked on top of Unity to demo Flutter -> Unity interactions.// On web this requires a PointerInterceptor widget.Positioned(            bottom:0,// <You need a PointerInterceptor here on web>            child:SafeArea(              child:Card(                elevation:10,                child:Column(                  children:<Widget>[constPadding(                      padding:EdgeInsets.only(top:20),                      child:Text("Rotation speed:"),                    ),Slider(                      onChanged: (value) {setState(() {                          _sliderValue= value;                        });// Send value to UnitysetRotationSpeed(value.toString());                      },                      value: _sliderValue,                      min:0.0,                      max:1.0,                    ),                  ],                ),              ),            ),          ),        ],      ),    );  }// Communcation from Flutter to UnityvoidsetRotationSpeed(String speed) {    _unityWidgetController?.postMessage('Cube','SetRotationSpeed',      speed,    );  }// Callback that connects the created controller to the unity controllervoidonUnityCreated(UnityWidgetController controller) {    _unityWidgetController= controller;  }// Communication from Unity to FluttervoidonUnityMessage(dynamic message) {print('Received message from unity: ${message.toString()}');  }// Communication from Unity when new scene is loaded to FluttervoidonUnitySceneLoaded(SceneLoaded? sceneInfo) {if (sceneInfo!=null) {print('Received scene loaded from unity: ${sceneInfo.name}');print('Received scene loaded from unity buildIndex: ${sceneInfo.buildIndex}');    }  }}

• fullscreen (Enable or disable fullscreen mode on Android)

• pause() (Use this to pause unity player)
• resume() (Use this to resume unity player)
• unload() (Use this to unload unity player) *Requires Unity 2019.4.3 or later
• quit() (Use this to quit unity player)
• postMessage(String gameObject, methodName, message) (Allows you invoke commands in Unity from flutter)
• onUnityMessage(data) (Unity to flutter binding and listener)
• onUnityUnloaded() (Unity to flutter listener when unity is unloaded)
• onUnitySceneLoaded(String name, int buildIndex, bool isLoaded, bool isValid,) (Unity to flutter binding and listener when new scene is loaded)

Location: Unity

Error:

Multiple precompiled assemblies with the same name Newtonsoft.Json.dll included on the current platform. Only one assembly with the same name is allowed per platform. (Assets/FlutterUnityIntegration/JsonDotNet/Assemblies/AOT/Newtonsoft.Json.dll)PrecompiledAssemblyException: Multiple precompiled assemblies with the same name Newtonsoft.Json.dll included on the current platform. Only one assembly with the same name is allowed per platform.

Solution:Locate the listed dll file, in this case:Assets/FlutterUnityIntegration/JsonDotNet/Assemblies/AOT/Newtonsoft.Json.dll

• Option 1:Delete the dll file or rename the file extension (e.g..dll.txt) to stop it from being imported.
• Option 2:Uninstall the package that conflicts in the Unity package manager (usually Version control, or Collab).The exact package can be found by looking for newtonsoft inpackage-lock.json

Location: Unity

Error:

The type or namespace name 'Newtonsoft' could not be found (are you missing a using directive or an assembly reference?)The type or namespace name 'JObject' could not be found (are you missing a using directive or an assembly reference?)The type or namespace name 'JToken' could not be found (are you missing a using directive or an assembly reference?)The type or namespace name 'JToken' could not be found (are you missing a using directive or an assembly reference?)

Solution:

Include the Newtonsoft JsonDotNet library.It is likely already included in your project with a wrong file extension:Assets/FlutterUnityIntegration/JsonDotNet/Assemblies/AOT/Newtonsoft.Json.dll.txtRename the.dll.txt extension to.dll in your file explorer and open Unity again.

Alternatively you can manually addthe library from the Unity package manager.

Location: Unity

Error:

InvalidOperationException: The build target does not support build appending.

Solution:

1. Open theunity/project-name/Assets/FlutterUnityIntegration/Editor/Build.cs file.

1.1. On line 48, change the following:

-    var options = BuildOptions.AcceptExternalModificationsToPlayer;+    var options = BuildOptions.AllowDebugging;+    EditorUserBuildSettings.exportAsGoogleAndroidProject = true;

1.2. On line 115, change the following:

-    var options = BuildOptions.AcceptExternalModificationsToPlayer;+    var options = BuildOptions.AllowDebugging;

Location: Android Studio

Error:

minSdkVersion XX cannot be smaller than version 19 declared in library     \ [:flutter_unity_widget] .../AndroidManifest.xml as the library might be using     \ APIs not available in XX

Solution:

1. Open theandroid/app/build.gradle file and change the following:

-    minSdkVersion XX+    minSdkVersion 19

Location: Android Studio

Error:

e: .../FlutterUnityWidgetBuilder.kt: (15, 42): Expecting a parameter declaratione: .../FlutterUnityWidgetBuilder.kt: (23, 25): Expecting an argumente: .../FlutterUnityWidgetController.kt: (22, 44): Expecting a parameter declaratione: .../FlutterUnityWidgetFactory.kt: (13, 58): Expecting a parameter declaration

Solution:

1. Open theandroid/build.gradle file and change the following:

-    ext.kotlin_version = '1.3.50'+    ext.kotlin_version = '1.4.31'

Location: Android Studio

Error:

Unable to find a matching variant of project :unityLibrary:

Solution:

1. Open theandroid/app/build.gradle file and change the following:

     lintOptions {         disable 'InvalidPackage'+        checkReleaseBuilds false     }

The easiest way to apply flavors for your app would be:flutter_flavorizr.

If you use flavors in your app you will notice that especially iOS crashes while running or building your app!Here are the necessary steps for flavored apps:

No changes needed. Flavors are applied without any additional setups.

For your Unity iOS-Build you have to add your flavors to your Unity iOS Configuration.

1. Check your actualRunner (your app) configurations. If you have for example the flavors:

• dev
• prod

YourRunner configurations are looking like this:

So you have the flavors:

• Debug-dev
• Profile-dev
• Release-dev
• Debug-prod
• Profile-prod
• Release-prod

These flavors needs to be added to yourUnity-IPhone project.

2. Go into yourUnity-IPhone project -> PROJECTUnity-IPhone -> Info:

Here you can see in the Configurations section only:

• Release
• ReleaseForProfiling
• ReleaseForRunning
• Debug

3. CopyDebug configuration twice and rename them toDebug-dev and the second toDebug-prod.

You can do that by selecting+ and duplicate the configuration like this:

4. Repeat this withRelease toRelease-dev andRelease-prod.

5. Repeat this withRelease toProfile-dev andProfile-prod.

6. YourUnity-IPhone configurations should now look like this:

Flutter on default doesn't support--flavor for building web. But you can set your targetmain.dart entrypoint (with-t main.dart) while running and building. So if you setup your flavors properly there're also no changes needed for web to apply changes for your Flutter-Unity web App.

• Remember to disabled fullscreen in unity player settings to disable unity fullscreen.
• Unity freezes and crashes on Android, please use OpenGL3 as Graphics API.
• Project fails to build due to some native dependencies in your unity project, please integrate the native libraries for those dependencies on Android or iOS
• App crashes on screen exit and re-entry do this

  Build Setting - iOS - Other Settings - Configuration - Enable Custom Background Behaviors or iOS

• Android builds takes forever to complete Unity 2022.1.*, remove these lines from unityLibrary/build.gradle file

  commandLineArgs.add("--enable-debugger")commandLineArgs.add("--profiler-report")commandLineArgs.add("--profiler-output-file=" + workingDir + "/build/il2cpp_"+ abi + "_" + configuration + "/il2cpp_conv.traceevents")

Flutter widgets stacked on top of the UnityWidget will not register clicks or taps. This is aFlutter issue and can be solved by using thePointerInterceptor package.

Example usage:

Stack(  children: [UnityWidget(      onUnityCreated: onUnityCreated,      onUnityMessage: onUnityMessage,      onUnitySceneLoaded: onUnitySceneLoaded,    ),Positioned(      bottom:20,      left:20,      right:20,      child:PointerInterceptor(        child:ElevatedButton(          onPressed: () {// do something          },          child:constText('Example button'),        ),      ),    ),

We already integrated this into ourExamples in the/example folder.

Support this project with your organization. Your donations will be used to help children first and then those in need. Your logo will show up here with a link to your website. [Contribute]

Thanks goes to these wonderful people (emoji key):

Rex Raphael 💻📖💬🐛👀✅

Thomas Stockx 💻📖💬✅

Kris Pypen 💻📖💬✅

Lorant Csonka 📖📹

This project follows theall-contributors specification. Contributions of any kind welcome!