@hugebug4ever/react-native-unity 0.0.1

package/README.md

@@ -0,0 +1,77 @@
+# @hugebug4ever/react-native-unity
+
+Embeds one process-wide Unity 6000.3 runtime in React Native 0.86-0.87 using Fabric and the New Architecture.
+
+## Install
+
+```sh
+npm install @hugebug4ever/react-native-unity
+```
+
+Add the Expo config plugin. Paths are relative to the app root and show their default values:
+
+```js
+module.exports = {
+  expo: {
+    newArchEnabled: true,
+    plugins: [
+      [
+        '@hugebug4ever/react-native-unity',
+        {
+          androidExportPath: 'unity/builds/android/unityLibrary',
+          iosExportPath: 'unity/builds/ios',
+        },
+      ],
+    ],
+  },
+};
+```
+
+Export Unity, then generate the native app:
+
+```sh
+npx rn-unity export --platform android --unity-project unity --output unity/builds/android
+npx expo prebuild
+npx rn-unity doctor --project . --platform android
+```
+
+On macOS, use `--platform ios` and output `unity/builds/ios`. The iOS plugin consumes the standard `Unity-iPhone.xcodeproj`; an XCFramework is not required.
+
+## API
+
+```tsx
+import { UnityRuntime, UnityView } from '@hugebug4ever/react-native-unity';
+
+<UnityView
+  style={{ flex: 1 }}
+  autoStart
+  detachedBehavior="pause"
+  onMessage={({ nativeEvent }) => console.log(nativeEvent.message)}
+/>
+
+await UnityRuntime.start();
+await UnityRuntime.sendMessage({
+  gameObject: 'Bridge',
+  methodName: 'OnMessage',
+  message: 'hello',
+});
+await UnityRuntime.pause();
+await UnityRuntime.resume();
+await UnityRuntime.unload();
+```
+
+`UnityRuntime.addListener` supports `stateChange`, `message`, and `error` and returns a removable subscription. `getState()` and `getDiagnostics()` expose lifecycle and diagnostic state.
+
+Only one visible `UnityView` may own the Unity root view. Detaching a view does not unload Unity and pauses it by default. Expo Go is unsupported because the package requires native code; use a development build or EAS native build.
+
+`unload()` only succeeds after Unity invokes its native completion callback. In the tested Unity `6000.3.15f1` Android embedded configuration that callback was not delivered, so the runtime deliberately times out with `E_UNLOAD_TIMEOUT`, transitions to terminal `failed`, and requires an app-process restart. It never creates a second Unity instance after an unsafe unload.
+
+## Support Boundary
+
+- Unity: `6000.3.x`
+- React Native: `>=0.86 <0.88`
+- iOS deployment target: 15.1
+- Android minSdk: 25
+- Architectures in the sample export: arm64-v8a and x86_64
+
+iOS source and standard-export project integration are included, but still require Mac compilation and device validation. Release readiness also requires repeated physical-device lifecycle, GPU/surface, memory, and long-running tests.

package/android/build.gradle

@@ -0,0 +1,38 @@
+buildscript {
+  repositories { google(); mavenCentral(); gradlePluginPortal() }
+  dependencies { classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.20" }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+apply plugin: "com.facebook.react"
+
+react {
+  libraryName = "RNUnitySpec"
+  codegenJavaPackageName = "com.hugebug4ever.rnunity"
+}
+
+android {
+  namespace "com.hugebug4ever.rnunity"
+  compileSdkVersion rootProject.ext.has("compileSdkVersion") ? rootProject.ext.get("compileSdkVersion") : 36
+
+  defaultConfig {
+    minSdkVersion rootProject.ext.has("minSdkVersion") ? rootProject.ext.get("minSdkVersion") : 24
+    targetSdkVersion rootProject.ext.has("targetSdkVersion") ? rootProject.ext.get("targetSdkVersion") : 36
+    consumerProguardFiles "consumer-rules.pro"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+  kotlinOptions { jvmTarget = "17" }
+}
+
+repositories { google(); mavenCentral() }
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation project(":unityLibrary")
+  compileOnly files("${project(':unityLibrary').projectDir}/libs/unity-classes.jar")
+}

package/android/consumer-rules.pro

@@ -0,0 +1,3 @@
+-keep class com.hugebug4ever.rnunity.** { *; }
+-keep class com.unity3d.player.** { *; }
+

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,4 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-feature android:glEsVersion="0x00030000" android:required="false" />
+</manifest>
+

package/android/src/main/java/com/hugebug4ever/rnunity/RNUnityBridge.kt

@@ -0,0 +1,5 @@
+package com.hugebug4ever.rnunity
+
+object RNUnityBridge {
+  @JvmStatic fun sendMessage(message: String) = UnityRuntimeController.receiveMessage(message)
+}

package/android/src/main/java/com/hugebug4ever/rnunity/RNUnityHostView.kt

@@ -0,0 +1,95 @@
+package com.hugebug4ever.rnunity
+
+import android.content.Context
+import android.view.View
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactContext
+import com.facebook.react.uimanager.UIManagerHelper
+import com.facebook.react.uimanager.events.Event
+import java.util.UUID
+
+internal class RNUnityHostView(context: Context) : FrameLayout(context) {
+  private val reactContext = context as ReactContext
+  val hostId: String = UUID.randomUUID().toString()
+  var detachedBehavior: String = "pause"
+
+  override fun onAttachedToWindow() {
+    super.onAttachedToWindow()
+    requestRuntimeAttach()
+  }
+
+  override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
+    super.onSizeChanged(w, h, oldw, oldh)
+    if (w > 0 && h > 0) requestRuntimeAttach()
+  }
+
+  override fun onDetachedFromWindow() {
+    UnityRuntimeController.detach(hostId)
+    super.onDetachedFromWindow()
+  }
+
+  override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
+    super.onLayout(changed, left, top, right, bottom)
+    val childWidth = right - left
+    val childHeight = bottom - top
+    for (index in 0 until childCount) {
+      layoutUnityChild(getChildAt(index), childWidth, childHeight)
+    }
+  }
+
+  private fun layoutUnityChild(child: View, childWidth: Int, childHeight: Int) {
+    if (childWidth <= 0 || childHeight <= 0) return
+    child.measure(
+      MeasureSpec.makeMeasureSpec(childWidth, MeasureSpec.EXACTLY),
+      MeasureSpec.makeMeasureSpec(childHeight, MeasureSpec.EXACTLY),
+    )
+    child.layout(0, 0, childWidth, childHeight)
+  }
+
+  private fun requestRuntimeAttach() {
+    if (isAttachedToWindow && width > 0 && height > 0) UnityRuntimeController.attach(this)
+  }
+
+  fun mountUnityView(view: View) {
+    if (view.parent === this) return
+    (view.parent as? ViewGroup)?.removeView(view)
+    removeAllViews()
+    addView(view, LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT))
+    layoutUnityChild(view, width, height)
+    view.requestFocus()
+  }
+
+  fun unmountUnityView(view: View?) {
+    if (view != null && view.parent === this) removeView(view)
+  }
+
+  fun emit(name: String, values: Map<String, Any?>) {
+    if (id == View.NO_ID) return
+    val map = Arguments.createMap()
+    values.forEach { (key, value) ->
+      when (value) {
+        null -> map.putNull(key)
+        is String -> map.putString(key, value)
+        is Int -> map.putInt(key, value)
+        is Number -> map.putDouble(key, value.toDouble())
+        is Boolean -> map.putBoolean(key, value)
+      }
+    }
+    val surfaceId = UIManagerHelper.getSurfaceId(this)
+    UIManagerHelper.getEventDispatcherForReactTag(reactContext, id)
+      ?.dispatchEvent(UnityHostEvent(surfaceId, id, name, map))
+  }
+}
+
+private class UnityHostEvent(
+  surfaceId: Int,
+  viewTag: Int,
+  private val name: String,
+  private val payload: com.facebook.react.bridge.WritableMap,
+) : Event<UnityHostEvent>(surfaceId, viewTag) {
+  override fun getEventName(): String = name
+  override fun getEventData() = payload
+  override fun canCoalesce(): Boolean = false
+}

package/android/src/main/java/com/hugebug4ever/rnunity/RNUnityPackage.kt

@@ -0,0 +1,31 @@
+package com.hugebug4ever.rnunity
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.ModuleSpec
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class RNUnityPackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? =
+    if (name == UnityRuntimeModule.NAME) UnityRuntimeModule(reactContext) else null
+
+  override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
+    mapOf(
+      UnityRuntimeModule.NAME to ReactModuleInfo(
+        UnityRuntimeModule.NAME,
+        UnityRuntimeModule.NAME,
+        false,
+        false,
+        false,
+        false,
+        true,
+      ),
+    )
+  }
+
+  override fun getViewManagers(reactContext: ReactApplicationContext) =
+    listOf(ModuleSpec.viewManagerSpec { RNUnityViewManager() })
+}
+

package/android/src/main/java/com/hugebug4ever/rnunity/RNUnityViewManager.kt

@@ -0,0 +1,30 @@
+package com.hugebug4ever.rnunity
+
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.SimpleViewManager
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.annotations.ReactProp
+
+internal class RNUnityViewManager : SimpleViewManager<RNUnityHostView>() {
+  override fun getName() = NAME
+  override fun createViewInstance(context: ThemedReactContext) = RNUnityHostView(context)
+
+  @ReactProp(name = "detachedBehavior")
+  fun setDetachedBehavior(view: RNUnityHostView, value: String?) {
+    view.detachedBehavior = if (value == "keepRunning") "keepRunning" else "pause"
+  }
+
+  override fun onDropViewInstance(view: RNUnityHostView) {
+    UnityRuntimeController.detach(view.hostId)
+    super.onDropViewInstance(view)
+  }
+
+  override fun getExportedCustomDirectEventTypeConstants() = mapOf(
+    "topReady" to mapOf("registrationName" to "onReady"),
+    "topMessage" to mapOf("registrationName" to "onMessage"),
+    "topStateChange" to mapOf("registrationName" to "onStateChange"),
+    "topError" to mapOf("registrationName" to "onError"),
+  )
+
+  companion object { const val NAME = "RNUnityView" }
+}

package/android/src/main/java/com/hugebug4ever/rnunity/UnityPlayerAdapter.kt

@@ -0,0 +1,58 @@
+package com.hugebug4ever.rnunity
+
+import android.app.Activity
+import android.content.Intent
+import android.content.res.Configuration
+import android.view.View
+import android.view.ViewGroup
+import com.unity3d.player.IUnityPlayerLifecycleEvents
+import com.unity3d.player.UnityPlayer
+import com.unity3d.player.UnityPlayerForActivityOrService
+
+internal interface UnityPlayerAdapter {
+  val rootView: View
+  fun start()
+  fun pause()
+  fun resume()
+  fun stop()
+  fun unload()
+  fun destroy()
+  fun configurationChanged(configuration: Configuration)
+  fun windowFocusChanged(hasFocus: Boolean)
+  fun newIntent(intent: Intent)
+  fun sendMessage(gameObject: String, methodName: String, message: String)
+  fun viewDiagnostics(): String
+}
+
+internal class Unity6000PlayerAdapter(
+  activity: Activity,
+  listener: IUnityPlayerLifecycleEvents,
+) : UnityPlayerAdapter {
+  private val player = UnityPlayerForActivityOrService(activity, listener)
+  override val rootView: View get() = player.frameLayout
+  override fun start() = player.onStart()
+  override fun pause() = player.onPause()
+  override fun resume() = player.onResume()
+  override fun stop() = player.onStop()
+  override fun unload() = player.unload()
+  override fun destroy() = player.destroy()
+  override fun configurationChanged(configuration: Configuration) = player.configurationChanged(configuration)
+  override fun windowFocusChanged(hasFocus: Boolean) = player.windowFocusChanged(hasFocus)
+  override fun newIntent(intent: Intent) = player.newIntent(intent)
+  override fun sendMessage(gameObject: String, methodName: String, message: String) =
+    UnityPlayer.UnitySendMessage(gameObject, methodName, message)
+  override fun viewDiagnostics(): String {
+    val root = player.frameLayout
+    val surface = player.surfaceView
+    return "root=${describe(root)} children=${root.childCount} " +
+      "unityView=${describe(player.view)} surface=${describe(surface)} " +
+      "surfaceParent=${surface.parent?.javaClass?.simpleName ?: "null"} " +
+      "surfaceValid=${surface.holder.surface.isValid}"
+  }
+
+  private fun describe(view: View): String {
+    val children = (view as? ViewGroup)?.childCount?.let { "/$it" }.orEmpty()
+    return "${view.javaClass.simpleName}$children[${view.width}x${view.height}," +
+      "attached=${view.isAttachedToWindow},visibility=${view.visibility}]"
+  }
+}

package/android/src/main/java/com/hugebug4ever/rnunity/UnityRuntimeController.kt

@@ -0,0 +1,329 @@
+package com.hugebug4ever.rnunity
+
+import android.app.Activity
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import android.view.ViewGroup
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import com.unity3d.player.IUnityPlayerLifecycleEvents
+import java.lang.ref.WeakReference
+import org.json.JSONArray
+import org.json.JSONObject
+
+internal object UnityRuntimeController {
+  private const val TAG = "RNUnity"
+  private const val UNLOAD_TIMEOUT_MS = 15_000L
+  private val main = Handler(Looper.getMainLooper())
+  private var state = UnityRuntimeState.IDLE
+  private var generation = 0
+  private var lastTransitionAt = System.currentTimeMillis()
+  private var lastError: Map<String, Any?>? = null
+  private val pauseReasons = linkedSetOf<PauseReason>()
+  private var activity = WeakReference<Activity>(null)
+  private var reactContext = WeakReference<ReactApplicationContext>(null)
+  private var host = WeakReference<RNUnityHostView>(null)
+  private var pendingHost = WeakReference<RNUnityHostView>(null)
+  private var player: UnityPlayerAdapter? = null
+  private var playerLifecycleStarted = false
+  private val startPromises = mutableListOf<Promise>()
+  private var unloadPromise: Promise? = null
+  private var pendingStart: Pair<String, Promise>? = null
+  private var defaultDetachedBehavior = "pause"
+  private var unloadTimeout: Runnable? = null
+
+  fun bind(context: ReactApplicationContext, currentActivity: Activity?) = onMain {
+    reactContext = WeakReference(context)
+    if (currentActivity != null) activity = WeakReference(currentActivity)
+  }
+
+  fun updateActivity(value: Activity?) = onMain { activity = WeakReference(value) }
+
+  fun start(detachedBehavior: String, promise: Promise) = onMain {
+    defaultDetachedBehavior = if (detachedBehavior == "keepRunning") "keepRunning" else "pause"
+    when (state) {
+      UnityRuntimeState.IDLE -> startNewGeneration(promise)
+      UnityRuntimeState.STARTING -> startPromises += promise
+      UnityRuntimeState.RUNNING_DETACHED,
+      UnityRuntimeState.RUNNING_ATTACHED,
+      UnityRuntimeState.PAUSED_DETACHED,
+      UnityRuntimeState.PAUSED_ATTACHED -> promise.resolve(null)
+      UnityRuntimeState.UNLOADING -> {
+        pendingStart?.second?.reject("E_UNLOADING", "A newer start request replaced this queued request")
+        pendingStart = defaultDetachedBehavior to promise
+      }
+      UnityRuntimeState.QUITTED -> reject(promise, "E_PROCESS_RESTART_REQUIRED", "Unity has quit in this process")
+      UnityRuntimeState.FAILED -> reject(promise, "E_NATIVE_INVARIANT", "Unity runtime is in a failed state")
+    }
+  }
+
+  private fun startNewGeneration(promise: Promise) {
+    val currentActivity = activity.get()
+    if (currentActivity == null || currentActivity.isFinishing) {
+      reject(promise, "E_NO_ACTIVITY", "A resumed Android Activity is required")
+      return
+    }
+    generation += 1
+    transition(UnityRuntimeState.STARTING)
+    startPromises += promise
+    val callbackGeneration = generation
+    try {
+      player = Unity6000PlayerAdapter(currentActivity, object : IUnityPlayerLifecycleEvents {
+        override fun onUnityPlayerUnloaded() = onMain { completeUnload(callbackGeneration) }
+        override fun onUnityPlayerQuitted() = onMain { completeQuit(callbackGeneration) }
+      })
+      transition(UnityRuntimeState.RUNNING_DETACHED)
+      if (defaultDetachedBehavior == "pause" && pendingHost.get() == null) addPauseReason(PauseReason.NO_HOST)
+      pendingHost.get()?.let { attachNow(it) }
+      startPromises.toList().also { startPromises.clear() }.forEach { it.resolve(null) }
+    } catch (error: Throwable) {
+      fail("E_RUNTIME_START_FAILED", "Unity failed to start", error)
+      startPromises.toList().also { startPromises.clear() }
+        .forEach { it.reject("E_RUNTIME_START_FAILED", error.message, error) }
+    }
+  }
+
+  fun attach(value: RNUnityHostView) = onMain {
+    if (!value.isAttachedToWindow || value.width <= 0 || value.height <= 0) return@onMain
+    val current = host.get()
+    if (current != null && current.hostId != value.hostId) {
+      value.emitError("E_HOST_IN_USE", "Another UnityView is already attached")
+      return@onMain
+    }
+    pendingHost = WeakReference(value)
+    when (state) {
+      UnityRuntimeState.RUNNING_DETACHED,
+      UnityRuntimeState.PAUSED_DETACHED -> attachNow(value)
+      UnityRuntimeState.RUNNING_ATTACHED,
+      UnityRuntimeState.PAUSED_ATTACHED -> if (current == null || current.hostId == value.hostId) attachNow(value)
+      else -> Unit
+    }
+  }
+
+  private fun attachNow(value: RNUnityHostView) {
+    val root = player?.rootView ?: return
+    host = WeakReference(value)
+    pendingHost = WeakReference(null)
+    value.mountUnityView(root)
+    removePauseReason(PauseReason.NO_HOST)
+    transition(if (pauseReasons.isEmpty()) UnityRuntimeState.RUNNING_ATTACHED else UnityRuntimeState.PAUSED_ATTACHED)
+    value.emit("topReady", mapOf("state" to state.wireName, "generation" to generation, "hostId" to value.hostId))
+    val lifecycleGeneration = generation
+    root.post {
+      if (generation != lifecycleGeneration || host.get()?.hostId != value.hostId || playerLifecycleStarted) return@post
+      player?.start()
+      playerLifecycleStarted = true
+      activity.get()?.let { currentActivity ->
+        player?.configurationChanged(currentActivity.resources.configuration)
+      }
+      player?.windowFocusChanged(true)
+      player?.resume()
+      if (pauseReasons.isNotEmpty()) player?.pause()
+      Log.i(TAG, "generation=$generation event=player-lifecycle-started ${player?.viewDiagnostics()}")
+      root.postDelayed({
+        if (generation == lifecycleGeneration) {
+          Log.i(TAG, "generation=$generation event=player-view-settled ${player?.viewDiagnostics()}")
+        }
+      }, 1_000L)
+    }
+  }
+
+  fun detach(hostId: String) = onMain {
+    val current = host.get()
+    if (current?.hostId != hostId) {
+      if (pendingHost.get()?.hostId == hostId) pendingHost = WeakReference(null)
+      return@onMain
+    }
+    current.unmountUnityView(player?.rootView)
+    host = WeakReference(null)
+    if (current.detachedBehavior == "pause") addPauseReason(PauseReason.NO_HOST)
+    transition(if (pauseReasons.isEmpty()) UnityRuntimeState.RUNNING_DETACHED else UnityRuntimeState.PAUSED_DETACHED)
+  }
+
+  fun pause(promise: Promise) = onMain {
+    if (!isRunningOrPaused()) return@onMain reject(promise, "E_RUNTIME_NOT_READY", "Unity is not running")
+    addPauseReason(PauseReason.USER)
+    promise.resolve(null)
+  }
+
+  fun resume(promise: Promise) = onMain {
+    if (!isRunningOrPaused()) return@onMain reject(promise, "E_RUNTIME_NOT_READY", "Unity is not running")
+    removePauseReason(PauseReason.USER)
+    promise.resolve(null)
+  }
+
+  fun setAppBackground(background: Boolean) = onMain {
+    if (!isRunningOrPaused()) return@onMain
+    if (background) addPauseReason(PauseReason.APP_BACKGROUND) else removePauseReason(PauseReason.APP_BACKGROUND)
+  }
+
+  private fun addPauseReason(reason: PauseReason) {
+    val wasRunning = pauseReasons.isEmpty()
+    pauseReasons += reason
+    if (wasRunning && playerLifecycleStarted) player?.pause()
+    syncPausedState()
+  }
+
+  private fun removePauseReason(reason: PauseReason) {
+    if (!pauseReasons.remove(reason)) return
+    if (pauseReasons.isEmpty() && playerLifecycleStarted) player?.resume()
+    syncPausedState()
+  }
+
+  private fun syncPausedState() {
+    if (!isRunningOrPaused()) return
+    val attached = host.get() != null
+    transition(
+      if (pauseReasons.isEmpty()) {
+        if (attached) UnityRuntimeState.RUNNING_ATTACHED else UnityRuntimeState.RUNNING_DETACHED
+      } else {
+        if (attached) UnityRuntimeState.PAUSED_ATTACHED else UnityRuntimeState.PAUSED_DETACHED
+      },
+    )
+  }
+
+  fun unload(promise: Promise) = onMain {
+    when (state) {
+      UnityRuntimeState.IDLE -> promise.resolve(null)
+      UnityRuntimeState.UNLOADING -> reject(promise, "E_UNLOADING", "Unity is already unloading")
+      UnityRuntimeState.QUITTED -> reject(promise, "E_PROCESS_RESTART_REQUIRED", "Unity has quit in this process")
+      UnityRuntimeState.FAILED -> reject(promise, "E_NATIVE_INVARIANT", "Unity runtime is in a failed state")
+      else -> {
+        host.get()?.unmountUnityView(player?.rootView)
+        host = WeakReference(null)
+        pendingHost = WeakReference(null)
+        pauseReasons.clear()
+        transition(UnityRuntimeState.UNLOADING)
+        unloadPromise = promise
+        val timeoutGeneration = generation
+        unloadTimeout = Runnable {
+          if (state == UnityRuntimeState.UNLOADING && generation == timeoutGeneration) {
+            fail("E_UNLOAD_TIMEOUT", "Unity did not report unload completion", null)
+            unloadPromise?.reject("E_UNLOAD_TIMEOUT", "Unity did not report unload completion")
+            unloadPromise = null
+            pendingStart?.second?.reject(
+              "E_PROCESS_RESTART_REQUIRED",
+              "Unity unload timed out; restart the app process before starting Unity again",
+            )
+            pendingStart = null
+          }
+        }.also { main.postDelayed(it, UNLOAD_TIMEOUT_MS) }
+        player?.unload()
+      }
+    }
+  }
+
+  private fun completeUnload(callbackGeneration: Int) {
+    if (state != UnityRuntimeState.UNLOADING || callbackGeneration != generation) return
+    unloadTimeout?.let(main::removeCallbacks)
+    unloadTimeout = null
+    player = null
+    playerLifecycleStarted = false
+    transition(UnityRuntimeState.IDLE)
+    unloadPromise?.resolve(null)
+    unloadPromise = null
+    pendingStart?.also { pendingStart = null; defaultDetachedBehavior = it.first; startNewGeneration(it.second) }
+  }
+
+  private fun completeQuit(callbackGeneration: Int) {
+    if (callbackGeneration != generation) return
+    player = null
+    playerLifecycleStarted = false
+    transition(UnityRuntimeState.QUITTED)
+    unloadPromise?.reject("E_PROCESS_RESTART_REQUIRED", "Unity quit during unload")
+    unloadPromise = null
+    pendingStart?.second?.reject("E_PROCESS_RESTART_REQUIRED", "Unity has quit in this process")
+    pendingStart = null
+  }
+
+  fun sendMessage(gameObject: String, methodName: String, message: String, promise: Promise) = onMain {
+    if (!isRunningOrPaused()) return@onMain reject(promise, "E_RUNTIME_NOT_READY", "Unity cannot receive messages in ${state.wireName}")
+    try {
+      player?.sendMessage(gameObject, methodName, message)
+      promise.resolve(null)
+    } catch (error: Throwable) {
+      reject(promise, "E_NATIVE_INVARIANT", error.message ?: "Unity message failed", error)
+    }
+  }
+
+  fun receiveMessage(message: String) = onMain {
+    val values = mapOf("generation" to generation, "message" to message)
+    emitGlobal("message", values)
+    host.get()?.emit("topMessage", values)
+  }
+
+  fun stateName(): String = state.wireName
+
+  fun diagnostics(): String = JSONObject().apply {
+    put("state", state.wireName)
+    put("generation", generation)
+    host.get()?.let { put("hostId", it.hostId) }
+    put("pauseReasons", JSONArray(pauseReasons.map { it.name }))
+    put("lastTransitionAt", lastTransitionAt)
+    put("lastError", lastError?.let(::JSONObject) ?: JSONObject.NULL)
+    put("unityVersion", "6000.3.x")
+    put("packageVersion", "0.1.0-next.14")
+  }.toString()
+
+  private fun isRunningOrPaused() = state in setOf(
+    UnityRuntimeState.RUNNING_DETACHED, UnityRuntimeState.RUNNING_ATTACHED,
+    UnityRuntimeState.PAUSED_DETACHED, UnityRuntimeState.PAUSED_ATTACHED,
+  )
+
+  private fun transition(next: UnityRuntimeState) {
+    if (state == next) return
+    state = next
+    lastTransitionAt = System.currentTimeMillis()
+    Log.i(TAG, "generation=$generation state=${state.wireName} event=transition")
+    val values = mapOf("state" to state.wireName, "generation" to generation)
+    emitGlobal("stateChange", values)
+    host.get()?.emit("topStateChange", values)
+  }
+
+  private fun fail(code: String, message: String, cause: Throwable?) {
+    transition(UnityRuntimeState.FAILED)
+    lastError = errorValues(code, message, cause)
+    emitGlobal("error", lastError!!)
+    host.get()?.emit("topError", lastError!!)
+    Log.e(TAG, "generation=$generation state=failed code=$code", cause)
+  }
+
+  private fun RNUnityHostView.emitError(code: String, message: String) =
+    emit("topError", errorValues(code, message, null))
+
+  private fun errorValues(code: String, message: String, cause: Throwable?) = mapOf(
+    "code" to code,
+    "message" to message,
+    "state" to state.wireName,
+    "generation" to generation,
+    "nativeCause" to cause?.javaClass?.simpleName,
+  )
+
+  private fun emitGlobal(name: String, values: Map<String, Any?>) {
+    val context = reactContext.get() ?: return
+    if (!context.hasActiveReactInstance()) return
+    val map = Arguments.createMap()
+    values.forEach { (key, value) ->
+      when (value) {
+        null -> map.putNull(key)
+        is String -> map.putString(key, value)
+        is Int -> map.putInt(key, value)
+        is Number -> map.putDouble(key, value.toDouble())
+        is Boolean -> map.putBoolean(key, value)
+      }
+    }
+    context.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+      .emit("RNUnity:$name", map)
+  }
+
+  private fun reject(promise: Promise, code: String, message: String, cause: Throwable? = null) {
+    if (cause == null) promise.reject(code, message) else promise.reject(code, message, cause)
+  }
+
+  private fun onMain(block: () -> Unit) {
+    if (Looper.myLooper() == Looper.getMainLooper()) block() else main.post(block)
+  }
+}