Ios Unable to load upon secondary opening

[xiyangzzz]

Question

My application has multiple Unity scenarios. When I exit the current scene and want to enter another scene, or enter another scene again, the scene cannot be loaded. I tried to separate the bridge from the Widget and adopt a global singleton mode. But this still doesn't work on iOS. Can you provide an example of how to manage the lifecycle of a bridge in this situation.
Flutter (Channel stable, 3.22.3, on macOS 26.4.1 25E253 darwin-arm64, locale zh-Hans-CN)

[✓] Android toolchain - develop for Android devices (Android SDK version 36.0.0)
[✓] Xcode - develop for iOS and macOS (Xcode 26.4.1)
[✓] Chrome - develop for the web
[✓] Android Studio (version 2025.1)
[✓] VS Code (version 1.126.0)
[✓] Connected device (5 available)
! Error: Browsing on the local area network for Test iPad. Ensure the device is unlocked and attached with a cable or associated with the same local area
network as this Mac.
The device must be opted into Developer Mode to connect wirelessly. (code -27)
[✓] Network resources

unity_kit: ^2.0.0

Area

Setup / Installation

Context

No response

[erykkruk]

Hi @xiyangzzz, thanks for the detailed report! 👋

Separating the bridge from the widget and making it a singleton is exactly the right first step — it's just not the whole story on iOS. Here's what's actually happening and the pattern that makes multi-scene navigation reliable.

Why the second open fails on iOS

There is only ever one Unity player per process. On iOS unity_kit owns it through a singleton (UnityPlayerManager.shared) that deliberately survives Flutter navigation, and there is a single native Unity view (appController().rootView). Two different things can break the "second open":

1. The bridge/engine got disposed on exit. Once Unity is torn down it can't be recreated in the same process — a Unity limitation, see "Unity can't be restarted after quit()" in the FAQ. A singleton bridge fixes this — which you've already done.
2. A second UnityView gets mounted. Because there is only one shared Unity view, each UnityView's container claims it via attachUnityView(...), which calls removeFromSuperview() first. So if two UnityViews are alive at once (e.g. you push a screen that builds its own UnityView over the previous one), they tug that single surface back and forth and the second screen ends up blank.

Since your bridge is already a singleton, #1 is probably handled — your remaining cause is almost certainly #2. The fix is to keep one Unity instance and one UnityView alive for the whole app and switch scenes inside it, instead of giving each screen its own view.

Two rules that make it work

1. One long-lived bridge, owned outside the widget.
Create a single UnityBridgeImpl in your service/DI layer, initialize() it once, and pass it into UnityView(bridge: ...). UnityView never disposes an external bridge (by design — the "bridge survives widget" behaviour), so the engine survives navigation. A bridge the widget created itself (bridge: null) does get disposed with the widget. Never call bridge.dispose() on screen exit — that's app-shutdown only.

2. Mount UnityView exactly once, high in the tree. ← this is the one biting you.
Put a single UnityView in a persistent host above your Navigator and keep it mounted for the app's lifetime; your routes sit on top of it. Don't let individual screens build their own UnityView — that's what triggers the removeFromSuperview tug-of-war above.

Switch scenarios by loading scenes, not by remounting Unity

Send a scene-change command into the one instance and let Unity switch the scene:

bridge.sendWhenReady(
  UnityMessage.command('LoadScene', {'name': 'SceneB'}),
);

LoadScene here is just a message type — there's no built-in handler. On the Unity/C# side you add a small handler (a FlutterMonoBehaviour on the FlutterBridge object) that reacts to it and calls SceneManager.LoadScene(name). Use sendWhenReady (not send) so the first message is queued until Unity is ready instead of throwing EngineNotReadyException. Listen for completion via onSceneLoaded / bridge.sceneStream (SceneInfo).

To free a scene's memory between scenarios without killing the engine: load a lightweight/empty scene first (or call bridge.unload(), which keeps the process alive), and Addressables.Release() any assets you no longer need. The FlutterBridge GameObject is DontDestroyOnLoad, so it persists across scene loads.

Minimal shape

// 1. One process-lifetime bridge (register in get_it / a provider / a plain singleton)
class UnityService {
  UnityService() : bridge = UnityBridgeImpl(platform: UnityKitPlatform.instance);

  final UnityBridge bridge;

  Future<void> init() => bridge.initialize();

  Future<void> loadScene(String name) =>
      bridge.sendWhenReady(UnityMessage.command('LoadScene', {'name': name}));
}

// 2. One persistent host — mounted once, above the Navigator, never disposed per screen
class UnityHost extends StatelessWidget {
  const UnityHost({super.key, required this.bridge});

  final UnityBridge bridge;

  @override
  Widget build(BuildContext context) {
    return UnityView(
      bridge: bridge, // external bridge => UnityView will NOT dispose it
      placeholder: const ColoredBox(color: Color(0xFF000000)),
      onSceneLoaded: (scene) => debugPrint('scene ready: ${scene.name}'),
    );
  }
}

// 3. Navigation just swaps scenes — it never mounts or disposes a second UnityView
await unityService.loadScene('SceneB');

The whole trick: screens come and go, but the bridge + the single UnityView stay put; scene changes are messages, not remounts.

iOS gotchas worth double-checking

• Physical device only — the iOS simulator can't load UnityFramework (arm64 device architecture only).
• Non-zero size at mount — if UnityView mounts inside a zero-height / offstage / collapsed container, Metal creates a 0×0 texture and you get a blank screen or crash. Give it real bounds.
• Window level — after a scene change Unity's window level can reset; unity_kit re-lowers it below Flutter automatically (see the FAQ).

If it still won't load the second scene after this, capture bridge.eventStream (the onEvent callback) plus the [UnityKit]-prefixed Unity logs around the second load and paste them here — that'll show whether it's the second-platform-view collision or something else.

Hope that helps! 🙌

[xiyangzzz]

@erykkruk Hello, thank you for your answer. I adopted your method when I entered the call jump for the second time. An error was reported.

[unity_kit] [UnityKit] ERROR: Failed to send message: CallMethod
[unity_kit] MissingPluginException (MissingPluginException(No implementation found for method unity#postMessage on channel com.unity_kit/unity_view_0))
[unity_kit] #0 MethodChannel._invokeMethod (package:flutter/src/services/platform_channel.dart:332:7)

#1 UnityKitMethodChannel.postMessage (package:unity_kit/src/platform/unity_kit_method_channel.dart:94:7)

#2 UnityBridgeImpl._postToPlatform (package:unity_kit/src/bridge/unity_bridge.dart:317:7)

#3 UnityBridgeImpl._sendToPlatform (package:unity_kit/src/bridge/unity_bridge.dart:310:7)

class UnityBridgeManager {
static final UnityBridgeManager instance = UnityBridgeManager._();

UnityBridgeManager._();

UnityBridgeImpl? _bridge;
Future? _initFuture;

UnityBridge get bridge =>
_bridge ??= UnityBridgeImpl(platform: UnityKitPlatform.instance);

/// Ensures the Dart bridge is subscribed and past initializing.
///
/// After [UnityBridge.unload] or native onUnityUnloaded, lifecycle resets to
/// [UnityLifecycleState.uninitialized] but [_initFuture] would otherwise stay
/// completed and skip re-init — causing onUnityCreated to throw on re-entry.
Future ensureInitialized() {
if (bridge.currentState == UnityLifecycleState.uninitialized) {
_initFuture = null;
}
return _initFuture ??= _initialize();
}

Future _initialize() async {
final b = bridge;
if (b.currentState == UnityLifecycleState.uninitialized) {
PrintUtil.print('UnityBridgeManager: initializing bridge');
await b.initialize();
}
}
}
class _PersistentUnityViewState extends State {
bool _visible = false;
bool _bootstrapped = false;
StreamSubscription<Map<String, dynamic>>? _platformSubscription;

UnityBridge get _bridge => UnityBridgeManager.instance.bridge;

@OverRide
void initState() {
super.initState();
_platformSubscription =
UnityKitPlatform.instance.events.listen(_onPlatformEvent);
_bootstrap();
}

Future _bootstrap() async {
UnityTemplateController controller = Get.find();
if(controller.sceneName!="SampleScene"){
controller.jump();
setState(() => _bootstrapped = true);
}
}

@OverRide
void dispose() {
_platformSubscription?.cancel();
super.dispose();
}

@OverRide
Widget build(BuildContext context) {
if (!_bootstrapped) {
return widget.placeholder ?? const SizedBox.shrink();
}
return Stack(
children: [
UnityView(
bridge: bridge,
config: widget.config,
gestureRecognizers: widget.gestureRecognizers,
onReady: () => _markVisible(),
onMessage: widget.onMessage,
onSceneLoaded: widget.onSceneLoaded,
placeholder: null,
),
// if (!_visible && widget.placeholder != null) widget.placeholder!,
],
);
}
}

[xiyangzzz]

The above is part of my code, please check it。Thank you

[erykkruk]

Thanks for the logs and the code — that made the root cause easy to pin down. This was a real bug in unity_kit, and it's fixed in unity_kit: 2.0.1 (just published to pub.dev).

What was happening

MissingPluginException ... on channel com.unity_kit/unity_view_0 means the Dart side was still sending to the first view's channel after that platform view had been destroyed:

1. When you left the first Unity screen, Flutter disposed platform view 0. The native controller tore down the com.unity_kit/unity_view_0 method channel.
2. The Dart side never learned about it — the bridge stayed in the ready state and kept targeting view 0, so sendWhenReady sent immediately into a dead channel instead of queueing.
3. Your _bootstrap() sends the jump message in initState, before _bootstrapped = true — i.e. before the new UnityView (and its new channel) even exists. That's exactly the window where the stale channel got hit.

Fixed in 2.0.1

Native (iOS + Android) now notifies Dart with onViewDisposed before tearing the channel down. The bridge then drops back from ready to initializing, so:

• sendWhenReady() queues messages and flushes them automatically once the next UnityView attaches and Unity reports created — your early jump() will now just wait for the new view instead of crashing;
• send() throws a typed EngineNotReadyException instead of a raw MissingPluginException.

Also fixed: calling initialize() again after unload() used to double-subscribe to platform events (duplicated messages) — relevant to your ensureInitialized() re-init path.

Please upgrade:

dependencies:
  unity_kit: ^2.0.1

Two things to adjust in your code

1. _bootstrap() never mounts the view for the default scene. _bootstrapped = true is only set inside if (controller.sceneName != "SampleScene"), so when the target is SampleScene the UnityView is never built and you'll sit on the placeholder forever. Set _bootstrapped = true unconditionally.

2. Note on lifecycle states with 2.0.1: after the active view is disposed, the bridge state is now initializing (not uninitialized), because the bridge is still alive and subscribed — it's just waiting for a view. Your ensureInitialized() check for uninitialized stays correct for the unload() case; no re-initialize() is needed after a view disposal.

Your per-screen PersistentUnityView pattern will now work with 2.0.1 (messages queue across the gap between views). That said, the single UnityView mounted once above the Navigator is still the smoothest option — it avoids the detach/reattach of the Unity surface entirely, so there's no blank frame during navigation.

Let me know if the second open works after upgrading! 🙌

[erykkruk]

@xiyangzzz is it working now? :)

[xiyangzzz]

"My code works now. But I'm wondering—how do I actually set it up so that the single UnityView is mounted once, above the Navigator? My project also has other pages that have nothing to do with Unity. Should I do it through a Stack component? Also, if I keep that Unity page alive the whole time, won't that hurt performance?"