@dolami-inc/react-native-expo-unity 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fahrezi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# react-native-expo-unity
+
+Unity as a Library (UaaL) bridge for React Native / Expo.
+
+> ⚠️ **iOS only** — Android support is coming soon.
+
+## Install
+
+```bash
+npm install react-native-expo-unity
+# or
+yarn add react-native-expo-unity
+# or
+bun add react-native-expo-unity
+```
+
+## Quick Start
+
+```tsx
+import { UnityView, type UnityViewRef } from "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");
+```
+
+## API
+
+### `<UnityView />`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onUnityMessage` | `(e: { message: string }) => void` | — | Message from Unity |
+| `autoUnloadOnUnmount` | `boolean` | `true` | Unload Unity when view unmounts. Set `false` to pause only (keeps state). |
+| `style` | `ViewStyle` | — | Must have dimensions (e.g. `flex: 1`) |
+| `ref` | `UnityViewRef` | — | Imperative methods |
+
+### Ref Methods
+
+```tsx
+unityRef.current?.postMessage(gameObject, methodName, message)
+unityRef.current?.pauseUnity()
+unityRef.current?.resumeUnity()
+unityRef.current?.unloadUnity()
+```
+
+### Standalone Functions
+
+Same as ref methods, callable anywhere (operates on the singleton):
+
+```tsx
+import { postMessage, pauseUnity, resumeUnity, unloadUnity, isInitialized } from "react-native-expo-unity";
+```
+
+## Setup
+
+### 1. Unity project — add plugin
+
+Copy the plugin files into your Unity project:
+
+```bash
+# From node_modules after install
+cp node_modules/react-native-expo-unity/plugin/NativeCallProxy.h  <UnityProject>/Assets/Plugins/iOS/
+cp node_modules/react-native-expo-unity/plugin/NativeCallProxy.mm <UnityProject>/Assets/Plugins/iOS/
+```
+
+### 2. Unity project — build iOS
+
+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. Build `UnityFramework` scheme
+
+### 3. Copy build artifacts to your RN project
+
+Create `unity/builds/ios/` in your project root and copy:
+
+```bash
+mkdir -p unity/builds/ios
+cp -R <unity-build>/UnityFramework.framework unity/builds/ios/
+cp <unity-build>/{baselib.a,il2cpp.a,libGameAssembly.a} unity/builds/ios/
+```
+
+> Custom path? Set `EXPO_UNITY_PATH` environment variable to your Unity build directory.
+
+### 4. Add the config plugin to `app.json`
+
+```json
+{
+  "expo": {
+    "plugins": [
+      "react-native-expo-unity"
+    ]
+  }
+}
+```
+
+The plugin automatically configures the required Xcode build settings:
+- `ENABLE_BITCODE = NO` — Unity does not support bitcode
+- `CLANG_CXX_LANGUAGE_STANDARD = c++17` — required for Unity headers
+- `FRAMEWORK_SEARCH_PATHS` — adds the Unity build artifacts directory
+
+If your Unity artifacts are in a custom path, pass the option:
+
+```json
+["react-native-expo-unity", { "unityPath": "/absolute/path/to/unity/builds/ios" }]
+```
+
+### 5. Build
+
+```bash
+expo prebuild --platform ios --clean
+expo run:ios --device
+```
+
+## Lifecycle
+
+Unity is a **singleton** — one instance for the entire app.
+
+| State | Memory | Re-entry |
+|---|---|---|
+| Running | ~200-500MB+ (depends on scene/assets) | Already running |
+| Paused | Same (frozen in memory, no CPU/GPU usage) | `resumeUnity()` — instant, state preserved |
+| Unloaded | ~80-180MB retained (Unity limitation) | Remount `<UnityView />` — ~1-2s reinit, state reset |
+
+### Auto behavior
+
+| Event | What happens |
+|---|---|
+| `<UnityView />` mounts | Unity initializes and starts rendering |
+| `<UnityView />` unmounts | Unity unloads (or pauses if `autoUnloadOnUnmount={false}`) |
+| App → background | Unity pauses |
+| App → foreground | Unity resumes |
+
+### Manual control
+
+Screen focus/blur is **not** automatic — handle with `useFocusEffect`:
+
+```tsx
+useFocusEffect(
+  useCallback(() => {
+    unityRef.current?.resumeUnity();
+    return () => unityRef.current?.pauseUnity();
+  }, [])
+);
+```
+
+## Messaging
+
+### RN → Unity
+
+```tsx
+unityRef.current?.postMessage("GameManager", "LoadAvatar", '{"id":"avatar_01"}');
+```
+
+```csharp
+// Unity C# — on "GameManager" GameObject
+public void LoadAvatar(string json) { /* ... */ }
+```
+
+### Unity → RN
+
+```csharp
+#if UNITY_IOS && !UNITY_EDITOR
+[DllImport("__Internal")]
+private static extern void sendMessageToMobileApp(string message);
+#endif
+
+// Recommended: JSON format
+sendMessageToMobileApp("{\"event\":\"image_taken\",\"data\":{\"path\":\"/tmp/photo.jpg\"}}");
+```
+
+```tsx
+<UnityView onUnityMessage={(e) => {
+  const msg = JSON.parse(e.message);
+  // msg.event, msg.data
+}} />
+```
+
+> See [Messaging Guide](docs/messaging.md) for recommended patterns.
+
+## Docs
+
+- [Lifecycle Deep Dive](docs/lifecycle.md) — navigation scenarios, state management, trade-offs
+- [Messaging Guide](docs/messaging.md) — recommended JSON format, Unity C# + RN examples
+
+## Requirements
+
+- **Expo SDK 54+**
+- **React Native New Architecture** (Fabric) — old architecture not supported
+- **Physical iOS device** — Unity renders only on device; Simulator shows a placeholder view
+- **Unity build artifacts** — must be copied manually into your project (~2GB, not bundled via npm)
+
+## Platform Support
+
+| Platform | Status |
+|---|---|
+| iOS Device | ✅ Supported |
+| iOS Simulator | ⚠️ Not supported — renders a placeholder view |
+| Android | 🚧 Coming soon |
+
+## Limitations
+
+- **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
+
+## License
+
+MIT

package/app.plugin.js

@@ -0,0 +1,82 @@
+// @ts-check
+const { withXcodeProject } = require('@expo/config-plugins');
+
+/**
+ * Expo Config Plugin for react-native-expo-unity.
+ *
+ * Automatically injects the Xcode build settings required for
+ * Unity as a Library (UaaL) to link and run correctly.
+ *
+ * @param {import('@expo/config-plugins').ExpoConfig} config
+ * @param {{ unityPath?: string }} options
+ *   unityPath — path to the Unity iOS build artifacts directory.
+ *   Defaults to `$(PROJECT_DIR)/unity/builds/ios`.
+ *   Can also be set via the EXPO_UNITY_PATH environment variable.
+ */
+const withExpoUnity = (config, options = {}) => {
+  return withXcodeProject(config, (config) => {
+    const xcodeProject = config.modResults;
+
+    const unityPath =
+      options.unityPath ||
+      process.env.EXPO_UNITY_PATH ||
+      '$(PROJECT_DIR)/unity/builds/ios';
+
+    const configurations = xcodeProject.pbxXCBuildConfigurationSection();
+
+    for (const key of Object.keys(configurations)) {
+      const configuration = configurations[key];
+      if (typeof configuration !== 'object' || !configuration.buildSettings) {
+        continue;
+      }
+
+      const settings = configuration.buildSettings;
+
+      // Unity as a Library does not support bitcode.
+      settings['ENABLE_BITCODE'] = 'NO';
+
+      // Unity headers require C++17.
+      settings['CLANG_CXX_LANGUAGE_STANDARD'] = 'c++17';
+
+      // Add the Unity framework directory to the search paths so that
+      // UnityFramework.framework can be found at build time.
+      addFrameworkSearchPath(settings, unityPath);
+    }
+
+    return config;
+  });
+};
+
+/**
+ * Appends `unityPath` to FRAMEWORK_SEARCH_PATHS without duplicating it.
+ *
+ * The xcode npm package stores this setting as either:
+ *   - undefined (not set)
+ *   - a plain string: `"$(inherited)"`
+ *   - a parenthesised list: `("$(inherited)", "/some/path")`
+ *
+ * @param {Record<string, any>} settings
+ * @param {string} unityPath
+ */
+function addFrameworkSearchPath(settings, unityPath) {
+  const quoted = `"${unityPath}"`;
+  const existing = settings['FRAMEWORK_SEARCH_PATHS'];
+
+  if (!existing) {
+    settings['FRAMEWORK_SEARCH_PATHS'] = `(${quoted}, "$(inherited)")`;
+    return;
+  }
+
+  const asStr = String(existing);
+
+  // Already present — nothing to do.
+  if (asStr.includes(unityPath)) {
+    return;
+  }
+
+  // Strip surrounding parens if present, then rebuild.
+  const inner = asStr.replace(/^\(|\)$/g, '').trim();
+  settings['FRAMEWORK_SEARCH_PATHS'] = `(${quoted}, ${inner})`;
+}
+
+module.exports = withExpoUnity;

package/docs/lifecycle.md

@@ -0,0 +1,131 @@
+# Lifecycle Deep Dive
+
+## Unity States
+
+```
+Not Initialized ──mount──→ Running ──pause──→ Paused
+                              ↑                  │
+                              └────resume─────────┘
+                              │
+                           unload
+                              │
+                              ↓
+                          Unloaded ──mount──→ Running (fresh state)
+```
+
+- **Pause/Resume** — cheap, instant, state preserved (avatar, scene, camera position)
+- **Unload** — frees most memory, but ~80-180MB retained by Unity. Next mount = full reinit (~1-2s), state reset.
+
+## Navigation Scenarios
+
+Stack: `Gallery → AR Camera → Add Caption`
+
+### Gallery → AR Camera (push)
+
+| What happens | Detail |
+|---|---|
+| AR Camera mounts | `<UnityView />` renders |
+| Unity initializes | First time: ~1-2s. If paused (not unloaded): instant resume |
+
+### AR Camera → Add Caption (push)
+
+| What happens | Detail |
+|---|---|
+| AR Camera stays mounted | React Navigation keeps stack screens alive |
+| AR Camera loses focus | `useFocusEffect` cleanup fires |
+| You call `pauseUnity()` | Unity freezes, state preserved |
+
+### Add Caption → AR Camera (back)
+
+| What happens | Detail |
+|---|---|
+| AR Camera regains focus | `useFocusEffect` fires |
+| You call `resumeUnity()` | Unity resumes instantly, all state preserved |
+
+### AR Camera → Gallery (back)
+
+| What happens | Detail |
+|---|---|
+| AR Camera unmounts | Component removed from stack |
+| `autoUnloadOnUnmount=true` | Unity unloads, memory freed, state reset |
+| `autoUnloadOnUnmount=false` | Unity pauses only, state preserved, memory stays |
+
+## Patterns
+
+### Pattern A: Fresh state every time
+
+Unity resets when user leaves. Safest, but slower re-entry.
+
+```tsx
+<UnityView
+  ref={unityRef}
+  style={{ flex: 1 }}
+  autoUnloadOnUnmount={true}  // default
+  onUnityMessage={handleMessage}
+/>
+```
+
+```tsx
+useFocusEffect(
+  useCallback(() => {
+    unityRef.current?.resumeUnity();
+    return () => unityRef.current?.pauseUnity();
+  }, [])
+);
+```
+
+### Pattern B: Keep state alive
+
+Unity stays in memory for instant re-entry. Better UX, higher memory.
+
+```tsx
+<UnityView
+  ref={unityRef}
+  style={{ flex: 1 }}
+  autoUnloadOnUnmount={false}  // pause instead of unload
+  onUnityMessage={handleMessage}
+/>
+```
+
+```tsx
+useFocusEffect(
+  useCallback(() => {
+    unityRef.current?.resumeUnity();
+    return () => unityRef.current?.pauseUnity();
+  }, [])
+);
+```
+
+### Pattern C: Force reset on blur
+
+Guarantee fresh state even if the component doesn't unmount.
+
+```tsx
+useFocusEffect(
+  useCallback(() => {
+    unityRef.current?.resumeUnity();
+    return () => unityRef.current?.unloadUnity();  // force unload
+  }, [])
+);
+```
+
+## Memory
+
+| State | Typical memory |
+|---|---|
+| App without Unity | ~100-200MB |
+| Unity running | ~200-500MB+ (depends on scene/assets) |
+| Unity paused | Same as running (frozen in RAM) |
+| Unity unloaded | ~80-180MB retained (Unity limitation) |
+
+**Paused Unity does not use CPU/GPU.** No battery drain. Only concern is memory pressure — iOS may kill your app if system memory is low.
+
+## Auto vs Manual
+
+| Behavior | Handled by | You need to |
+|---|---|---|
+| Initialize on mount | Auto | Nothing |
+| Unload/pause on unmount | Auto (configurable via `autoUnloadOnUnmount`) | Nothing |
+| App background/foreground | Auto (pause/resume) | Nothing |
+| Screen focus/blur | **Manual** | Use `useFocusEffect` |
+| Force unload mid-session | **Manual** | Call `unloadUnity()` |

package/docs/messaging.md

@@ -0,0 +1,117 @@
+# Messaging Guide
+
+The bridge passes raw strings between Unity and React Native. You can use any format, but we recommend **JSON** for consistency.
+
+## Recommended Format
+
+All messages as JSON with `event` + `data`:
+
+```json
+{
+  "event": "event_name",
+  "data": { ... }
+}
+```
+
+### Unity → RN Examples
+
+```json
+{ "event": "unity_ready", "data": {} }
+{ "event": "image_taken", "data": { "path": "/tmp/photo.jpg", "w": 828, "h": 1792 } }
+{ "event": "session_close", "data": { "reason": "user_request" } }
+{ "event": "avatar_loaded", "data": { "id": "avatar_01", "name": "Cat" } }
+{ "event": "error", "data": { "code": "CAMERA_DENIED", "message": "Camera permission denied" } }
+```
+
+### RN → Unity Examples
+
+```json
+{ "event": "load_avatar", "data": { "id": "avatar_01" } }
+{ "event": "set_config", "data": { "quality": "high", "ar_enabled": true } }
+{ "event": "take_photo", "data": {} }
+```
+
+## Unity C# Implementation
+
+```csharp
+using System.Runtime.InteropServices;
+using UnityEngine;
+
+public static class RNBridge
+{
+    #if UNITY_IOS && !UNITY_EDITOR
+    [DllImport("__Internal")]
+    private static extern void sendMessageToMobileApp(string message);
+    #endif
+
+    /// Send a structured event to React Native
+    public static void SendEvent(string eventName, object data = null)
+    {
+        var msg = new EventMessage { @event = eventName, data = data };
+        string json = JsonUtility.ToJson(msg);
+
+        #if UNITY_IOS && !UNITY_EDITOR
+        sendMessageToMobileApp(json);
+        #endif
+    }
+
+    [System.Serializable]
+    private class EventMessage
+    {
+        public string @event;
+        public object data;
+    }
+}
+
+// Usage:
+// RNBridge.SendEvent("unity_ready");
+// RNBridge.SendEvent("image_taken", new { path = "/tmp/photo.jpg", w = 828, h = 1792 });
+```
+
+## React Native Implementation
+
+```tsx
+import { UnityView } from "react-native-expo-unity";
+
+interface UnityEvent<T = unknown> {
+  event: string;
+  data: T;
+}
+
+function parseUnityMessage<T = unknown>(raw: string): UnityEvent<T> | null {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    console.warn("[Unity] Invalid message:", raw);
+    return null;
+  }
+}
+
+// Usage:
+<UnityView
+  onUnityMessage={(e) => {
+    const msg = parseUnityMessage(e.message);
+    if (!msg) return;
+
+    switch (msg.event) {
+      case "unity_ready":
+        console.log("Unity is ready");
+        break;
+      case "image_taken":
+        handleImageTaken(msg.data as { path: string; w: number; h: number });
+        break;
+      case "error":
+        handleError(msg.data as { code: string; message: string });
+        break;
+    }
+  }}
+/>
+```
+
+## Why JSON?
+
+- Consistent structure for all messages
+- Easy to parse on both sides
+- Type-safe with interfaces/classes
+- Extensible — add fields without breaking existing handlers
+- Debuggable — readable in logs

package/expo-module.config.json

@@ -0,0 +1,7 @@
+{
+  "platforms": ["ios"],
+  "ios": {
+    "modules": ["ExpoUnityModule"],
+    "appDelegateSubscribers": ["ExpoUnityAppDelegateSubscriber"]
+  }
+}

package/ios/ExpoUnity.podspec

@@ -0,0 +1,52 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+# Resolve the Unity build artifacts directory.
+# By default, looks for `unity/builds/ios/` in the app's project root.
+# Override with EXPO_UNITY_PATH environment variable.
+unity_ios_dir = ENV['EXPO_UNITY_PATH'] || File.join(Pod::Config.instance.project_root.to_s, 'unity', 'builds', 'ios')
+
+Pod::Spec.new do |s|
+  s.name           = 'ExpoUnity'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.description    = package['description']
+  s.license        = package['license']
+  s.author         = package['author']
+  s.homepage       = package['homepage']
+  s.platforms      = { :ios => '15.1' }
+  s.source         = { :git => package['repository']['url'], :tag => "v#{s.version}" }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  s.source_files = '**/*.{h,m,mm,swift}'
+  s.exclude_files = 'UnityFramework.framework/**/*'
+
+  # Copy Unity build artifacts from the app's project into the pod at install time
+  s.prepare_command = <<-CMD
+    if [ -d "#{unity_ios_dir}" ]; then
+      cp -R "#{unity_ios_dir}/UnityFramework.framework" . 2>/dev/null || true
+    fi
+  CMD
+
+  # Link UnityFramework if present
+  if File.exist?(File.join(unity_ios_dir, 'UnityFramework.framework'))
+    s.vendored_frameworks = 'UnityFramework.framework'
+  end
+
+  s.pod_target_xcconfig = {
+    'HEADER_SEARCH_PATHS' => [
+      '"${PODS_TARGET_SRCROOT}/UnityFramework.framework/Headers"',
+      "\"#{unity_ios_dir}/UnityFramework.framework/Headers\""
+    ].join(' '),
+    'CLANG_CXX_LANGUAGE_STANDARD' => 'c++17',
+    'GCC_PREPROCESSOR_DEFINITIONS' => 'UNITY_FRAMEWORK=1',
+    'ENABLE_BITCODE' => 'NO'
+  }
+
+  s.user_target_xcconfig = {
+    'ENABLE_BITCODE' => 'NO'
+  }
+end

package/ios/ExpoUnityAppDelegateSubscriber.swift

@@ -0,0 +1,36 @@
+import ExpoModulesCore
+import UIKit
+
+// Handles app lifecycle events for Unity
+// Auto pause/resume when app goes to background/foreground
+public class ExpoUnityAppDelegateSubscriber: ExpoAppDelegateSubscriber {
+  // Track if Unity was running before going to background
+  // so we don't resume if it was already paused by the developer
+  private static var wasRunningBeforeBackground = false
+
+  public func applicationWillResignActive(_ application: UIApplication) {
+    let bridge = UnityBridge.shared()
+    if bridge.isInitialized() {
+      ExpoUnityAppDelegateSubscriber.wasRunningBeforeBackground = true
+      bridge.pause(true)
+      NSLog("[ExpoUnity] Auto-paused (app entering background)")
+    } else {
+      ExpoUnityAppDelegateSubscriber.wasRunningBeforeBackground = false
+    }
+  }
+
+  public func applicationDidBecomeActive(_ application: UIApplication) {
+    if ExpoUnityAppDelegateSubscriber.wasRunningBeforeBackground {
+      UnityBridge.shared().pause(false)
+      ExpoUnityAppDelegateSubscriber.wasRunningBeforeBackground = false
+      NSLog("[ExpoUnity] Auto-resumed (app entering foreground)")
+    }
+  }
+
+  public func applicationWillTerminate(_ application: UIApplication) {
+    if UnityBridge.shared().isInitialized() {
+      UnityBridge.shared().unload()
+      NSLog("[ExpoUnity] Auto-unloaded (app terminating)")
+    }
+  }
+}

package/ios/ExpoUnityModule.swift

@@ -0,0 +1,39 @@
+import ExpoModulesCore
+
+public class ExpoUnityModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("ExpoUnity")
+
+    // Send a message from RN to Unity
+    Function("postMessage") { (gameObject: String, methodName: String, message: String) in
+      UnityBridge.shared().sendMessage(gameObject, methodName: methodName, message: message)
+    }
+
+    // Pause / resume Unity
+    Function("pauseUnity") { (pause: Bool) in
+      UnityBridge.shared().pause(pause)
+    }
+
+    // Unload Unity (free memory)
+    Function("unloadUnity") {
+      UnityBridge.shared().unload()
+    }
+
+    // Check if Unity is initialized
+    Function("isInitialized") { () -> Bool in
+      return UnityBridge.shared().isInitialized()
+    }
+
+    // Event sent from Unity → RN
+    Events("onUnityMessage")
+
+    // The native Unity view
+    View(ExpoUnityView.self) {
+      Events("onUnityMessage")
+
+      Prop("autoUnloadOnUnmount") { (view: ExpoUnityView, value: Bool) in
+        view.autoUnloadOnUnmount = value
+      }
+    }
+  }
+}

package/ios/ExpoUnityView.swift

@@ -0,0 +1,115 @@
+import ExpoModulesCore
+import UIKit
+
+class ExpoUnityView: ExpoView {
+  private let onUnityMessage = EventDispatcher()
+  var autoUnloadOnUnmount: Bool = true
+
+  required init(appContext: AppContext? = nil) {
+    super.init(appContext: appContext)
+
+    #if targetEnvironment(simulator)
+    setupSimulatorPlaceholder()
+    #else
+    DispatchQueue.main.async { [weak self] in
+      self?.setupUnity()
+    }
+    #endif
+  }
+
+  required init?(coder: NSCoder) {
+    fatalError("init(coder:) has not been implemented")
+  }
+
+  // MARK: - Simulator
+
+  #if targetEnvironment(simulator)
+  private func setupSimulatorPlaceholder() {
+    backgroundColor = .black
+
+    let label = UILabel()
+    label.text = "Unity is not available\non iOS Simulator"
+    label.textAlignment = .center
+    label.numberOfLines = 0
+    label.textColor = UIColor(white: 0.6, alpha: 1)
+    label.font = .systemFont(ofSize: 14)
+    label.translatesAutoresizingMaskIntoConstraints = false
+    addSubview(label)
+
+    NSLayoutConstraint.activate([
+      label.centerXAnchor.constraint(equalTo: centerXAnchor),
+      label.centerYAnchor.constraint(equalTo: centerYAnchor),
+      label.leadingAnchor.constraint(greaterThanOrEqualTo: leadingAnchor, constant: 16),
+      label.trailingAnchor.constraint(lessThanOrEqualTo: trailingAnchor, constant: -16),
+    ])
+  }
+  #endif
+
+  // MARK: - Device
+
+  #if !targetEnvironment(simulator)
+  private func setupUnity() {
+    let bridge = UnityBridge.shared()
+
+    if !bridge.isInitialized() {
+      bridge.initialize()
+    }
+
+    bridge.onMessage = { [weak self] message in
+      DispatchQueue.main.async {
+        self?.onUnityMessage([
+          "message": message
+        ])
+      }
+    }
+
+    mountUnityView()
+  }
+
+  private func mountUnityView() {
+    guard let unityView = UnityBridge.shared().unityRootView() else {
+      NSLog("[ExpoUnity] Unity root view not available yet")
+      return
+    }
+
+    if let unityWindow = UnityBridge.shared().unityWindow() {
+      if let myWindow = self.window, unityWindow != myWindow {
+        unityWindow.isHidden = true
+        unityWindow.isUserInteractionEnabled = false
+        myWindow.makeKeyAndVisible()
+      }
+    }
+
+    unityView.frame = self.bounds
+    if unityView.superview != self {
+      self.addSubview(unityView)
+    }
+  }
+
+  override func layoutSubviews() {
+    super.layoutSubviews()
+
+    if let unityView = UnityBridge.shared().unityRootView(),
+       unityView.superview == self {
+      unityView.frame = self.bounds
+    } else {
+      mountUnityView()
+    }
+  }
+
+  override func removeFromSuperview() {
+    let bridge = UnityBridge.shared()
+    bridge.onMessage = nil
+
+    if autoUnloadOnUnmount && bridge.isInitialized() {
+      bridge.unload()
+      NSLog("[ExpoUnity] Auto-unloaded (view removed from superview)")
+    } else if !autoUnloadOnUnmount && bridge.isInitialized() {
+      bridge.pause(true)
+      NSLog("[ExpoUnity] Auto-paused on unmount (autoUnloadOnUnmount=false)")
+    }
+
+    super.removeFromSuperview()
+  }
+  #endif
+}

package/ios/UnityBridge.h

@@ -0,0 +1,26 @@
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+typedef void (^UnityMessageCallback)(NSString * _Nonnull message);
+
+@interface UnityBridge : NSObject
+
+@property (nonatomic, copy, nullable) UnityMessageCallback onMessage;
+
++ (instancetype)shared;
+
+- (BOOL)isInitialized;
+- (void)initialize;
+- (void)sendMessage:(NSString *)gameObject
+         methodName:(NSString *)methodName
+            message:(NSString *)message;
+- (void)pause:(BOOL)pause;
+- (void)unload;
+- (nullable UIView *)unityRootView;
+- (nullable UIWindow *)unityWindow;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/UnityBridge.mm

@@ -0,0 +1,180 @@
+#import "UnityBridge.h"
+
+// ------------------------------------------------------------------
+// UnityBridge — singleton that owns the UnityFramework lifecycle.
+// Called from Swift via @objc interop.
+//
+// On Simulator, all methods are no-ops because Unity as a Library
+// does not support the iOS Simulator target.
+// ------------------------------------------------------------------
+
+#if TARGET_OS_SIMULATOR
+
+// MARK: - Simulator stubs
+
+@implementation UnityBridge
+
+static UnityBridge *_shared = nil;
+
++ (instancetype)shared {
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        _shared = [[UnityBridge alloc] init];
+    });
+    return _shared;
+}
+
+- (BOOL)isInitialized { return NO; }
+- (void)initialize { NSLog(@"[ExpoUnity] Unity is not available on iOS Simulator"); }
+- (nullable UIView *)unityRootView { return nil; }
+- (nullable UIWindow *)unityWindow { return nil; }
+- (void)sendMessage:(NSString *)gameObject methodName:(NSString *)methodName message:(NSString *)message {}
+- (void)pause:(BOOL)pause {}
+- (void)unload {}
+
+@end
+
+#else // !TARGET_OS_SIMULATOR
+
+// MARK: - Device implementation
+
+#import <UnityFramework/UnityFramework.h>
+#import <UnityFramework/NativeCallProxy.h>
+
+#ifdef DEBUG
+#include <mach-o/ldsyms.h>
+#endif
+
+@interface UnityBridge () <NativeCallsProtocol, UnityFrameworkListener>
+
+@property (nonatomic, strong, nullable) UnityFramework *ufwInternal;
+
+@end
+
+@implementation UnityBridge
+
+static UnityBridge *_shared = nil;
+
++ (instancetype)shared {
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        _shared = [[UnityBridge alloc] init];
+    });
+    return _shared;
+}
+
+- (BOOL)isInitialized {
+    return self.ufwInternal != nil && [self.ufwInternal appController] != nil;
+}
+
+- (void)initialize {
+    if ([self isInitialized]) return;
+
+    NSString *bundlePath = [[NSBundle mainBundle] bundlePath];
+    bundlePath = [bundlePath stringByAppendingString:@"/Frameworks/UnityFramework.framework"];
+
+    NSBundle *bundle = [NSBundle bundleWithPath:bundlePath];
+    if (![bundle isLoaded]) [bundle load];
+
+    UnityFramework *ufw = [bundle.principalClass getInstance];
+    if (![ufw appController]) {
+#ifdef DEBUG
+        [ufw setExecuteHeader:&_mh_dylib_header];
+#else
+        [ufw setExecuteHeader:&_mh_execute_header];
+#endif
+    }
+
+    [ufw setDataBundleId:[bundle.bundleIdentifier cStringUsingEncoding:NSUTF8StringEncoding]];
+
+    // Boot Unity
+    NSArray *args = [[NSProcessInfo processInfo] arguments];
+    int argc = (int)args.count;
+    char **argv = (char **)malloc((argc + 1) * sizeof(char *));
+    for (int i = 0; i < argc; i++) {
+        argv[i] = strdup([args[i] UTF8String]);
+    }
+    argv[argc] = NULL;
+
+    [ufw runEmbeddedWithArgc:1 argv:argv appLaunchOpts:nil];
+    [ufw appController].quitHandler = ^{ NSLog(@"[ExpoUnity] Unity quit handler called"); };
+
+    // Register for callbacks
+    [ufw registerFrameworkListener:self];
+    [NSClassFromString(@"FrameworkLibAPI") registerAPIforNativeCalls:self];
+
+    self.ufwInternal = ufw;
+
+    // Hide Unity's window — we embed its rootView in our own view
+    UIWindow *unityWindow = [ufw appController].window;
+    if (unityWindow) {
+        unityWindow.hidden = YES;
+        unityWindow.userInteractionEnabled = NO;
+    }
+
+    NSLog(@"[ExpoUnity] Unity initialized");
+}
+
+- (nullable UIView *)unityRootView {
+    if (![self isInitialized]) return nil;
+    return [self.ufwInternal appController].rootView;
+}
+
+- (nullable UIWindow *)unityWindow {
+    if (![self isInitialized]) return nil;
+    return [self.ufwInternal appController].window;
+}
+
+- (void)sendMessage:(NSString *)gameObject
+         methodName:(NSString *)methodName
+            message:(NSString *)message {
+    if (![self isInitialized]) return;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        [self.ufwInternal sendMessageToGOWithName:[gameObject UTF8String]
+                             functionName:[methodName UTF8String]
+                                  message:[message UTF8String]];
+    });
+}
+
+- (void)pause:(BOOL)pause {
+    if (![self isInitialized]) return;
+    dispatch_async(dispatch_get_main_queue(), ^{
+        [self.ufwInternal pause:pause];
+    });
+}
+
+- (void)unload {
+    NSLog(@"[ExpoUnity] unload called, isInitialized=%d", [self isInitialized]);
+    if (![self isInitialized]) return;
+    UIWindow *mainWindow = [[[UIApplication sharedApplication] delegate] window];
+    if (mainWindow) [mainWindow makeKeyAndVisible];
+    [self.ufwInternal unloadApplication];
+    NSLog(@"[ExpoUnity] unloadApplication called");
+}
+
+// MARK: - NativeCallsProtocol (Unity → RN)
+
+- (void)sendMessageToMobileApp:(NSString *)message {
+    if (self.onMessage) {
+        self.onMessage(message);
+    }
+}
+
+// MARK: - UnityFrameworkListener
+
+- (void)unityDidUnload:(NSNotification *)notification {
+    NSLog(@"[ExpoUnity] unityDidUnload notification received");
+    [self.ufwInternal unregisterFrameworkListener:self];
+    self.ufwInternal = nil;
+    NSLog(@"[ExpoUnity] ufwInternal set to nil, ready for re-initialize");
+}
+
+- (void)unityDidQuit:(NSNotification *)notification {
+    NSLog(@"[ExpoUnity] Unity did quit");
+    [self.ufwInternal unregisterFrameworkListener:self];
+    self.ufwInternal = nil;
+}
+
+@end
+
+#endif // !TARGET_OS_SIMULATOR

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@dolami-inc/react-native-expo-unity",
+  "version": "0.1.1",
+  "description": "Unity as a Library (UaaL) bridge for React Native / Expo",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "plugin": "./app.plugin.js",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf build"
+  },
+  "files": [
+    "src/",
+    "ios/",
+    "plugin/",
+    "docs/",
+    "app.plugin.js",
+    "expo-module.config.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fahreziadh/react-native-expo-unity.git"
+  },
+  "keywords": [
+    "expo",
+    "react-native",
+    "unity",
+    "unity-as-a-library",
+    "uaal",
+    "bridge",
+    "ar"
+  ],
+  "author": "Fahrezi <fahrezi@dolami.is>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/fahreziadh/react-native-expo-unity/issues"
+  },
+  "homepage": "https://github.com/fahreziadh/react-native-expo-unity#readme",
+  "peerDependencies": {
+    "expo": ">=54.0.0",
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@types/react": "~19.1.10",
+    "expo-module-scripts": "~4.0.0",
+    "typescript": "~5.8.0"
+  }
+}

package/plugin/NativeCallProxy.h

@@ -0,0 +1,15 @@
+#import <Foundation/Foundation.h>
+
+@protocol NativeCallsProtocol
+@required
+
+- (void) sendMessageToMobileApp:(NSString*)message;
+
+@end
+
+__attribute__ ((visibility("default")))
+@interface FrameworkLibAPI : NSObject
+
++(void) registerAPIforNativeCalls:(id<NativeCallsProtocol>) aApi;
+
+@end

package/plugin/NativeCallProxy.mm

@@ -0,0 +1,20 @@
+#import <Foundation/Foundation.h>
+#import "NativeCallProxy.h"
+
+@implementation FrameworkLibAPI
+
+id<NativeCallsProtocol> api = NULL;
++(void) registerAPIforNativeCalls:(id<NativeCallsProtocol>) aApi
+{
+    api = aApi;
+}
+
+@end
+
+extern "C"
+{
+    void sendMessageToMobileApp(const char* message)
+    {
+        return [api sendMessageToMobileApp:[NSString stringWithUTF8String:message]];
+    }
+}

package/src/ExpoUnity.ts

@@ -0,0 +1,43 @@
+import { requireNativeModule } from "expo";
+
+const ExpoUnityModule = requireNativeModule("ExpoUnity");
+
+/**
+ * Send a message to a Unity GameObject.
+ */
+export function postMessage(
+  gameObject: string,
+  methodName: string,
+  message: string
+): void {
+  ExpoUnityModule.postMessage(gameObject, methodName, message);
+}
+
+/**
+ * Pause Unity rendering and execution.
+ */
+export function pauseUnity(): void {
+  ExpoUnityModule.pauseUnity(true);
+}
+
+/**
+ * Resume Unity rendering and execution.
+ */
+export function resumeUnity(): void {
+  ExpoUnityModule.pauseUnity(false);
+}
+
+/**
+ * Unload Unity and free memory.
+ * After this, Unity must be re-initialized (remount the view).
+ */
+export function unloadUnity(): void {
+  ExpoUnityModule.unloadUnity();
+}
+
+/**
+ * Check if Unity is currently initialized.
+ */
+export function isInitialized(): boolean {
+  return ExpoUnityModule.isInitialized();
+}

package/src/UnityView.tsx

@@ -0,0 +1,56 @@
+import { requireNativeView } from "expo";
+import { forwardRef, useImperativeHandle, useCallback, useRef } from "react";
+import type { ViewProps } from "react-native";
+import type { UnityMessageEvent } from "./types";
+import { postMessage, pauseUnity, resumeUnity, unloadUnity } from "./ExpoUnity";
+
+// Native view from Expo Modules
+const NativeUnityView = requireNativeView("ExpoUnity");
+
+export interface UnityViewProps extends ViewProps {
+  onUnityMessage?: (event: UnityMessageEvent) => void;
+  /**
+   * If true (default), Unity will automatically unload when the view unmounts.
+   * If false, Unity will only pause on unmount — state is preserved for faster re-mount.
+   * Use false when users frequently navigate back and forth to the Unity screen.
+   */
+  autoUnloadOnUnmount?: boolean;
+}
+
+export interface UnityViewRef {
+  postMessage: (gameObject: string, methodName: string, message: string) => void;
+  pauseUnity: () => void;
+  resumeUnity: () => void;
+  unloadUnity: () => void;
+}
+
+export const UnityView = forwardRef<UnityViewRef, UnityViewProps>(
+  ({ onUnityMessage, autoUnloadOnUnmount = true, ...props }, ref) => {
+    const nativeRef = useRef(null);
+
+    useImperativeHandle(ref, () => ({
+      postMessage,
+      pauseUnity,
+      resumeUnity,
+      unloadUnity,
+    }));
+
+    const handleUnityMessage = useCallback(
+      (event: { nativeEvent: UnityMessageEvent }) => {
+        onUnityMessage?.(event.nativeEvent);
+      },
+      [onUnityMessage]
+    );
+
+    return (
+      <NativeUnityView
+        ref={nativeRef}
+        onUnityMessage={handleUnityMessage}
+        autoUnloadOnUnmount={autoUnloadOnUnmount}
+        {...props}
+      />
+    );
+  }
+);
+
+UnityView.displayName = "UnityView";

package/src/index.ts

@@ -0,0 +1,4 @@
+export { UnityView } from "./UnityView";
+export type { UnityViewRef, UnityViewProps } from "./UnityView";
+export { postMessage, pauseUnity, resumeUnity, unloadUnity, isInitialized } from "./ExpoUnity";
+export type { UnityMessageEvent } from "./types";

package/src/types.ts

@@ -0,0 +1,3 @@
+export interface UnityMessageEvent {
+  message: string;
+}