Unity as a Library (UaaL) bridge for React Native / Expo.

npm install @dolami-inc/react-native-expo-unity
# or
yarn add @dolami-inc/react-native-expo-unity
# or
bun add @dolami-inc/react-native-expo-unity

import { UnityView, type UnityViewRef } from "@dolami-inc/react-native-expo-unity";

const unityRef = useRef<UnityViewRef>(null);

<UnityView
  ref={unityRef}
  style={{ flex: 1 }}
  onUnityMessage={(e) => console.log(e.message)}
/>

// Send message to Unity
unityRef.current?.postMessage("GameObject", "Method", "payload");

unityRef.current?.postMessage(gameObject, methodName, message)
unityRef.current?.pauseUnity()
unityRef.current?.resumeUnity()
unityRef.current?.unloadUnity()

Same as ref methods, callable anywhere (operates on the singleton):

import { postMessage, pauseUnity, resumeUnity, unloadUnity, isInitialized } from "@dolami-inc/react-native-expo-unity";

Copy the platform bridge files into your Unity project:

iOS:

# From node_modules after install
cp node_modules/@dolami-inc/react-native-expo-unity/plugin/NativeCallProxy.h  <UnityProject>/Assets/Plugins/iOS/
cp node_modules/@dolami-inc/react-native-expo-unity/plugin/NativeCallProxy.mm <UnityProject>/Assets/Plugins/iOS/

Android:

No plugin files need to be copied — the NativeCallProxy Java class ships with the module and is available at runtime automatically. Your Unity C# code calls it via AndroidJavaClass (see Messaging Guide).

1. Unity → File → Build Settings → iOS → Build
2. Open generated Xcode project
3. Select NativeCallProxy.h in Libraries/Plugins/iOS/
4. Set Target Membership → UnityFramework → Public
5. Select the Data folder in the Project Navigator
6. In the right panel under Target Membership, check UnityFramework

   This is critical. Without this, the Data folder (which contains global-metadata.dat and all Unity assets) will NOT be included inside UnityFramework.framework. The app will crash at launch with: Could not open .../global-metadata.dat — IL2CPP initialization failed

7. Build UnityFramework scheme

1. Unity → File → Build Settings → Android
2. Check Export Project (do not "Build" directly — you need the Gradle project)
3. Set Scripting Backend to IL2CPP
4. Set Target Architectures: ARMv7 and ARM64
5. Click Export and save to a directory (e.g. unity/builds/android)

Create unity/builds/ios/ in your project root and copy the built framework and static libraries:

mkdir -p unity/builds/ios

# Copy the compiled framework (should already contain Data/ inside after step 2.6)
cp -R <xcode-build-output>/UnityFramework.framework unity/builds/ios/

# Copy static libraries from the Unity Xcode project root
cp <unity-xcode-project>/*.a unity/builds/ios/

Verify that Data/ exists inside the framework:

ls unity/builds/ios/UnityFramework.framework/Data
# Should show: Managed/  Resources/  etc.

The podspec references these files directly by path — nothing is copied or embedded into the npm package. Updating your Unity build is as simple as replacing the contents of unity/builds/ios/ and re-running pod install.

Custom path? Set EXPO_UNITY_PATH environment variable pointing to your Unity build directory, or pass unityPath to the config plugin (see step 4).

The Unity export directory (containing the unityLibrary folder) should be at unity/builds/android/ in your project root. The config plugin will automatically include the :unityLibrary Gradle module.

# Verify the structure
ls unity/builds/android/unityLibrary
# Should show: libs/  src/  build.gradle  etc.

Custom path? Set EXPO_UNITY_ANDROID_PATH environment variable, or pass androidUnityPath to the config plugin.

{
  "expo": {
    "plugins": [
      "@dolami-inc/react-native-expo-unity"
    ]
  }
}

The plugin automatically configures:

iOS:

• ENABLE_BITCODE = NO — Unity does not support bitcode
• CLANG_CXX_LANGUAGE_STANDARD = c++17 — required for Unity headers
• Embeds UnityFramework.framework via a build script phase

Android:

• Includes :unityLibrary module in settings.gradle
• Adds flatDir repository for Unity's native libs
• Adds ndk.abiFilters for armeabi-v7a and arm64-v8a

If your Unity artifacts are in custom paths:

["@dolami-inc/react-native-expo-unity", {
  "unityPath": "/absolute/path/to/unity/builds/ios",
  "androidUnityPath": "/absolute/path/to/unity/builds/android"
}]

# iOS
expo prebuild --platform ios --clean
expo run:ios --device

# Android
expo prebuild --platform android --clean
expo run:android

Unity is a singleton — one instance for the entire app.

Screen focus/blur is not automatic — handle with useFocusEffect:

useFocusEffect(
  useCallback(() => {
    unityRef.current?.resumeUnity();
    return () => unityRef.current?.pauseUnity();
  }, [])
);

unityRef.current?.postMessage("GameManager", "LoadAvatar", '{"id":"avatar_01"}');

// Unity C# — on "GameManager" GameObject
public void LoadAvatar(string json) { /* ... */ }

// iOS — uses extern "C" DllImport
#if UNITY_IOS && !UNITY_EDITOR
[DllImport("__Internal")]
private static extern void sendMessageToMobileApp(string message);
#endif

// Android — uses AndroidJavaClass
private static void SendToMobile(string message) {
#if UNITY_IOS && !UNITY_EDITOR
    sendMessageToMobileApp(message);
#elif UNITY_ANDROID && !UNITY_EDITOR
    using (var proxy = new AndroidJavaClass("com.expounity.bridge.NativeCallProxy")) {
        proxy.CallStatic("sendMessageToMobileApp", message);
    }
#endif
}

// Usage:
SendToMobile("{\"event\":\"image_taken\",\"data\":{\"path\":\"/tmp/photo.jpg\"}}");

<UnityView onUnityMessage={(e) => {
  const msg = JSON.parse(e.message);
  // msg.event, msg.data
}} />

See Messaging Guide for recommended patterns.

• Lifecycle Deep Dive — navigation scenarios, state management, trade-offs
• Messaging Guide — recommended JSON format, Unity C# + RN examples

• Expo SDK 54+
• React Native New Architecture (Fabric) — old architecture not supported
• Physical device — iOS: Unity renders only on device, Simulator shows a placeholder. Android: physical device or emulator with ARM support.
• Unity build artifacts — must be exported/copied manually into your project (not bundled via npm)

• Single instance — only one Unity view at a time, cannot run multiple
• Full-screen rendering only — Unity renders full-screen within its view (Unity limitation)
• Memory retention — after unloadUnity(), Unity retains 80-180MB in memory (Unity limitation)
• No reload after quit — if Unity calls Application.Quit() on iOS, it cannot be restarted without restarting the app
• No hot reload — native code changes require a full rebuild

MIT