Step-by-step integration guide

unity_kit embeds a Unity scene inside a Flutter app through a typed, testable bridge. Two projects stay completely separate: your Flutter app and your Unity project. Unity exports a native library artifact that is copied into the Flutter app - the artifact only ever flows one way, from Unity into Flutter.

Start on the Flutter side. Add the dependency to pubspec.yaml, or run the equivalent command.

# pubspec.yaml
dependencies:
  unity_kit: ^2.0.0

flutter pub add unity_kit

# In-repo / monorepo alternative
dependencies:
  unity_kit:
    path: path/to/unity_kit

The Flutter package ships the C# runtime and the Editor export automation. Copy the entire folder into your Unity project - once it compiles, a Flutter menu appears in the Unity Editor menu bar.

Assets/Scripts/UnityKit/
+-- Editor/
|   +-- Build.cs                  # Export automation (adds the 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

The tree above is the doc's listing. The real folder ships more than it names - assembly definitions (UnityKit.asmdef), a Tests/ folder, UnityKitMethodAttribute.cs, UnityKitLogger.cs, UnityKitBinaryCodec.cs, UnityKitPerformanceMonitor.cs and more. Copy everything.

The FlutterBridge GameObject is the entry point for all Flutter ⟷ Unity communication. It uses DontDestroyOnLoad, so it persists across scene changes - put it in your first loaded scene.

1. 1
   Open your main scene in the Unity Editor.
2. 2
   Create an empty GameObject: GameObject > Create Empty.
3. 3
   Rename it to FlutterBridge - the name matters, because Flutter addresses it via UnitySendMessage("FlutterBridge", ...).
4. 4
   Add the component: Add Component > UnityKit > FlutterBridge. Keep Send Ready On Start enabled (default true) so Unity emits {"type":"ready"} on startup.

Open Edit > Project Settings > Player and set the scripting backend and architectures exactly as below, per platform tab.

Android
  Scripting Backend      = IL2CPP                    (Required for release builds)
  Target Architectures   = ARM64 (+ ARMv7 optional)  (Flutter requires ARM64)
  Minimum API Level      = 24                         (Flutter minimum)

iOS
  Scripting Backend      = IL2CPP       (Required)
  Target SDK             = Device SDK   (Simulator not supported)
  Architecture           = ARM64        (Required)

Note the min-SDK discrepancy: unity_kit/README.md writes minSdkVersion 22 ("Unity requires API 22+"), but doc/unity-export.md requires Minimum API Level 24 ("Flutter minimum") - use 24. Before exporting, you can run Tools > UnityKit > Validate Project, which checks the build scene list, scripting backend, ARM64 and the Android min SDK.

Switch platform (File > Build Settings > Switch Platform), then export via the Flutter menu. Every export writes into the Builds/ folder inside the Unity project.

# Optional: set the Flutter project path for auto-deploy
export UNITY_KIT_FLUTTER_PROJECT="/path/to/my_flutter_app"

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

# iOS Debug / Release (must set -buildTarget iOS)
Unity -quit -batchmode -projectPath /path/to/MyUnityProject \
  -buildTarget iOS \
  -executeMethod UnityKit.Editor.Build.ExportIOSDebug
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

The exported library must land inside the Flutter project. Deploy it three ways: manually via Flutter > Settings > Deploy to Flutter Project, automatically on every export (Phase 6), or by copying the artifact yourself in CI.

// android/settings.gradle
include ':unityLibrary'
project(':unityLibrary').projectDir = file('./unityLibrary')

// android/build.gradle
allprojects {
    repositories {
        flatDir {
            dirs "${project(':unityLibrary').projectDir}/libs"
        }
    }
}

// android/app/build.gradle
dependencies {
    implementation project(':unityLibrary')
}

Two Android settings are always manual - Build.cs does not touch them. Both go in the host app's android/app/build.gradle, inside android { defaultConfig { ... } }.

// android/app/build.gradle
android {
    defaultConfig {
        minSdkVersion 24 // doc/unity-export.md: Flutter minimum (README writes 22)
        ndk {
            abiFilters 'armeabi-v7a', 'arm64-v8a'
        }
    }
}

Edit the Flutter app's ios/Podfile to pin the platform version and disable Bitcode on every pod target:

# ios/Podfile
platform :ios, '13.0'

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['ENABLE_BITCODE'] = 'NO'
    end
  end
end

Then export the Unity project as an iOS framework and include the resulting UnityFramework in your Runner workspace. The docs give no per-click Xcode steps beyond that - at runtime the plugin loads the framework from Bundle.main.bundlePath + "/Frameworks/UnityFramework.framework", so it must end up embedded in the app bundle's Frameworks/ directory.

Now wire both sides. On the Flutter side, create the bridge, embed UnityView, send once Unity is ready, and read responses off onMessage / messageStream.

import 'package:unity_kit/unity_kit.dart';

// 1. Create the bridge (independent of any widget)
final bridge = UnityBridgeImpl(platform: UnityKitPlatform.instance);
await bridge.initialize();

// 2. Embed the Unity view
UnityView(
  bridge: bridge,
  config: const UnityConfig(sceneName: 'MainScene'),
  placeholder: const UnityPlaceholder(message: 'Loading 3D...'),
  onReady: (bridge) {
    // Unity is up -- send a command
    bridge.send(UnityMessage.command('StartGame'));
  },
  onMessage: (message) {
    // 3. Receive Unity -> Flutter responses
    print('From Unity: ${message.type}');
  },
  onSceneLoaded: (scene) {
    print('Scene loaded: ${scene.name}');
  },
);

To send before Unity has reported ready, use sendWhenReady - it queues the message and auto-flushes when the engine starts (plain send throws EngineNotReadyException if the engine is not up yet):

// Fire before Unity is ready: queues and auto-flushes on ready
await bridge.sendWhenReady(
  UnityMessage.command('Init', {'userId': '123'}),
);

// Or subscribe to the message stream directly
bridge.messageStream.listen((msg) {
  switch (msg.type) {
    case 'score_updated':
      final score = msg.data?['score'] as int?;
      // update UI
    case 'game_over':
      // show results
  }
});

On the Unity side, extend FlutterMonoBehaviour - it auto-registers with MessageRouter, using the GameObject name as its target (override it with the Inspector Target Namefield). Respond with NativeAPI.SendToFlutter(json) or the SendToFlutter(type, data) helper.

using UnityEngine;
using UnityKit;

// Receive a message from Flutter and respond
public class MyHandler : FlutterMonoBehaviour
{
    protected override void OnFlutterMessage(string method, string data)
    {
        switch (method)
        {
            case "StartGame":
                // do something, then reply
                NativeAPI.SendToFlutter("{\"type\":\"game_started\"}");
                break;
        }
    }
}

A clean build is not proof the integration works. Run on a physical device and confirm the Unity view actually renders. If something is off, match the symptom to its check: