Unity as a Library on iOS and tvOS

Understand how the Unity as a Library feature embeds the Unity Runtime Library in a native iOS and tvOS application.

阅读时间7 分钟

最后更新于 19 天前

The Unity as a Library feature integrates the Unity Runtime Library into native iOS and tvOS 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. Both iOS and tvOS share the same project structure and integration workflow.

The following sections describe how to integrate Unity as a Library with the Objective-C and Swift Xcode project types, the methods that control the Unity runtime, and the known limitations of the feature.

Objective-C Xcode project structure

To use Unity as a Library for iOS and tvOS, first build your Xcode project from Unity as you normally would. For more information, refer to Build an iOS application.

Every Unity iOS and tvOS 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.

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).

Objective-C 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.

Swift Xcode project structure

Every Unity iOS and tvOS Swift Xcode project has the structure described in Structure of a Unity Xcode Swift project type:

A library part in the UnityFramework target that contains plug-ins and dependent frameworks. Building this target produces the
```
UnityFramework.framework
```
bundle. The UnityFramework target links the UnityAPI target.
A public API part in the UnityAPI target that produces the
```
UnityAPI.framework
```
static framework. It contains the trampoline source code and exposes the public
```
UnityAPI
```
module, including the
```
UnityPlayer
```
API and
```
UnityPluginInterface
```
headers, to native plug-ins. This target doesn't exist in the Objective-C project type.
A thin launcher part in the Unity-iPhone target that includes app representation data and runs the library. Unlike the Objective-C project type,
```
UnityFramework.framework
```
is linked with the main binary. The entry point is
```
MainApp/MainApp.swift
```
instead of
```
main.mm
```
. The Unity-iPhone target has a single dependency on the UnityFramework target.

The

.xcodeproj

file name matches the Unity project name (sanitized), not the hardcoded

Unity-iPhone.xcodeproj

used in the Objective-C project type.

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

UnityPlayer

class from the

UnityAPI

framework to control the Unity runtime.

To access the API, import

UnityAPI

at the top of your source file:


import UnityAPI

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).

Swift methods to control the Unity runtime

After you add the Unity Xcode project to your workspace and link

UnityFramework.framework

into your host app, control the Unity runtime through

UnityPlayer.shared

Method	Description
`UnityPlayer.shared`	Returns the singleton instance of `UnityPlayer` .
`setDataBundleId(_ bundleId: String)`	Sets the bundle where the Unity runtime looks for the `Data` folder. Call this method before `startEngine()` . Use this when the Unity content is embedded inside a framework bundle rather than the main app bundle.
`startEngine()`	Starts the Unity engine. On first call, initializes the runtime and loads the first scene. After `unload()` , reloads the scene and resumes rendering.
`unload()`	Unloads Unity and posts `UnityNotifications.unityDidUnload` . Unity releases most of the memory it occupies, but not all of it. You can restart Unity by calling `startEngine()` .
`quit(exitCode: Int32 = 0)`	Quits Unity completely and posts `UnityNotifications.unityDidQuit` . Unity releases all memory. You can't run Unity again in the same process after this call. By default, the process terminates after quit. Set `terminatesOnQuit` to `false` to keep the process alive.
`terminatesOnQuit: Bool`	Controls whether `quit()` terminates the process. Defaults to `true` . Set to `false` when you use Unity as a Library so the host app can continue running after Unity quits.
`pause()`	Pauses the Unity Player.
`resume()`	Resumes the Unity Player.
`isPaused() -> Bool`	Returns whether the Unity Player is paused.
`renderingView: UIView?`	Returns the view that Unity renders to.
`rootViewController: UIViewController?`	Returns the root view controller of the window that displays the Unity view.
`sendMessage(toGameObject:method:argument:)`	Sends a message to a C# script on a GameObject. Equivalent to `UnitySendMessage` .

Lifecycle notifications

Subscribe to

NotificationCenter

notifications to react to Unity lifecycle events:

```
UnityNotifications.unityDidUnload
```
: Unity posts this notification when
```
unload()
```
completes. Use it to update the UI of your host application.
```
UnityNotifications.unityDidQuit
```
: Unity posts this notification when
```
quit()
```
completes.

For the full list of available notifications, refer to Listen for lifecycle events.

Limitations

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

Unity as a Library supports only full-screen rendering, not rendering to part of the screen.
You can't load more than one instance of the Unity runtime.
You might need to adapt third-party plug-ins (both native and managed) to work with the Unity runtime.
(iOS only) You can't adjust the device's status bar visibility through the iOS Player settings when you use Unity as a Library in a native iOS application. To hide the status bar, use one of the following options:
- Set the
```
UIStatusBarHidden
```
  or
```
UIViewControllerBasedStatusBarAppearance
```
  key in the
```
info.plist
```
  file of your project.
- Set the view controller property
```
prefersStatusBarHidden
```
  and call the
```
setNeedsStatusBarAppearanceUpdate
```
  method.
- Set the view controller property
```
childViewControllerForStatusBarHidden
```
  .

Unity Engine

User Manual

Script Reference