Table of Contents

Руководство по миграции EasyAR Sense Unity Plugin

В этой статье описано, как перейти с старой версии EasyAR Sense Unity Plugin на новую.

Пояснение по совместимости

Начиная с версии 4000, плагин EasyAR Sense Unity Plugin следует системе управления версиями пакетов (с использованием Semantic Versioning), требуемой Unity. Совместимость можно определить по номеру версии.

Версия 4.7 является постепенно обновляемой, любые две версии 4.7 несовместимы друг с другом.

Для версий до 4.7 только третья цифра номера версии указывает на обратную совместимость. Изменение первых двух цифр означает несовместимость. Например, версия 4.6.2 совместима с версией 4.6.1, но версия 4.6.0 несовместима с версией 4.5.0.

Предупреждение

Изменение файлов tgz или неполное обновление всего плагина после распаковки приведет к несовместимости.

Общее руководство по миграции

Для перехода на новую версию сначала необходимо удалить старую версию пакета плагина и добавить новую с помощью Package Manager window.

Рекомендуется выполнить следующие шаги:

  1. Закройте используемый Unity.
  2. Удалите каталоги сборки платформы, созданные Unity при упаковке приложения.
  3. Снова откройте проект Unity и удалите старую версию плагина EasyAR Sense Unity Plugin из проекта.
  4. Импортируйте новую версию плагина EasyAR Sense Unity Plugin.

Примечание

Примеры файлов, предоставляемые плагином, не гарантируют совместимость между версиями. После обновления плагина примеры, импортированные в проект, могут работать некорректно. Рекомендуется удалить старые примеры перед выполнением операций.

EasyAR содержит нативные библиотечные файлы. Если библиотечные функции были выполнены перед удалением или заменой (они также вызываются при сборке), эти файлы могут быть заблокированы системой, что не позволит их удалить или заменить.

Важно

Перед удалением старой версии убедитесь, что в редакторе не запущена ни одна сцена и не выполняется сборка приложения для какой-либо платформы. Обычно рекомендуется закрыть Unity перед удалением или заменой пакета и немедленно заменить его после повторного открытия.

Перед повторной сборкой с использованием новой версии плагина необходимо удалить каталоги сборки платформы, сгенерированные Unity при упаковке, включая каталог проекта Gradle, созданный для Android, и каталог Xcode, созданный для iOS.

Совет

Обычно эти каталоги могут находиться внутри папки Library проекта Unity (например, Library/Bee/Android/Prj/IL2CPP/Gradle), но в разных версиях Unity это может отличаться.

Если вы выполняли сборку, но не можете найти соответствующий каталог платформы, рекомендуется удалить всю папку Library.

Если после миграции возникает исключение SchemaHashNotMatched, обычно есть две возможности:

  1. Предыдущие операции не были выполнены правильно, что привело к неудачному или неполному обновлению, или сгенерированные Unity каталоги сборки не были правильно обновлены (примечание: если они не были удалены вручную, высока вероятность ошибки). Рекомендуется выполнить действия по предложенным шагам или перекомпилировать проект без кэша Library.
  2. Файл tgz EasyAR был изменен вручную или после распаковки плагин не был полностью обновлен. В этом случае 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 можно не импортировать этот пакет; однако, для загрузки моделей блоков в редакторе для помощи в размещении контента по-прежнему необходимо его импортировать.
    • Добавлена опция конфигурации Mega Block/Landmark support: Необходимо включить перед сборкой.
  • Изменения в функционале редактора
    • Загрузка сетки блока и других данных больше не требует использования инструмента Mega Studio. Даже если в сцене добавлен инструмент разметки, его нельзя использовать для разработки в Unity.
    • Панель компонента MegaBlockController напрямую предоставляет функции редактора блока, что обеспечивает более прямое управление.
    • Инструмент проверки сессии предоставляет больше полезных опций управления Mega, заменяя функционал в старом Mega Studio и функционал области тестирования редактора MegaTrackerFrameFilter.
  • Изменения в поведении target

При переходе от версии 4002 к 4003 необходимо особое внимание уделить переорганизации объектов блоков в сцене и замене групп узлов, сгенерированных Mega Studio, на компонент MegaBlockController:

  1. Удалите из сцены группы узлов, сгенерированные Mega Studio, включая объект MegaBlocks и все объекты блоков, находящиеся в его дочерних узлах.
    • Если есть узлы разметки, их также необходимо удалить.
    • Если под объектами блоков есть объекты контента, рекомендуется сначала переместить объекты контента в другие узлы, при этом сохраните локальные преобразования.
  2. Добавьте цель отслеживания Mega в сцену.
    • Если в исходной сцене было несколько объектов блоков, необходимо создать несколько целей отслеживания Mega в сцене.
    • Переместите объекты контента, находящиеся под исходными объектами блоков, в новые созданные цели отслеживания Mega, при этом сохраните локальные преобразования.
    • Обратите внимание на настройку идентификатора MegaBlockController.Source. Он должен совпадать с идентификатором исходного объекта блока, чтобы обеспечить правильную загрузку во время выполнения.
    • Обратите внимание на настройку MegaBlockController.Tracker для использования правильного MegaTrackerFrameFilter.
  3. Если в исходной сцене были узлы разметки, необходимо самостоятельно создать аналогичные узлы трехмерных объектов, чтобы заменить узлы разметки.
  4. Если в исходном проекте есть логика создания блоков в скриптах, необходимо использовать методы из Добавление цели отслеживания Mega для замены.
  5. Удалите недействующие скрипты на дочернем узле Mega Tracker (MegaTrackerFrameFilter) объекта AR Session (EasyAR).

В большинстве случаев, после замены узлов блоков другие элементы сцены будут работать корректно без изменений.

Изменения интерфейса

Функциональный модуль v4002 API v4003 API Инструкция по использованию
Mega MegaTrackerFrameFilter.BlockHolder MegaBlockController.Tracker Добавление целей отслеживания Mega
Настройка загрузчика в узле block вместо настройки загружаемого корневого узла block в узле tracker.
Mega MegaTrackerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) MegaTrackerFrameFilter.SwitchEndPoint Управление процессом отслеживания Mega
Mega MegaTrackerFrameFilter.SimulatorLocation MegaTrackerFrameFilter.SimulatorLocation
Mega CloudLocalizerFrameFilter.BlockHolder MegaBlockController.Tracker Добавление целей отслеживания Mega
Настройка загрузчика в узле block вместо настройки загружаемого корневого узла block в узле tracker.
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 вместо настройки загружаемого корневого узла block в узле tracker.
Mega Support EasyAR.Mega.Scene.BlockHolder.BlockRootSourceType - Функция удалена
Mega Support EasyAR.Mega.Scene.BlockHolder.MultiBlockStrategy - Функция удалена
Mega Support EasyAR.Mega.Scene.BlockActiveController ActiveController Стратегия управления активностью для target
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, помимо вышеуказанных общих рекомендаций по миграции, необходимо обратить внимание на следующие аспекты.

Изменение интерфейса

Функциональный модуль API v4001 API v4002 Инструкция по использованию
Вспомогательная функция 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 необходимо ознакомиться со следующей информацией:

Связанные темы