Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Unity as a Library on iOS

Understand how the Unity as a Library feature embeds the Unity Runtime Library in a native iOS application.
Read time 4 minutesLast updated 4 days ago
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.

Xcode project structure and integration

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:
  • A library part in the UnityFramework target that contains source files (such as 
    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.
  • A thin launcher part in the Unity-iPhone target that includes app representation data and runs the library. The Unity-iPhone target has a single dependency on the UnityFramework target.
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).

Methods to control the Unity runtime

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.

Limitations

Unity doesn't control the runtime lifecycle, so Unity as a Library might not work in every scenario. Known limitations include:

Additional resources