三、配置带HybridCLR的ARCore开发环境

预告

本专栏将介绍如何使用这个支持热更的AR开发插件，快速地开发AR应用。

专栏： Unity开发AR系列

插件简介

通过热更技术实现动态地加载AR场景，简化了AR开发流程，让用户可更多地关注Unity场景内容的制作。

"EnvInstaller..."支持HybridCLR和ARCore的一键安装。

"AR SDK..."基于HybridCLR和ARFoundation实现，使热更技术贯穿AR开发的全流程。

包含热更数据制作与导出、热更数据上传与下载、热更数据的版本控制与数据加载

资源下载

"EnvInstaller"：点击下载

"AR SDK"：点击下载

配置AR开发环境

在前面的《使用插件一键安装》已介绍如何使用插件导入ARFoundation（ARCore）和HybridCLR的相关Package，这里仅介绍必须修改的设置。

导入AR SDK

1. 通过"Assets -> Import Package -> Custom Package..."的方式导入 "AR SDK_v1.0.1.x.unitypackage"。导入成功后，菜单栏出现"Holo-XR"栏目。

2. 点击"Holo-XR > Settings"，打开设置窗口。

   • （必需）勾选"热更新"启用SDK中涉及HybridCLR的脚本。

   • （必需）勾选"ARCore"，启用ARFoundation。（此处由于通过EnvInstaller安装的是ARCore，因此这里选用ARCore。目前也支持启用其它平台，将在后续文档中讲述。）

   • （可选）勾选"调试模式"和"打印日志"（勾选后，使用"EqLog.log(...)"）

使用ARFoundation

1. 导入 "AR Foundation"和"ARCore Extensions for AR Foundation "。

建议使用《使用插件一键安装》介绍的插件一键导入 ARCore的所有依赖。

此外，也可参考官方文档《AR Foundation 使用入门》按照步骤逐步导入。

2. 转到 File > Build Settings 以打开 Build Settings 窗口，点击 Player Settings，修改3处地方。

Player Settings > ...	值
Other Settings > Rendering	取消选中 Auto Graphics API 。 如果 Vulkan 列在 Graphics APIs 下，请将其移除，因为 ARCore 尚不支持 Vulkan。
Other Settings > Minimum API Level	这里要构建 AR 必备应用，请指定 Android 7.0 'Nougat' (API Level 24) or higher
Other Settings > Scripting Backend	选择 IL2CPP （而非 Mono ），Level切换为 .NET Framework(而非**.Net Standard 2.x**)。（注意：Unity 2020及其以下版本，切换为.NET 4.x）

示意图如下：

3. 转到 Edit > Project Settings 以打开 Project Settings 窗口，点击XR Plug-in Management，启用ARCore。

4. 转到ARCore，修改为深度可选的AR必备应用。

配置HybridCLR

1. 检查HybridCLR Installer的状态

通过菜单栏 > HybridCLR > Installer...，打开HybridCLR Installer窗口，检查Installed的状态值是否为True。若为False，则点击Install按钮。

2. 转到 File > Build Settings 以打开 Build Settings 窗口，点击 Player Settings，修改如下内容。这是使用HybridCLR所必需的。

HybridCLR同样需要修改为IL2CPP和切换为 .Net 4.x(Unity 2019-2020) 或 .Net Framework（Unity 2021+），由于上节内容已修改，这里不再重复。

• 关闭增量GC

此前"HybridCLR"仅商业版支持增量GC，现在社区版已在2023年8月28日支持增量GC。若不关闭增量GC，则需要替换HybridCLR4.0以上版本。

• 关闭代码裁剪

若要启用代码裁剪，则需补充元数据（此处关闭代码裁剪，可避免很多方法找不到的异常问题。若不关闭，则需要针对缺失的内容补充元数据）。

3. 划分程序集

请阅读文档配置程序集了解如何配置程序集。

划分程序集：

项目代码必须合理拆分为AOT（即编译到游戏主包内）程序集 和 热更新程序集，才能进行热更新。HybridCLR对于 怎么拆分程序集并无任何限制，甚至可以把第三方工程中的代码作为热更新程序集。一般来说，游戏刚启动时，至少需要一个AOT程序集来负责启动及热更新相关工作。

这里以AR SDK中的示例为例，AR SDK中包含如下程序集定义

程序集	类型	简介
Holo.Demo	热更程序集	包含各单项功能示例的程序集，示例Demo中使用
DynamicScene	热更程序集	AR动态场景示例的程序集，示例Demo中使用
Holo.Runtime	AOT程序集	AR SDK核心程序集，已编译成dll并添加至项目中。
Assembly-CSharp	AOT/热更都可	Unity的默认全局程序集

Assembly-CSharp是Unity默认的程序集，这里可做AOT程序集，也可做热更程序集。

若要自定义热更数据集，则可通过"Assets > Create > Assembly Definition"的方式创建程序集。

4. 配置热更新程序集

注意：如果把Assembly-CSharp作为AOT程序集，强烈建议关闭热更新程序集的auto reference选项。因为Assembly-CSharp是最顶层assembly，它会自动引用剩余所有assembly。

当确定要使用哪些程序集作为热更程序集后，那么需要在HybridCLR Settings中，将这些程序集添加至"hotUpdateAssemblyDefinitions"或"hotUpdateAssemblies"。

操作步骤：

• 点击菜单 "HybridCLR > Settings" 打开配置界面。
• 将Assembly Definition(asmdef)方式定义的程序集，加入hotUpdateAssemblyDefinitions
• 将普通dll或"Assembly-CSharp"加入hotUpdateAssemblies（不需要'.dll'后缀）

注意事项：

• hotUpdateAssemblyDefinitions和hotUpdateAssemblies列表是等价的，不要重复添加，否则会报错。
• 如果热更新程序集是已经编译好的dll（无论放在Assets下还是其他目录），必须同时在 HybridCLR/Settings的外部dll搜索路径中配置它的搜索路径。 搜索路径为相对路径，相对于项目根目录（也就是Assets的父目录）。

参考示例：

• 这里将"Holo.Demo"和"DynamicScene"两个程序集作为热更的程序集，则可参考下面的操作截图。

5. 生成AOT dll

   • 运行菜单 HybridCLR/Generate/All 一键执行必要的生成操作

   这里只需要执行"Genrate > All"即可，若需了解更多，请参考<<HybridCLR 打包工作流>>。

6. 补充元数据

   在执行上一步操作后，生成的裁剪后的AOT dll可以用于补充元数据。HybridCLR插件会自动把它们复制到{project}/HybridCLRData/AssembliesPostIl2CppStrip/{target}。

   注意，不同BuildTarget的裁剪AOT dll不可复用。

   打开"Assets/HybridCLRGenerate/AOTGenericReferences.cs"文件，查看需要补充的元数据。

   using System.Collections.Generic;
   public class AOTGenericReferences : UnityEngine.MonoBehaviour
   {
   
       // {{ AOT assemblies
       public static readonly IReadOnlyList<string> PatchedAOTAssemblyList = new List<string>
       {
   		"UnityEngine.AndroidJNIModule.dll",
   		"UnityEngine.CoreModule.dll",
   		"mscorlib.dll",
       };
   }

   可见，需要补充的dll有以下3个。

    "UnityEngine.AndroidJNIModule.dll",
    "UnityEngine.CoreModule.dll",
    "mscorlib.dll",
   

   打开HybridCLR Settings，在"Patch AOT Assemblies"中添加。

   

注意：

补充元数据没有加载顺序的要求。这里使用的是HybridCLR社区版本，补充元数据加载后，大约会占用6倍dll大小的内存，而且这些内存无法回收。若对内存有较高的要求，需要使用HybridCLR商业版本的完全泛型共享技术，不再需要补充元数据，节省这部分内存。请转至 HybridCLR文档《基于补充元数据的泛型函数实例化技术》

---

至此环境已搭建完成，后续将结合示例讲述如何实现一个AR程序。

---

补充说明

AR Foundation注意事项

内置渲染管线和通用渲染管线都与 AR Foundation 软件包兼容，但 URP 需要额外的步骤进行配置。

参考文档《AR Foundation 使用入门》

HybridCLR技巧

• 优化打包流程

  HybridCLR/Generate/All 命令运行过程中会执行一次导出工程，以生成裁剪后的AOT dll。这一步对于大型项目来说可能非常耗时，几乎将打包时间增加了一倍。如果需要优化打包时间，可以按照如下流程一次出包。

  • 运行 HybridCLR/Generate/LinkXml
  • 导出工程
  • 运行 HybridCLR/Generate/Il2cppDef
  • 运行 HybridCLR/Generate/MethodBridge生成桥接函数
  • 运行 HybridCLR/Generate/PReverseInvokeWrapper。 不需要与lua之类交互的项目可跳过此步。
  • 将 {proj}\HybridCLRData\LocalIl2CppData-{platform}\il2cpp\libil2cpp\hybridclr\generated目录 替换导出工程中的此目录。
  • 在导出工程上执行build