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 以前的版本遷移時，需要參考以下內容：