专栏

本专栏将介绍如何使用这个支持热更的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(…)”)

Settings修改

使用ARFoundation

  1. 导入 “AR Foundation”和“ARCore Extensions for AR Foundation ”。

建议使用《使用插件一键安装》介绍的插件一键导入 ARCore的所有依赖。
此外,也可参考官方文档《AR Foundation 使用入门》按照步骤逐步导入。

  1. 转到 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)

示意图如下:

Player Settings修改

Player Settings修改

  1. 转到 Edit > Project Settings 以打开 Project Settings 窗口,点击XR Plug-in Management,启用ARCore。
Settings修改
  1. 转到ARCore,修改为深度可选的AR必备应用。
Settings修改

配置HybridCLR

  1. 检查HybridCLR Installer的状态

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

  1. 转到 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以上版本。

Player Settings修改

  • 关闭代码裁剪

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

Player Settings修改

  1. 划分程序集

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

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

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

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

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

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

  1. 配置热更新程序集

注意:如果把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”两个程序集作为热更的程序集,则可参考下面的操作截图。

Settings修改

  1. 生成AOT dll

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

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

  2. 补充元数据

    在执行上一步操作后,生成的裁剪后的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
Logo

欢迎加入西安开发者社区!我们致力于为西安地区的开发者提供学习、合作和成长的机会。参与我们的活动,与专家分享最新技术趋势,解决挑战,探索创新。加入我们,共同打造技术社区!

更多推荐