Руководство по миграции 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-файла или неполное обновление всего plugin после распаковки приведет к несовместимости.
Общий guide по миграции
Чтобы перейти на новую версию, сначала удалите старый пакет plugin через Package Manager window и добавьте новый пакет.
Рекомендуется выполнить следующие шаги:
- Закройте используемый Unity.
- Удалите директорию platform build, созданную Unity при сборке приложения.
- Снова откройте Unity project и удалите из него старую версию EasyAR Sense Unity Plugin.
- Импортируйте новую версию EasyAR Sense Unity Plugin.
Примечание
Примерные файлы, поставляемые с plugin, не гарантируют совместимость между версиями. После обновления plugin импортированные в project примеры могут перестать работать. Рекомендуется удалить примеры старой версии и только потом продолжать.
EasyAR включает native library files. Если эти files уже использовались до удаления или замены, система заблокирует их и удалить или заменить их будет невозможно.
Важно
Перед удалением старой версии убедитесь, что в editor не запущена ни одна scene и не выполняется сборка приложения для какой-либо platform. Обычно рекомендуется сначала закрыть Unity, удалить или заменить package, а затем сразу заменить его после повторного открытия.
Перед повторной сборкой с новой версией plugin сначала удалите platform build directories, созданные Unity, включая директорию Gradle для Android и директорию Xcode для iOS.
Совет
Обычно эти директории находятся в папке Library Unity project, например Library/Bee/Android/Prj/IL2CPP/Gradle, но в разных версиях Unity они могут отличаться.
Если вы уже собирали проект, но не можете найти соответствующую platform directory, рекомендуется удалить всю папку Library.
Если после миграции появляется exception SchemaHashNotMatched, обычно возможны две причины:
- Предыдущие шаги были выполнены неправильно, поэтому обновление прошло неудачно или неполностью, либо build directories, созданные Unity, не были обновлены корректно. Если их не удалять вручную, ошибка возникает с большой вероятностью. Рекомендуется следовать указанным шагам или пересобрать project без cache
Library. - Tgz-файл EasyAR был изменен вручную или весь plugin не был обновлен полностью после распаковки. В этом случае EasyAR не может гарантировать корректную работу, поэтому необходимо заново скачать правильный пакет и импортировать его.
Важно
Поскольку файлы library EasyAR Sense и их расположение после сборки могут изменяться, если вы сохраняете Unity-generated проект Gradle или Xcode, нужно заранее удалить все файлы EasyAR, например EasyAR.aar, libEasyAR.so, easyar.framework и так далее.
Миграция на версию 4003
Совет
Только при использовании Mega есть несовместимые изменения; использование других функций не затрагивается.
При миграции с версии 4002 на 4003, помимо общего guide по миграции выше, нужно также учитывать следующее.
Изменение workflow разработки Mega
В версии 4003 workflow разработки Mega сильно изменился. Если вы уже использовали другие функции EasyAR Sense Unity Plugin, этот workflow будет вам знаком.
Основные изменения:
- Изменения возможностей пакета
com.easyar.mega- Для использования Mega этот пакет больше не нужно обязательно импортировать; но чтобы загружать block model в editor для помощи с размещением контента, он по-прежнему нужен.
- Добавлена опция конфигурации Mega Block/Landmark support: включите перед сборкой.
- Изменения editor-функций
- Загрузка block mesh и других данных больше не требует tool Mega Studio, и даже если в scene добавлен tool аннотаций, он не может использоваться для Unity development.
- Панель компонента MegaBlockController напрямую предоставляет editor-функции для block, что делает управление более прямым.
- session verification tool предоставляет больше полезных Mega control options, заменяя прежние функции Mega Studio и testing area editor в MegaTrackerFrameFilter.
- Изменения поведения target
- EasyAR.Mega.Scene.BlockController заменен на MegaBlockController. MegaBlockController является подклассом TargetController, следует стандартному target behavior mode и active control strategy, применимым к target.
- EasyAR.Mega.Scene.BlockRootController удален, у block больше нет root node, и каждый block независим.
- MegaBlockController можно создать через ARSessionFactory.CreateController.
При миграции с 4002 на 4003 самое важное — перестроить block objects в scene и заменить группировку node, ранее создаваемую Mega Studio, на компонент MegaBlockController:
- Удалите в scene прежнюю группу node, созданную Mega Studio, включая объект
MegaBlocksи все block objects под ним.- Если есть annotation nodes, их тоже нужно удалить.
- Если у block object есть content objects, рекомендуется сначала перенести content objects под другие nodes и сохранить local transform без изменений.
- Добавьте target tracking Mega в scene.
- Если в исходной scene было несколько block objects, нужно создать несколько Mega target tracking objects.
- Перенесите content objects из-под старых block objects под новые Mega target tracking objects и сохраните local transform без изменений.
- Обратите внимание на настройку id в MegaBlockController.Source; id должен совпадать с id исходного block object, чтобы runtime мог загрузить его правильно.
- Обратите внимание на настройку MegaBlockController.Tracker, чтобы использовать правильный MegaTrackerFrameFilter.
- Если в исходной scene были annotation nodes, нужно вручную создать похожие nodes вместо них.
- Если в исходном project была логика создания block в script, используйте вместо нее метод из Добавление target tracking Mega.
- Удалите неактуальный script у дочернего node
Mega Tracker(MegaTrackerFrameFilter) подAR Session (EasyAR).
Для большинства случаев после замены block node остальной content scene можно не менять, и он будет работать нормально.
Изменения API
| Модуль | v4002 API | v4003 API | Описание |
|---|---|---|---|
| Mega | MegaTrackerFrameFilter.BlockHolder | MegaBlockController.Tracker | Добавление target tracking Mega На block node loader настраивается вместо block root, который раньше настраивался на tracker node. |
| Mega | MegaTrackerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) | MegaTrackerFrameFilter.SwitchEndPoint | Управление процессом tracking Mega |
| Mega | MegaTrackerFrameFilter.SimulatorLocation | MegaTrackerFrameFilter.SimulatorLocation | |
| Mega | CloudLocalizerFrameFilter.BlockHolder | MegaBlockController.Tracker | Добавление target tracking Mega На block node loader настраивается вместо block root, который раньше настраивался на tracker node. |
| Mega | CloudLocalizerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) | CloudLocalizerFrameFilter.SwitchEndPoint | Управление процессом tracking Mega |
| Mega | CloudLocalizerFrameFilter.SimulatorLocation | CloudLocalizerFrameFilter.SimulatorLocation | |
| Mega | MegaLocalizationResponse.Blocks | MegaLocalizationResponse.Blocks | Управление процессом tracking Mega |
| Mega Support | EasyAR.Mega.Scene.BlockHolder | - | Функция удалена |
| Mega Support | EasyAR.Mega.Scene.BlockHolder.MultiBlock | - | Функция удалена |
| Mega Support | EasyAR.Mega.Scene.BlockHolder.BlockRoot | MegaBlockController.Tracker | Добавление target tracking Mega На block node loader настраивается вместо block root, который раньше настраивался на tracker node. |
| Mega Support | EasyAR.Mega.Scene.BlockHolder.BlockRootSourceType | - | Функция удалена |
| Mega Support | EasyAR.Mega.Scene.BlockHolder.MultiBlockStrategy | - | Функция удалена |
| Mega Support | EasyAR.Mega.Scene.BlockActiveController | ActiveController | Стратегия active control для target |
| Mega Support | EasyAR.Mega.Scene.BlockController | MegaBlockController | Добавление target tracking 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, помимо общего guide по миграции выше, нужно также учитывать следующее.
Изменения API
| Модуль | v4001 API | v4002 API | Описание |
|---|---|---|---|
| Вспомогательная функция | Image.Image(Buffer, PixelFormat, int, int) | Image.create |
Миграция на версию 4001
Совет
Только при использовании Mega есть несовместимые изменения; использование других функций не затрагивается.
При миграции с версии 4000 на 4001, помимо общего guide по миграции выше, нужно также учитывать следующее.
Изменения API
| Модуль | v4000 API | v4001 API | Описание |
|---|---|---|---|
| Mega | MegaTrackerFrameFilter.ResultPoseType.EnableLocalization | MegaTrackerFrameFilter.EnableLocalization | Управление процессом tracking Mega |
| Mega | MegaTrackerFrameFilter.ResultPoseType.EnableStabilization | - | Функция удалена |
Историческая миграция
При миграции с версий до 4000 нужно смотреть: