Unity export guide

The Unity project and the Flutter project are completely separate - they can live in different folders, different repos, or even different machines. Build.cs exports Unity as a standalone artifact into a local Builds/ folder; you then optionally deploy that artifact into a Flutter project.

Copy the entire UnityKit/ folder from the unity_kit package into your Unity project. This ships the message-bridge runtime plus the Editor export automation that adds the Flutter menu.

Assets/Scripts/UnityKit/
+-- Editor/
|   +-- Build.cs                      # Export automation (Flutter menu)
|   +-- XCodePostBuild.cs             # iOS Xcode post-processing
|   +-- SweetShellHelper.cs           # Shell helper for build scripts
+-- FlutterBridge.cs                  # Singleton message receiver
+-- FlutterMessage.cs                 # Message DTO: {target, method, data}
+-- FlutterMonoBehaviour.cs           # Base class for Flutter-aware scripts
+-- MessageBatcher.cs                 # Per-frame message batching
+-- MessageRouter.cs                  # Target-based message routing
+-- NativeAPI.cs                      # Platform-specific native calls
+-- SceneTracker.cs                   # Auto scene load/unload notifications
+-- FlutterAddressablesManager.cs     # Addressables integration (optional)
+-- link.xml                          # IL2CPP type preservation

Open the project in the Unity Editor and wait for scripts to compile. A Flutter menu should appear in the menu bar. If it does not, confirm Assets/Scripts/UnityKit/Editor/Build.cs exists and compiles without errors (Editor scripts must live inside an Editor/ folder).

Once Build.cs compiles, every export and the Settings window are reachable from the Flutter menu. Every item and its keyboard shortcut:

Exports always go to the Builds/ folder inside your Unity project. If a Flutter project path is configured (see Deploy below), artifacts are also auto-copied there. Switch to the target platform first, then run the matching export.

A raw Unity export is a standalone app, not something Flutter can embed. Build.cs post-processes each artifact into a library module. On Android, steps 1-9 run on every export; steps 10-12 patch the Flutter project and run only during a deploy.

-keep class com.unity_kit.** { *; }
-keep class com.unity3d.player.** { *; }

Deploying copies whichever artifacts exist in Builds/ into the matching folders in the Flutter project and patches the Android Gradle files. There are three ways to do it.

For CI/CD, drive the same exports in batch mode via -executeMethod. The entry points run identical post-processing to the menu items. iOS commands must include -buildTarget iOS.

# Set the Flutter project path (optional -- skip for standalone artifact)
export UNITY_KIT_FLUTTER_PROJECT="/path/to/my_flutter_app"

# Android Debug
Unity -quit -batchmode -projectPath /path/to/MyUnityProject \
  -executeMethod UnityKit.Editor.Build.ExportAndroidDebug

# Android Release
Unity -quit -batchmode -projectPath /path/to/MyUnityProject \
  -executeMethod UnityKit.Editor.Build.ExportAndroidRelease

# iOS Debug (must set -buildTarget iOS)
Unity -quit -batchmode -projectPath /path/to/MyUnityProject \
  -buildTarget iOS \
  -executeMethod UnityKit.Editor.Build.ExportIOSDebug

# iOS Release
Unity -quit -batchmode -projectPath /path/to/MyUnityProject \
  -buildTarget iOS \
  -executeMethod UnityKit.Editor.Build.ExportIOSRelease

# WebGL
Unity -quit -batchmode -projectPath /path/to/MyUnityProject \
  -executeMethod UnityKit.Editor.Build.ExportWebGL

Without UNITY_KIT_FLUTTER_PROJECT, artifacts stay in Builds/ as a standalone artifact - upload them from the Unity job and download them into the Flutter job:

# Example GitHub Actions workflow
unity-build:
  steps:
    - name: Export Android
      run: Unity -quit -batchmode ...
    - name: Upload artifact
      uses: actions/upload-artifact@v4
      with:
        name: unity-android
        path: MyUnityProject/Builds/android/unityLibrary/

flutter-build:
  needs: unity-build
  steps:
    - name: Download Unity artifact
      uses: actions/download-artifact@v4
      with:
        name: unity-android
        path: my_flutter_app/android/unityLibrary/
    - name: Build Flutter
      run: cd my_flutter_app && flutter build apk

An export is a compiled snapshot of your Unity project. Re-export (and redeploy, or let auto-deploy handle it) whenever an input to that snapshot changes: