Unity needs an explicit refocus after being embedded in a Flutter platform view — windowFocusChanged(true) → pause() → resume(). unity_kit does this automatically in UnityKitViewController.

1. 1Make sure you're using the latest unity_kit version.
2. 2Check that UnityPlayerManager successfully created the player (check logs).
3. 3Verify the platform view mode is AndroidView (Virtual Display), not PlatformViewLink (Hybrid Composition — causes app freeze).

Most common cause: Unity's Metal renderer creates textures matching the view size. Initialized before the view has layout, it gets 0×0 and crashes (MTLTextureDescriptor has width of zero). unity_kit prevents this with waitForNonZeroFrame(), which polls until the container view has non-zero bounds.

1. 1Make sure UnityView has a non-zero size in the layout (not hidden, not zero-height).
2. 2Check that UnityFramework.framework loaded successfully (iOS logs).
3. 3Check for onError events on the Dart side.

After a scene change, Unity's window level might reset — unity_kit sets it below Flutter's (UIWindow.Level.normal − 1).

A known platform issue, especially on Android < 10, where SurfaceView z-ordering is unreliable. Reported from a BottomNavigationBar tab / IndexedStack where Unity covered everything — a real rendering bug fixed in unity_kit 0.9.2.

1. 1Upgrade the package to unity_kit ≥ 0.9.2.
2. 2Use Android 10+ if possible.
3. 3Use AndroidView (Virtual Display) mode — Unity renders into a virtual display that Flutter composites.

The UnityContainerLayout overrides onWindowVisibilityChanged(VISIBLE) to call pause() + resume(), which restarts the rendering pipeline.

If you're using a custom container, add this pattern.

Two common causes, both patched by unity_kit's UnityContainerLayout.

1. 1Missing source type: Unity's New Input System requires InputDevice.SOURCE_TOUCHSCREEN — unity_kit sets this automatically.
2. 2DeviceId = 0: Flutter's Virtual Display sends events with deviceId = 0, which Unity ignores — unity_kit patches this.

If you use a custom touch handler, make sure both fixes are applied.

unity_kit forwards touch events via UIKit. Check that gesture recognizers on the Unity view are configured.

With the old Input Manager multi-touch should work; with the New Input System, verify the EnhancedTouch module is enabled.

The bridge target isn't wired up on the Unity side.

1. 1FlutterBridge GameObject must exist in the first loaded scene (auto-creates via [RuntimeInitializeOnLoadMethod], but manual placement is recommended).
2. 2sendReadyOnStart must be enabled on the FlutterBridge component.
3. 3Check the target name matches — FlutterMonoBehaviour uses GameObject.name by default (or the custom Target Name field).
4. 4Check the Unity Console for: [UnityKit] No handler registered for target: xxx.

The native send path is broken or stripped from the build.

1. 1Use NativeAPI.SendToFlutter() (not Debug.Log).
2. 2Android: verify com.unity_kit.FlutterBridgeRegistry is not stripped by ProGuard (see Build & release).
3. 3iOS: verify UnityKitNativeBridge.mm is in Assets/Plugins/iOS/ and compiled into UnityFramework.
4. 4Editor: messages go to Console only — there is no Flutter connection in Play Mode.

Plain bridge.send() throws EngineNotReadyException if Unity isn't ready. Use bridge.sendWhenReady() — the readiness guard queues messages and auto-flushes when Unity reports ready.

// This throws EngineNotReadyException if Unity isn't ready:
bridge.send(message);

// This queues and sends automatically when ready:
bridge.sendWhenReady(message);

unity_kit uses a bridge independent of the widget, so — unlike flutter_unity_widget, where the controller dies with the widget — the bridge survives navigation. Create it once in a service layer and pass it in.

// Create the bridge once (e.g. in a service/provider)
final bridge = UnityBridgeImpl(platform: UnityKitPlatform.instance);

// Pass it to the widget - the widget does NOT dispose it
UnityView(bridge: bridge, ...);

If you let the widget create its own bridge (bridge: null), it's disposed when the widget is removed. A related crash — MissingPluginException on re-opening a Unity screen, where the destroyed platform view left Dart targeting the dead com.unity_kit/unity_view_N channel — was fixed in unity_kit 2.0.1: native now emits onViewDisposed, the bridge resets to initializing, sendWhenReady() queues until the next UnityView attaches, and send() throws a typed EngineNotReadyException instead of crashing. Upgrade to ≥ 2.0.1.

Assets/Scripts/UnityKit/Editor/Build.cs is missing or has compilation errors. Editor scripts must live inside an Editor/ folder.

Check the Unity Console for errors.

ProGuard/R8 is stripping classes used via reflection and JNI. Build.cs auto-adds ProGuard rules during export — verify proguard-unity.txt exists in unityLibrary/ and contains the keep rules.

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

This is critical — without it, release builds silently fail (no crash, just non-functional).

Every new Flutter version can change the Gradle/Kotlin/JVM requirements. Build.cs patches build.gradle automatically during export.

1. 1Re-export from Unity (Flutter > Export Android).
2. 2Make sure Build.cs is up-to-date (latest from unity_kit/unity/).
3. 3Flutter 3.29+ uses Kotlin DSL (build.gradle.kts) — Build.cs handles both.

UnityFramework.framework is not in the expected location.

1. 1The iOS export completed successfully (Flutter > Export iOS).
2. 2Builds/ios/UnityLibrary/ contains the Xcode project.
3. 3For local dev: create a symlink from unity_kit/ios/ to the built framework.

The UnityKitNativeBridge.mm file is not compiled into UnityFramework. It must be in Assets/Plugins/iOS/ before the Unity export — Unity's build system automatically includes files from that folder.

Add your custom [Serializable] classes to link.xml. unity_kit's own link.xml already preserves UnityKit DTOs.

<linker>
    <assembly fullname="Assembly-CSharp">
        <type fullname="YourNamespace.YourClass" preserve="all"/>
    </assembly>
</linker>

These APIs exist only in Unity 6000+. Build.cs uses BuildTargetGroup instead (compatible with Unity 2022.3+). Make sure you have the latest Build.cs from unity_kit/unity/Assets/Scripts/UnityKit/Editor/.

Unity 6 renamed the player class and changed view extraction. unity_kit handles both automatically via reflection — no manual configuration needed.

1. 1Constructor: 2022.3 uses UnityPlayer(Activity); 6000+ uses UnityPlayerForActivityOrService(Context, IUnityPlayerLifecycleEvents?). unity_kit tries both.
2. 2View extraction: Unity 6's player is not a View — unity_kit calls getFrameLayout(), falling back through getView(), getPlayerView(), getSurfaceView(), getRootView(), then legacy.

Unity can't resolve the addressable at runtime.

1. 1SetCachePath must be called first — Flutter must tell Unity where the downloaded bundles are before any load.
2. 2Verify the addressable key matches between Flutter and Unity (what Flutter sends must match the 'Address' field in Unity's Addressables Groups window).
3. 3Check that the bundle was actually downloaded to the cache path (verify the file exists).
4. 4Rebuild Addressables after any asset changes: Flutter > Build Addressables.

AddressablesManifestBuilder generates metadata.addressableKeys by matching Addressable group entries to built bundle filenames.

1. 1Rebuild: Flutter > Build Addressables.
2. 2Check that the asset has an address set in the Addressables Groups window.
3. 3Check that the asset's group has Remote build/load paths.

The TransformInternalId callback in FlutterAddressablesManager intercepts Unity's remote URLs and redirects to the local cache.

1. 1SetCachePath was called with the correct path.
2. 2The bundle filename in cache matches what Unity expects.
3. 3The catalog was loaded (LoadContentCatalog or UpdateCatalog).

Unity as a Library allows a single shared Unity player per process. UnityPlayerManager.shared survives navigation by design — keep one instance alive and switch scenes rather than mounting two Unity views.

This is a Unity limitation, not a unity_kit bug — quit() kills the process and the player cannot restart. Use pause() / resume() instead, or load an empty scene to 'reset'.

Unity retains 80–180 MB even after 'unload'. This is a platform limitation.

1. 1Keep Unity alive, swap scenes (don't try to destroy/recreate).
2. 2Load an empty scene before disposing the widget to free scene-specific resources.
3. 3Use Addressables.Release() to unload assets you no longer need.

flutter_unity_widget crashes after 2–3 navigations (issue #281, open 5+ years) because resources are never freed. unity_kit addresses this with proper dispose() chains and WeakListener patterns, but the fundamental Unity memory behavior remains.

UnityFramework.framework is built for arm64 device architecture only. Always test on physical devices — this applies even on Apple Silicon Macs (the simulator runs arm64 but may still have compatibility issues).

Do NOT use PlatformViewLink + initExpensiveAndroidView for the Unity view. Use AndroidView (Virtual Display) mode — Hybrid Composition conflicts with Unity's rendering pipeline.

flutter run only captures Debug.Log (Unity) and print() (Dart). Swift NSLog is not forwarded — for debugging, send info through the bridge.

sendEvent(name: "onUnityMessage", data: "debug:someValue=\(value)")