【热更新】使用HybridCLR实现MR场景的热更新

title: 实现MR场景的热更新
date: 2023-08-24
update：2024-03-20

实现MR场景的热更新

需求描述

TA制作资源场景，场景+C#脚本打包后，直接可在程序中替换数据，不需要再次打包应用程序。

功能实现

实现方式简述

• 通过Unity的AssetsBundle的方式，实现资源的导入导出
• 通过“HybridCLR”实现C#脚本的热更
• 通过数据清单记录热更文件和入口场景信息

数据检查

通过"获取版本文件 -> 比对版本信息 -> 读取数据清单 -> 下载数据"几个步骤更新数据。

数据加密

由于unity打的ab包可通过诸如AssetsStudioGUI这类插件打开和提取，HybridCLR生成的热更DLL是未混淆的，因此需要对数据进行加密。

开发步骤

以下几步将描述如何实现MR眼镜加载热更场景。

前提条件

使用Holo当前版本的sdk

注：
为Xvisio B50R构建热更场景需要引入XVisio SDK
为ARCore构建热更场景需额外按ARCore官方文档配置环境

配置环境

• 通过 “Assets”->"Import Package"导入 holo sdk。
• 配置热更工具
• 按需导入Xvisio SDK 或ARCore

安装 HybridCLR

• 执行菜单栏"Holo-XR"->“HotUpdate”->"Import HybridCLR"选项

待菜单栏出现“HybridCLR”后，表示导入成功。若未出现，重启Unity编辑器即可。

• 执行"HybridCLR"-> “Installer”

当状态值变为True时，表示安装成功

配置ARCore依赖

若是使用Xvisio SDK 则直接跳过

1、安装AR Foundation

AR Foundation 软件包提供了一个供 Unity 开发者使用的接口，但其本身并不实现任何 AR 功能。如需在目标设备上使用 AR Foundation，您还需要安装单独的软件包，并为每个平台启用相应的插件。

​ “Package Manager”中搜"AR Foundation"，之后“install”

2、安装 ARCore XR Plugin

借助 ARCore XR 插件软件包，您可以构建适用于 Android 设备的增强现实应用。如果您的应用以 Android 设备为目标平台，请按照以下步骤在 Unity 项目中安装该 SDK。使用与 AR Foundation 软件包相同的版本，以免出现任何兼容性问题。

​ “Package Manager”中搜"ARCore XR Plugin"，之后“install”

3、前往 Edit > Project Settings。在 XR Plug-in Management 中，打开 Android 标签页并启用 ARCore。

4、配置Player Settings

• 在“Other Settings”->Graphics APIs中 只保留 “OpenGLES3”，ARCore不支持Vulkan

• 设置Configuration，Min API 。用ARCore 时此处设置为大于等于24。
• 关闭增量GC，设置后台脚本为IL2CPP

当前"HybridCLR"仅商业版支持增量GC，社区版将在2023年8月28日支持增量GC。

Api Compatability Level 切换为 .Net 4.x(Unity 2019-2020) 或 .Net Framework（Unity 2021+）

• 设置写入权限

• 关闭代码裁减 Other Settings -> Optimization -> Strip Engine Code

若是启用代码裁剪，则需要 参考文档 按需配置补充元数据。

配置Xvisio SDK

1、导入"xvisio_xxxxxx.unitypackage"。

2、配置Player Settings

• 若是为Xvisio设备构建热更场景，需按如下配置Resolution and Presentation，其它平台按平台对应的文档配置

• 在“Other Settings”->Graphics APIs中 只保留 “OpenGLES3”

• 设置Configuration，Min API，按不同的AR平台设置，此处针对XVisio B50R应该设置为API 25。
• 关闭增量GC，设置后台脚本为IL2CPP

当前"HybridCLR"仅商业版支持增量GC，社区版将在2023年8月28日支持增量GC。

Api Compatability Level 切换为 .Net 4.x(Unity 2019-2020) 或 .Net Framework（Unity 2021+）

• 设置写入权限

• 关闭代码裁减 Other Settings -> Optimization -> Strip Engine Code

若是启用代码裁剪，则需要 参考文档 按需配置补充元数据。

设置Holo-Settings

执行“Holo-XR”->“Setting”，启用热更选项，选择XR平台

划分程序集

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

常见的拆分方式有几种：

• Assembly-CSharp作为AOT程序集。剩余代码自己拆分为N个AOT程序集和M个热更新程序集。
• Assembly-CSharp作为热更新程序集。剩余代码自己拆分为N个AOT程序集和M个热更新程序集。

无论哪种拆分方式，正确设置好程序集之间的引用关系即可。请不要在AOT程序集中引用热更新程序集，这会导致打包出错。

如果 你们项目把Assembly-CSharp作为AOT程序集，强烈建议关闭热更新程序集的auto reference选项。

因为Assembly-CSharp是最顶层assembly，它会自动引用剩余所有assembly，很容易就出现失误引用热更新程序集的情况。

实现主体程序

以开发XVisio为例，其它平台区别不大。

构建场景

• 通过菜单栏选项，快速创建XVisio的默认组件

需要注意的是：若使用ARCore XR Plugin，则需要在主体程序的场景中添加“AR Session”对象，且该对象的“ attemptUpdate”属性为true。

attemptUpdate
If the device supports XR but does not have the necessary software, some platforms allow prompting the user to install or update the software. If attemptUpdate is true, a software update will be attempted. If the appropriate software is not installed or out of date, and attemptUpdate is false, then AR will not be available.

层级菜单中新增如下内容：

• 新建空对象，添加DataDownLoader组件，并设置数据路径

• 通过菜单栏选项，创建DllLoader对象

• 设置DataDownLoader事件，当资源下载完成后执行DllLoader对象的StartReadData方法

打包程序

AOT编译

​ HybridCLR -> generate -> All

优化的打包流程

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

打包apk

注：由于还无热更内容，此程序启动后并不会进入AR场景。

制作热更场景

以XVisio为例，构造支持CSLAM的热更场景

创建热更程序集

一般来说，必须将热更新代码独立为assembly，才能方便地进行热更新。

• 创建热更程序集“hotfix”

• 在HybridCLR Settings中配置热更Assembly Definitions

• 若是需要将“Assembly-CSharp”也作为热更内容，则需要在“热更新dlls->Hot Update Assembiles”中添加

Assembly-CSharp

编写测试脚本

• 创建热更脚本，需确保脚本位置在“hotfix”程序集中

注意事项

• 热更程序集“hotfix”中的脚本是无法依赖Unity预定义程序集（如：Assembly-CSharp）。
• 热更程序集“hotfix”可依赖Dll，因此可将原Assembly-CSharp中的代码编译成DLL。
• 热更程序集“hotfix”可通过反射机制访问Assembly-CSharp中的类与方法。
• Assembly-CSharp是Unity的默认全局程序集，它也可以像普通dll一样当作热更新程序集。

更多信息请参考HybridCLR文档

添加场景资源

• XVisio可使用CSLAM功能，通过菜单栏选项“Holo-XR”->“XVisio Config”->"Import MapLoader"创建CSLAM地图加载对象。

在路径栏填入服务器上的homap数据全路径

• 在场景中添加资源（模型、粒子特效等），将所有AR场景中要显示的内容资源都拖至“Holo XR World”->"SceneNode"节点下

场景打包

• 在Build Settings中添加要导出的场景

• 执行菜单栏“Holo-XR”->“BuildBundle-Android”，指定入口场景后，点击”导出“

入口场景：即主体程序在读取热更数据后，首先进入的场景。

上传数据包

• 场景打包的结果为zip包和version文件

• 将数据上传至服务器即可，注意：当前版本服务器保存解压后的数据（zip需解压）

运行程序

Editor运行

在unity中运行时，输出日志如下：

真机运行

• 启动主体程序，程序会自动进行版本校验和数据下载。
• 进入场景后，MR眼镜端的投屏截图如下：