EasyAR Sense Unity Plugin 迁移指南
本文介绍如何从旧版本的 EasyAR Sense Unity Plugin 迁移到新版本。
兼容性说明
从版本 4000 开始，EasyAR Sense Unity Plugin 遵循 Unity 所要求的 包版本控制（使用 Semantic Versioning），兼容性可根据版本号判断。
4.7 是逐步更新版本，任何两个 4.7 版本都不兼容。
4.7 之前的版本，只有第三个版本号表示向后兼容性，前两个版本号的变更均表示不兼容。比如，4.6.2 与 4.6.1 兼容，但 4.6.0 与 4.5.0 不兼容。
警告
修改 tgz 文件或解压后未完整更新整个插件将导致不兼容。
通用迁移指南
迁移到新版本需要先使用 Package Manager window 删除老版本的插件包并添加新的包。
建议按如下步骤操作：
- 关闭使用中的 Unity。
- 删除 Unity 打包应用时生成的平台编译目录。
- 重新打开 Unity 工程，将老版本的 EasyAR Sense Unity Plugin 从工程中移除。
- 导入新版本的 EasyAR Sense Unity Plugin 版本。
注意
插件提供的示例文件并不保证版本间兼容。在插件升级后，导入到工程中的示例有可能无法正常工作，建议删除老版本示例后再操作。
EasyAR 包含原生库文件，如果在删除或替换前执行过库函数（打包时也会调用），这些库文件会被系统锁定无法删除或替换。
重要事项
在删除老版本之前，需要确保没有在编辑器中运行任何场景或打包任何平台的应用。通常建议删除或替换包之前先关闭 Unity，并在重新打开后立即替换。
在使用新版本插件重新打包前，需要先删除 Unity 打包生成的平台编译目录，包括打包 Android 生成的 Gradle 工程目录，以及打包 iOS 生成的 Xcode 目录。
提示
通常这些目录可能在 Unity 工程的 Library 文件夹里面（比如 Library/Bee/Android/Prj/IL2CPP/Gradle），但是不同 Unity 版本有可能不一样。
如果您打包过但找不到对应平台的目录，建议删除整个 Library 文件夹。
如果在迁移之后出现 SchemaHashNotMatched 异常，通常有两种可能
- 前述操作未正确进行导致升级失败或不完整，或是 Unity 生成的编译目录未正确更新（注意：如果未手动删除，大概率会出错）。建议按建议步骤进行操作或使用没有
Library缓存的工程重新编译。 - 手动修改了 EasyAR 的 tgz 文件或解压后未完整更新整个插件。这种情况 EasyAR 无法保证可用性，需要重新下载正确的包并导入。
重要事项
由于 EasyAR Sense 的库文件以及库文件打包后的位置可能会发生变化，如果您保留了 Unity 生成的 Gradle 或 Xcode 工程，必需提前删除所有与 EasyAR 有关的文件，比如 EasyAR.aar ， libEasyAR.so ， easyar.framework 等。
迁移到版本 4003
提示
仅在使用 Mega 时有不兼容改动，其它功能的使用不受影响。
从版本 4002 迁移到 4003 时，除了上述通用迁移指南之外，还需要注意以下内容。
Mega 开发流程变更
在 4003 版本中，Mega 的开发流程发生了较大变化，如果之前使用过 EasyAR Sense Unity Plugin 的其它功能，对这套流程会比较熟悉。
主要变化包括以下内容：
com.easyar.mega包功能变更- 使用 Mega 可以不再导入这个包；但要在编辑器中加载 block 模型以辅助内容摆放时，依旧需要导入。
- 添加了 Mega Block/Landmark support 配置选项：打包前需要开启 。
- 编辑器功能变更
- block mesh 及其它数据加载不再需要 Mega Studio 工具，即使场景中添加了标注工具，也无法用于 Unity 开发。
- MegaBlockController 组件面板直接提供了 block 的编辑器功能，管理更加直接。
- session 验证工具 提供了更多实用的 Mega 控制选项，替代了原先 Mega Studio 中的功能及 MegaTrackerFrameFilter 的编辑器测试区域功能。
- target 行为变更
- EasyAR.Mega.Scene.BlockController 已由 MegaBlockController 替代。MegaBlockController 是 TargetController 的子类，遵循标准 target 行为模式 和适用于 target 的 active 控制策略。
- EasyAR.Mega.Scene.BlockRootController 已删除，block 不再存在根节点，block 各自独立
- MegaBlockController 可以由 ARSessionFactory.CreateController 创建。
从 4002 迁移到 4003 时，重点需要重新组织场景中的 block 物体，替换原先由 Mega Studio 生成的节点组为 MegaBlockController 组件：
- 删除场景中原先由 Mega Studio 生成的节点组，包括
MegaBlocks物体及其下的所有 block 物体。- 如果存在标注节点，也需要删除。
- 如果 block 物体下有内容物体，建议先将内容物体移动到其它节点下，注意保持 local transform 不变。
- 在场景中添加 Mega 跟踪目标。
- 如果原场景中存在多个 block 物体，需要在场景中创建多个 Mega 跟踪目标。
- 将原先 block 物体下的内容物体移动到新创建的 Mega 跟踪目标下，注意保持 local transform 不变。
- 注意配置 MegaBlockController.Source 的 id，该 id 需要与原 block 物体的 id 保持一致，以确保运行时能正确加载。
- 注意配置 MegaBlockController.Tracker 以使用正确的 MegaTrackerFrameFilter。
- 如果原场景中存在标注节点，需要自行创建类似 3D 物体的节点来替代标注节点。
- 如果原工程中存在在脚本中创建 block 的逻辑，需要使用 添加 Mega 跟踪目标 中的方法进行替代。
- 删除
AR Session (EasyAR)子节点Mega Tracker(MegaTrackerFrameFilter) 上的失效脚本。
对于绝大部分使用情况，完成 block 节点的替换后，场景中其它内容无需修改即可正常运行。
接口变更
| 功能模块 | v4002 API | v4003 API | 使用说明 |
|---|---|---|---|
| Mega | MegaTrackerFrameFilter.BlockHolder | MegaBlockController.Tracker | 添加 Mega 跟踪目标 在 block 节点配置加载器替代在 tracker 节点配置加载的 block 根节点。 |
| Mega | MegaTrackerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) | MegaTrackerFrameFilter.SwitchEndPoint | 控制 Mega 跟踪过程 |
| Mega | MegaTrackerFrameFilter.SimulatorLocation | MegaTrackerFrameFilter.SimulatorLocation | |
| Mega | CloudLocalizerFrameFilter.BlockHolder | MegaBlockController.Tracker | 添加 Mega 跟踪目标 在 block 节点配置加载器替代在 tracker 节点配置加载的 block 根节点。 |
| Mega | CloudLocalizerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) | CloudLocalizerFrameFilter.SwitchEndPoint | 控制 Mega 跟踪过程 |
| Mega | CloudLocalizerFrameFilter.SimulatorLocation | CloudLocalizerFrameFilter.SimulatorLocation | |
| Mega | MegaLocalizationResponse.Blocks | MegaLocalizationResponse.Blocks | 控制 Mega 跟踪过程 |
| Mega Support | EasyAR.Mega.Scene.BlockHolder | - | 功能已删除 |
| Mega Support | EasyAR.Mega.Scene.BlockHolder.MultiBlock | - | 功能已删除 |
| Mega Support | EasyAR.Mega.Scene.BlockHolder.BlockRoot | MegaBlockController.Tracker | 添加 Mega 跟踪目标 在 block 节点配置加载器替代在 tracker 节点配置加载的 block 根节点。 |
| Mega Support | EasyAR.Mega.Scene.BlockHolder.BlockRootSourceType | - | 功能已删除 |
| Mega Support | EasyAR.Mega.Scene.BlockHolder.MultiBlockStrategy | - | 功能已删除 |
| Mega Support | EasyAR.Mega.Scene.BlockActiveController | ActiveController | 适用于 target 的 active 控制策略 |
| Mega Support | EasyAR.Mega.Scene.BlockController | MegaBlockController | 添加 Mega 跟踪目标 |
| Mega Support | EasyAR.Mega.Scene.BlockRootController | - | 功能已删除 |
| Mega Support | EasyAR.Mega.Scene.LocalTransform | LocalTransform | |
| Mega Support | EasyAR.Mega.Scene.Location | Location | |
| Mega Support | EasyAR.Mega.Scene.LocationConverter | - | 功能已删除 |
| Mega Support | EasyAR.Mega.Scene.AnnotationNode | - | 功能已删除 |
| Mega Support | EasyAR.Mega.Scene.AnnotationGroup | - | 功能已删除 |
| Mega Support | EasyAR.Mega.Scene.NavPointGraph | - | 功能已删除 |
迁移到版本 4002
从版本 4001 迁移到 4002 时，除了上述通用迁移指南之外，还需要注意以下内容。
接口变更
| 功能模块 | v4001 API | v4002 API | 使用说明 |
|---|---|---|---|
| 辅助功能 | Image.Image(Buffer, PixelFormat, int, int) | Image.create |
迁移到版本 4001
提示
仅在使用 Mega 时有不兼容改动，其它功能的使用不受影响。
从版本 4000 迁移到 4001 时，除了上述通用迁移指南之外，还需要注意以下内容。
接口变更
| 功能模块 | v4000 API | v4001 API | 使用说明 |
|---|---|---|---|
| Mega | MegaTrackerFrameFilter.ResultPoseType.EnableLocalization | MegaTrackerFrameFilter.EnableLocalization | 控制 Mega 跟踪过程 |
| Mega | MegaTrackerFrameFilter.ResultPoseType.EnableStabilization | - | 功能已删除 |
历史版本迁移
从 4000 以前的版本迁移时，需要参考以下内容：