@azesmway/react-native-unity

The plugin that allows you to embed a Unity project into React Native as a full-fledged component. The plugin now supports the new architecture.

Android

Attention! Added support for Unity 2023 and above

Important

For iOS, it is no longer necessary to embed a project created with Unity. Only the built UnityFramework is used. It should be placed in the plugin folder at the path - <YOUR_RN_PROJECT>/unity/builds/ios

Device Support:

Platform	Supported
iOS Simulator	⚠️ optional (see iOS Simulator support)
iOS Device	✅
Android Emulator	✅
Android Device	✅

The iOS Simulator works only with the optional XCFramework export described below; the default device-only UnityFramework.framework does not link on the simulator.

Installation

Install this package in your react-native project:

npm install @azesmway/react-native-unity

or

yarn add @azesmway/react-native-unity

Configure your Unity project:

1. Copy the contents of the folder unity to the root of your Unity project. This folder contains the necessary scripts and settings for the Unity project. You can find these files in your react-native project under node_modules/@azesmway/react-native-unity/unity. This is necessary to ensure iOS has access to the NativeCallProxy class from this library.

2. (optional) If you're following along with the example, you can add the following code to the ButtonBehavior.cs script in your Unity project. This allows the button press in Unity to communicate with your react-native app.

ButtonBehavior.cs

using System;
using System.Collections;
using System.Collections.Generic;
using System.Runtime.InteropServices;
using UnityEngine.UI;
using UnityEngine;

public class NativeAPI {
#if UNITY_IOS && !UNITY_EDITOR
  [DllImport("__Internal")]
  public static extern void sendMessageToMobileApp(string message);
#endif
}

public class ButtonBehavior : MonoBehaviour
{
  public void ButtonPressed()
  {
    if (Application.platform == RuntimePlatform.Android)
    {
      using (AndroidJavaClass jc = new AndroidJavaClass("com.azesmwayreactnativeunity.ReactNativeUnityViewManager"))
      {
        jc.CallStatic("sendMessageToMobileApp", "The button has been tapped!");
      }
    }
    else if (Application.platform == RuntimePlatform.IPhonePlayer)
    {
#if UNITY_IOS && !UNITY_EDITOR
      NativeAPI.sendMessageToMobileApp("The button has been tapped!");
#endif
    }
  }
}

Export iOS Unity Project:

After you've moved the files from the unity folder to your Unity project, you can export the iOS unity project by following these steps:

1. Open your Unity project
2. Build Unity project for ios in ANY folder - just not the main RN project folder!!!
3. Open the created project in XCode
4. Select Data folder and set a checkbox in the "Target Membership" section to "UnityFramework"
5. You need to select the NativeCallProxy.h inside the Unity-iPhone/Libraries/Plugins/iOS folder of the Unity-iPhone project and change UnityFramework’s target membership from Project to Public. Don’t forget this step! (if you don't see these files in your Xcode project, you didn't copy over the unity folder to your Unity project correctly in previous steps)
6. If required - sign the project UnityFramework.framework and build a framework
7. Open the folder with the built framework (by right-clicking) and move it to the plugin folder (<YOUR_RN_PROJECT>/unity/builds/ios)
8. Remove your Pods cache and lockfile with this command in the root of the main RN project rm -rf ios/Pods && rm -f ios/Podfile.lock && npx pod-install

Android

1. Open your Unity project
2. Export Unity app to <YOUR_RN_PROJECT>/unity/builds/android
3. Remove <intent-filter>...</intent-filter> from <YOUR_RN_PROJECT>/unity/builds/android/unityLibrary/src/main/AndroidManifest.xml at unityLibrary to leave only integrated version.

If you're using expo, you're done. The built-in expo plugin will handle the rest. If you're not using expo, you'll need to follow the steps below.

1. Add the following lines to android/settings.gradle:

   include ':unityLibrary'
   project(':unityLibrary').projectDir=new File('..\\unity\\builds\\android\\unityLibrary')

2. Add into android/build.gradle

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

3. Add into android/gradle.properties

   unityStreamingAssets=.unity3d

4. Add strings to android/app/src/main/res/values/strings.xml

   <string name="game_view_content_description">Game view</string>

Android AR (ARCore) permission

If your Unity project uses AR — AR Foundation / ARCore — add this permission to android/app/src/main/AndroidManifest.xml. This applies to expo users too: the config plugin does not add it, so declare it through android.permissions in app.json.

<uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS" />

Since Android 12 (API 31), an app targeting API 31+ needs this permission to read sensors faster than 200 Hz. ARCore requests the IMU at its maximum rate — 500 Hz on many devices — so without it the sensor registration is rejected, the ARCore session never starts and the camera stays black. In logcat it looks like this:

Failed to register sensor to queue 0
...
ArPresto::Moving from ArPrestoStatus 102 to 200
operator(): width <= 0

HIGH_SAMPLING_RATE_SENSORS is a normal permission — it is granted at install time and needs no runtime request. AR Foundation normally merges it in on its own, but in a Unity as a Library setup it often does not reach the host app's manifest, and the failure only shows on devices whose IMU runs above 200 Hz (many Samsung models) — which is why it can look device-specific.

Known issues

• Does not work on the iOS simulator with the default device-only framework. See iOS Simulator support (optional) for the XCFramework workaround.
• On iOS the Unity view is waiting for a parent with dimensions greater than 0 (from RN side). Please take care of this because if it is not the case, your app will crash with the native message MTLTextureDescriptor has width of zero.
• On Android, an ARCore scene fails to start the camera unless the app declares android.permission.HIGH_SAMPLING_RATE_SENSORS. See Android AR (ARCore) permission.
• Unity applies its own fullscreen settings to the Activity it shares with React Native, so opening <UnityView> can hide the system navigation bar for the whole app (immersive sticky mode — the bar reappears on swipe, then hides again). The fullScreen prop only controls the status bar flag; change Fullscreen Mode / Status Bar Hidden in Unity's Player Settings, or set Screen.fullScreen = false in your scene.

Usage

Sample code

import React, { useRef, useEffect } from 'react';

import UnityView from '@azesmway/react-native-unity';
import { View } from 'react-native';

interface IMessage {
  gameObject: string;
  methodName: string;
  message: string;
}

const Unity = () => {
  const unityRef = useRef<UnityView>(null);

  useEffect(() => {
    if (unityRef?.current) {
      const message: IMessage = {
        gameObject: 'gameObject',
        methodName: 'methodName',
        message: 'message',
      };
      unityRef.current.postMessage(
        message.gameObject,
        message.methodName,
        message.message
      );
    }
  }, []);

  return (
    <View style={{ flex: 1 }}>
      <UnityView
        ref={unityRef}
        style={{ flex: 1 }}
        onUnityMessage={(result) => {
          console.log('onUnityMessage', result.nativeEvent.message);
        }}
      />
    </View>
  );
};

export default Unity;

Props

• style: ViewStyle - styles the UnityView. (Won't show on Android without dimensions. Recommended to give it flex: 1 as in the example)
• onUnityMessage?: (event: { nativeEvent: { message: string } }) => void - receives a message from Unity. The payload is available as event.nativeEvent.message
• onPlayerUnload?: (event) => void - fired when the Unity player has been unloaded
• onPlayerQuit?: (event) => void - fired when the Unity player has quit
• androidKeepPlayerMounted?: boolean - if set to true, keep the player mounted even when the view that contains it has lost focus. The player will be paused on blur and resumed on focus. ANDROID ONLY
• fullScreen?: boolean - defaults to true. If set to false, will not request full screen access. ANDROID ONLY

Methods

• postMessage(gameObject, methodName, message) - sends a message to the Unity. FOR IOS: The native method of unity is used to send a message sendMessageToGOWithName:(const char*)goName functionName:(const char*)name message:(const char*)msg;, more details can be found in the documentation
• unloadUnity() - the Unity is unloaded automatically when the react-native component is unmounted, but if you want to unload the Unity, you can call this method
• pauseUnity(pause: boolean) - pause (true) or resume (false) the Unity player
• resumeUnity() - resume the Unity player after it was paused
• windowFocusChanged(hasFocus: boolean = true) - simulate focus change (intended to be used to recover from black screen (not rendering) after remounting Unity view when resumeUnity does not work) ANDROID ONLY

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

iOS Simulator support (optional)

The classic setup vendors a device-only UnityFramework.framework, which is why the support table lists the iOS Simulator as unsupported: simulator builds fail to link the device-arm64 dylib. Unity itself can target the simulator — pack both slices into an XCFramework and the plugin picks it up automatically:

1. In Unity, export the iOS project twice: once with Target SDK: Device SDK and once with Target SDK: Simulator SDK (Player Settings → iOS → Target SDK).
2. Build UnityFramework from each export and create the XCFramework:

xcodebuild -project device-export/Unity-iPhone.xcodeproj -scheme UnityFramework \
  -configuration Release -sdk iphoneos BUILD_DIR="$PWD/device-build" build
xcodebuild -project simulator-export/Unity-iPhone.xcodeproj -scheme UnityFramework \
  -configuration Release -sdk iphonesimulator BUILD_DIR="$PWD/simulator-build" build
xcodebuild -create-xcframework \
  -framework device-build/Release-iphoneos/UnityFramework.framework \
  -framework simulator-build/Release-iphonesimulator/UnityFramework.framework \
  -output <YOUR_RN_PROJECT>/unity/builds/ios/UnityFramework.xcframework

3. Reinstall pods. The App Store build is unaffected: Xcode links only the device slice, so the shipped app size does not change.