unity_widget 1.0.4

Embed Unity into Flutter iOS, Android and Web

unity_widget

A Flutter plugin for embedding Unity projects in Flutter projects.

Supports Android, iOS and Web (Also supports CanvasKit).

Disclaimer

This Plugin was tested and approved with Unity 2019.* and 2020.* for full support of not only 3D-Rendering but also AR/VR Features (corresponding to: Unity AR Foundation, ARCore, ARKit and so on). It CAN be possible that this Plugin also works for latest stable Unity versions and beta versions, but we cannot give any guarantee that it works. So always keep that in mind and be prepared before you update any Unity Editor or AR/VR Plugins in your Unity version! Anyways: always test and be careful before updating anything on Unity side.

Usage

To use this plugin, add unity_widget as a dependency in your pubspec.yaml file.

Example

Refer to the example project and the included Unity project.

Testing

To test this plugin, do the following:

1. Run git clone https://github.com/Ahmadre/unity_widget.git to create a local copy of unity_widget.
2. Open unity_widget in Android Studio.

Android

3. Connect your Android device and run the project.

iOS

3. Configure the example project and the included Unity project.
4. Connect your iOS device and run the project.

Configuring your Unity project

Android

1. Go to File > Build Settings... to open the Build Settings window.
2. Select Android and click Switch Platform.
3. Click Add Open Scenes.
4. Check Export Project.
5. Click Player Settings... to open the Player Settings window.
6. In the Player Settings window, configure the following:

Setting	Value
Resolution and Presentation > Start in fullscreen mode	No
Other Settings > Rendering > Graphics APIs	OpenGLES3
Other Settings > Configuration > Scripting Backend	IL2CPP
Other Settings > Configuration > Target Architectures	ARMv7, ARM64

7. Close the Player Settings window.
8. Click Export and save as unityExport.

iOS

1. Go to File > Build Settings... to open the Build Settings window.
2. Select iOS and click Switch Platform.
3. Click Add Open Scenes.
4. Click Build and save as UnityProject.

Configuring your Flutter project

Android

1. Copy the unityExport folder to <your_flutter_project>/android/unityExport.
2. Run flutter pub run unity_widget:unity_export_transmogrify.
3. Open <your_flutter_project>/android/unityExport/build.gradle and check if buildTypes { profile {} } is present. If not, add the following:

buildTypes {
    profile {}
}

Refer to the example project's unityExport/build.gradle.

4. Open <your_flutter_project>/android/build.gradle and, under allprojects { repositories {} }, add the following:

flatDir {
    dirs "${project(':unityExport').projectDir}/libs"
}

Refer to the example project's build.gradle.

5. Open <your_flutter_project>/android/settings.gradle and add the following:

include ':unityExport'

Refer to the example project's settings.gradle.

6. Open <your_flutter_project>/android/app/src/main/AndroidManifest.xml and add the following:

<uses-permission android:name="android.permission.WAKE_LOCK"/>

Refer to the example project's AndroidManifest.xml.

Steps 1, 2 and 3 must be repeated for every new build of the Unity project.

NDK

If your project requires Android NDK, you have to setup following:

Your android project needs to know the path of the NDK Unity uses. You can find the path to the NDK under Preferences -> External Tools:

Copy the path and paste the path here in your android/local.properties:

    ndk.dir=/Applications/Unity/Hub/Editor/2020.3.19f1/PlaybackEngines/AndroidPlayer/NDK

That's it! You don't need to tell your Android App in your app/build.gradle the NDK version or other NDK settings. It's all connected to Unity now.

iOS

1. Copy the UnityProject folder to <your_flutter_project>/ios/UnityProject and open <your_flutter_project>/ios/Runner.xcworkspace in Xcode.
2. Go to File > Add Files to "Runner"..., and add <your_flutter_project>/ios/UnityProject/Unity-iPhone.xcodeproj.
3. Select Unity-iPhone/Data, and, in the Inspectors pane, set the Target Membership to UnityFramework.
4. Select Unity-iPhone, select PROJECT : Unity-iPhone, and, in the Build Settings tab, configure the following:

Setting	Value
Build Options > Enable Bitcode	No
Linking > Other Linker Flags	-Wl,-U,_FlutterUnityPluginOnMessage

5. Select Runner, select TARGETS : Runner, and, in the General tab, configure the following:

Setting	Value
Frameworks, Libraries, and Embedded Content	Name Embed UnityFramework.framework Embed & Sign

6. Select Runner/Runner/Info.plist, and configure the following:

Key	Type	Value
io.flutter.embedded_views_preview	Boolean	YES

Steps 1, 3 and 4 must be repeated for every new build of the Unity project.

Web

1. Copy MessageHandler.jslib from bin folder into your Unity-Project: MyFlutterProject/MyUnityProject/Assets/Plugins.

2. In Unity Tap on your MessageHandler and your config should look like this:

Now tap on Apply.

Keep in mind that if you change anything in MessageHandler you have to rebuild your Unity WebGL Build to apply the changes for Flutter Web!

3. Build Unity for Web (WebGL) in Unity.

4. Place the exported unity WebGL build folder inside web folder.

5. Modify the index.html file inside unity WebGL build folder.

   • Add following script in index.html.

     let globalUnityInstance;
     
     window["receiveMessageFromUnity"] = function (params) {
       window.parent.postMessage(params, "*");
     };
     
     window.parent.addEventListener("flutter2js", function (params) {
       const obj = JSON.parse(params.data);
       globalUnityInstance.SendMessage(obj.gameObject, obj.method, obj.data);
     });
     

     index.html file after adding the above script.

     

   • Add following script in index.html.

     window.parent.postMessage("unity_loaded", "*");
     globalUnityInstance = unityInstance;
     

     index.html file after adding the above script.

     

Tip: Save your Unity's index.html and TemplateData/style.css somewhere in your project and replace it to shorten the steps above.

Flavors

Recommendation

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

If you use flavors in your app here are the setup steps for flavored apps:

Android

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

iOS

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

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

• dev
• prod

Your Runner 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 your Unity-IPhone project.

2. Go into your Unity-IPhone project -> PROJECT Unity-IPhone -> Info:

Here you can see in the Configurations section only:

• Release
• ReleaseForProfiling
• ReleaseForRunning
• Debug

3. Copy Debug configuration twice and rename them to Debug-dev and the second to Debug-prod.

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

4. Repeat this with Release to Release-dev and Release-prod.

5. Repeat this with Release to Profile-dev and Profile-prod.

6. Your Unity-IPhone configurations should now look like this:

Web

Flutter on default doesn't support --flavor for building web. But you can set your target main.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.

Exchanging messages between Flutter and Unity

Flutter

To send a message, define the onCreated callback in your UnityView widget, and use the send method from the received controller.

To receive a message, define the onMessage callback in your UnityView widget.

Unity

To send and receive messages, include FlutterUnityPlugin.cs in your project, and use the Messages.Send and Messages.Receive methods.

A Message object has the following members:

• id (int)

A non-negative number representing the source view when receiving a message, and the destination view when sending a message. When sending a message, it can also be set to a negative number, indicating that the message is intended for any existing view.

• data (string)

The actual message.

Refer to the included Unity project's Rotate.cs.

Solutions to problems

Unity freezes for unknown reason and you cannot see any error messages in Flutter or Unity:

Sometimes both Flutter as well as Unity won't tell you what's happening and why your Unity Build is crashing. This is mostly happening on Unity Android (on my experience). If you take a deeper look into Android Studio you see in Logcat this:

1. learning: If you don't know what's happening in Unity iOS or Android, have a look into the console in either XCode or Android Studio!
2. learning: Sometimes we see here like the error above, that even the Unity Team can introduce errors which occurs for our exported Unity Android Build.
3. learning: Unity Android setup is using ProGuard which secures your app against security risks that can occur. To solve the error above:

ClassNotFoundException: com.unity3d.plugin.UnityAndroidPermission

Add this line to android/unityExport/proguard-unity.txt: