# 将 Unity 集成到原生 iOS 应用程序中

> Integrate the Unity Runtime Library into iOS applications.

本页说明如何使用“Unity 用作库”(Unity as a Library) 功能将 Unity 运行时库集成到 iOS 原生应用程序中。

使用此功能可以在原生应用程序中包含 Unity 支持的功能（例如 3D/2D 实时渲染、AR 体验、3D 模型交互或 2D 迷你游戏）。Unity 运行时库提供了多种控件来管理何时以及如何在原生应用程序中加载、激活和卸载内容。

## 工作原理##how-it-works

要将 Unity as a Library 用于 iOS，请先照常从 Unity 构建 Xcode 项目。有关更多信息，请参阅[构建 iOS 应用](/engine/6000.0/manual/platform-specific/iphone/ios-building-and-delivering/build-process.md)程序。

每个 Unity iOS Xcode 项目具有以下[结构](/engine/6000.0/manual/platform-specific/iphone/ios-introducing/structure-of-xcode-project.md)：

* **UnityFramework** 目标中的一个库部分，其中包含源、插件和相关框架。它还会生成 `UnityFramework.framework` 文件。
* **Unity-iPhone** 目标中的一个瘦启动器 (Thin Launcher) 部分，其中包含了应用程序表示数据并会运行该库。**Unity-iPhone** 目标对 **UnityFramework** 目标具有单一依赖关系。

要将 Unity 集成到另一个 Xcode 项目中，必须将两个 Xcode 项目（原生项目和 Unity 生成的项目）合并到一个 Xcode 工作空间中，并将 `UnityFramework.framework` 文件添加到原生 Xcode 项目的**应用程序 (Application)** 目标的**嵌入式二进制文件 (Embedded Binaries)** 部分中。完成此操作后，可以使用 `UnityFramework` 类来控制 Unity 运行时。

此[代码仓库](https://github.com/Unity-Technologies/uaal-example/blob/master/docs/ios.md)包含示例项目和插件（演示如何将 Unity 集成到 Xcode 项目中）以及更多文档。

## UnityFramework 类##unityframework-class

可通过 `UnityFramework` Objective-C 类（该类是 `UnityFramework.framework` 的主体类）的实例来控制 Unity 运行时：

| **方法**                                                                                                         | **描述**                                                                                                                                                                                                                         |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `+ (UnityFramework*)getInstance;`                                                                              | 单例类方法，可将实例返回到 `UnityFramework`。                                                                                                                                                                                                |
| `- (UnityAppController*)appController;`                                                                        | 可返回 `UIApplicationDelegate` 的 `UnityAppController` 子类。这是原生端的根 Unity 类，可以访问应用程序的视图相关对象，例如 `UIView`、`UIViewControllers`、`CADisplayLink` 或 `DisplayConnection`。                                                                   |
| `- (void)setDataBundleId:(const char*)bundleId;`                                                               | 设置捆绑包，Unity 运行时应在其中查找 *Data* 文件夹。有关更多信息，请参阅有关 [Data 文件夹](/engine/6000.0/manual/platform-specific/iphone/ios-introducing/structure-of-xcode-project.md)的文档。请在调用 `runUIApplicationMainWithArgc` 或 `runEmbeddedWithArgc` 之前调用此方法。 |
| `- (void)runUIApplicationMainWithArgc:(int)argc argv:(char*[])argv;`                                           | 从没有其他视图的主要方法中运行 Unity 的默认方式。                                                                                                                                                                                                   |
| `- (void)runEmbeddedWithArgc:(int)argc argv:(char*[])argv appLaunchOpts:(NSDictionary*)appLaunchOpts;`         | 存在其他视图时，如果需要运行 Unity，请调用此方法。                                                                                                                                                                                                   |
| `- (void)unloadApplication;`                                                                                   | 调用此方法可卸载 Unity，并在卸载完成后接收对 `UnityFrameworkListener` 的回调。Unity 将释放占用的大部分内存，但不会全部释放。您将可以再次运行 Unity。                                                                                                                               |
| `- (void)registerFrameworkListener:(id<UnityFrameworkListener>)obj;`                                           | 注册监听器对象，用于接收 UnityFramework 生命周期相关事件的回调。                                                                                                                                                                                       |
| `- (void)unregisterFrameworkListener:(id<UnityFrameworkListener>)obj;`                                         | 取消注册监听器对象。                                                                                                                                                                                                                     |
| `- (void)showUnityWindow;`                                                                                     | 在显示非 Unity 视图时调用此方法，也会显示已经在运行的 Unity 视图。                                                                                                                                                                                       |
| `- (void)pause:(bool)pause;`                                                                                   | 暂停 Unity。                                                                                                                                                                                                                      |
| `- (void)setExecuteHeader:(const MachHeader*)header;`                                                          | 必须在运行 Unity 之前调用此命令，CrashReporter 才能正常工作。                                                                                                                                                                                      |
| `- (void)sendMessageToGOWithName:(const char*)goName functionName:(const char*)name message:(const char*)msg;` | 此方法是 [UnitySendMessage](/engine/6000.0/manual/platform-specific/iphone/ios-developing/plugins-for-ios.md) 的代理。它通过名称查找游戏对象，并使用单字符串消息参数来调用 functionName。                                                                         |
| `(void)quitApplication:(int)exitCode;`                                                                         | 调用此方法可完全卸载 Unity，并在 Unity 退出时接收对 `UnityFrameworkListener` 的回调。Unity 将释放所有内存。\*\*注意：\*\*在此调用之后，无法在同一进程中再次运行 Unity。可以在 `AppController` 上设置 `quitHandler` 以覆盖进程终止默认设置。                                                            |

## 限制##limitations

Unity 不会控制运行时生命周期，因此 Unity as a Library 可能并不适用于所有可能的用例。已知限制包括：

* Unity as a Library 仅支持全屏渲染，不支持在部分屏幕中渲染。

* 您不能加载多个 Unity 运行时实例。

* 您可能需要调整第三方插件（[原生](/engine/6000.0/manual/scripting/compilation-and-code-reload/plug-ins/native.md)和[托管](/engine/6000.0/manual/scripting/compilation-and-code-reload/plug-ins/managed.md)插件）才能使用 Unity 运行时。

* 在原生 iOS 应用程序中使用 Unity as a Library 时，无法通过 [iOS 播放器设置 (iOS Player settings)](/engine/6000.0/manual/platform-specific/iphone/getting-started/class-player-settings-ios.md#Status) 调整设备的状态栏可见性。请考虑使用以下任一方案来实现相同目的：

  * 在项目的 info.plist 文件中设置 [`UIStatusBarHidden`](https://developer.apple.com/documentation/bundleresources/information_property_list/uistatusbarhidden?language=objc) 或 [`UIViewControllerBasedStatusBarAppearance`](https://developer.apple.com/documentation/bundleresources/information_property_list/uiviewcontrollerbasedstatusbarappearance?language=objc) 键。
  * 设置视图控制器属性 [`prefersStatusBarHidden`](https://developer.apple.com/documentation/swiftui/uihostingcontroller/prefersstatusbarhidden/) 并调用 [`setNeedsStatusBarAppearanceUpdate`](https://developer.apple.com/documentation/uikit/uiviewcontroller/1621354-setneedsstatusbarappearanceupdat?language=objc) 方法。
  * 设置视图控制器属性 [`childViewControllerForStatusBarHidden`](https://developer.apple.com/documentation/uikit/uiviewcontroller/1621451-childviewcontrollerforstatusbarh?language=objc)。

***

*