The Unity as a Library feature integrates the Unity Runtime Library into native iOS applications.
You can use this feature to include Unity-powered capabilities, such as 2D and 3D real-time rendering, augmented reality (AR) experiences, 3D model interaction, or 2D mini-games, in your native application. The Unity Runtime Library exposes controls to manage when and how to load, activate, and unload content in your native application.
The following sections describe the Xcode project structure that Unity generates, the methods that control the Unity runtime, and the known limitations of the feature.
To use Unity as a Library for iOS, first build your Xcode project from Unity as you normally would. For more information, refer to Build an iOS application.
Every Unity iOS Objective-C Xcode project has the structure described in Structure of a Unity Xcode Objective-C project type:
UnityFramework/UnityFramework.h), plug-ins, and dependent frameworks. Building this target in Xcode produces the UnityFramework.framework bundle. Unity doesn’t place a prebuilt .framework in the export folder.Note: The Swift Xcode project type doesn’t support Unity as a Library.
To integrate Unity into another Xcode project, combine both Xcode projects (the native one and the one Unity generates) into a single Xcode workspace. Then add the built UnityFramework.framework to Frameworks, Libraries, and Embedded Content (or Embedded Binaries) for your native application’s target. After you do this, you can use the UnityFramework class to control the Unity runtime.
For example projects and plug-ins that demonstrate how to integrate Unity into an Xcode project, refer to the uaal-example repository (Unity Technologies on GitHub).
After you load UnityFramework.framework in the host app, control the Unity runtime through the UnityFramework Objective-C class. The class is declared in UnityFramework/UnityFramework.h and is the principal class of the framework bundle.
The following table lists the methods of the UnityFramework class:
| Method | Description |
|---|---|
+ (UnityFramework*)getInstance; |
Returns the singleton instance of UnityFramework. |
- (UnityAppController*)appController; |
Returns the UnityAppController subclass of UIApplicationDelegate. This is the root Unity class in native code, and can access the app’s view-related objects, such as UIView, UIViewController instances, CADisplayLink, or DisplayConnection. |
- (void)setDataBundleId:(const char*)bundleId; |
Sets the bundle where the Unity runtime looks for the Data folder. Call this method before runUIApplicationMainWithArgc or runEmbeddedWithArgc. For more information, refer to Structure of a Unity Xcode Objective-C project type. |
- (void)runUIApplicationMainWithArgc:(int)argc argv:(char*[])argv; |
Runs Unity from the main method when no other views exist. This is the default way to run Unity. |
- (void)runEmbeddedWithArgc:(int)argc argv:(char*[])argv appLaunchOpts:(NSDictionary*)appLaunchOpts; |
Runs Unity when other views already exist. |
- (void)unloadApplication; |
Unloads Unity and triggers a callback to UnityFrameworkListener after the unload completes. Unity releases most of the memory it occupies, but not all of it. You can run Unity again. |
- (void)registerFrameworkListener:(id<UnityFrameworkListener>)obj; |
Registers a listener object that receives callbacks for UnityFramework lifecycle events. |
- (void)unregisterFrameworkListener:(id<UnityFrameworkListener>)obj; |
Unregisters a listener object. |
- (void)showUnityWindow; |
Shows a Unity view that’s already running, while a non-Unity view is visible. |
- (void)pause:(bool)pause; |
Pauses Unity. |
- (void)setExecuteHeader:(const MachHeader*)header; |
Sets the executable header that CrashReporter uses. Call this method before you run Unity. |
- (void)sendMessageToGOWithName:(const char*)goName functionName:(const char*)name message:(const char*)msg; |
Acts as a proxy to UnitySendMessage. Finds a GameObject by name and calls functionName with a single-string message parameter. For more information, refer to Native plug-in development for iOS. |
- (void)quitApplication:(int)exitCode; |
Unloads Unity completely and triggers a callback to UnityFrameworkListener when Unity quits. Unity releases all memory.Note: You can’t run Unity again in the same process after this call. You can set quitHandler on AppController to override the default process termination. |
Unity doesn’t control the runtime lifecycle, so Unity as a Library might not work in every scenario. Known limitations include:
UIStatusBarHidden or UIViewControllerBasedStatusBarAppearance key in the info.plist file of your project.prefersStatusBarHidden and call the setNeedsStatusBarAppearanceUpdate method.childViewControllerForStatusBarHidden.