Table of Contents

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 전체를 완전히 업데이트하지 않으면 호환되지 않게 됩니다.

일반 마이그레이션 가이드

새 버전으로 옮기려면 먼저 Package Manager window에서 기존 plugin package를 삭제하고 새 package를 추가하세요.

다음 단계를 권장합니다.

  1. 사용 중인 Unity를 닫습니다.
  2. Unity가 앱을 build할 때 생성한 platform build directory를 삭제합니다.
  3. Unity project를 다시 열고 오래된 EasyAR Sense Unity Plugin을 project에서 제거합니다.
  4. 새 EasyAR Sense Unity Plugin을 가져옵니다.

참고

plugin이 제공하는 예시 files는 버전 간 호환성을 보장하지 않습니다. plugin을 업데이트한 뒤 project에 가져온 예시가 정상 동작하지 않을 수 있습니다. 오래된 예시를 먼저 삭제하고 진행하는 것을 권장합니다.

EasyAR에는 native library files가 포함됩니다. 삭제하거나 교체하기 전에 이 files가 이미 사용되었다면 system이 이를 lock하여 삭제나 교체가 불가능합니다.

중요

오래된 버전을 삭제하기 전에 editor에서 scene이 실행 중이 아니고 어떤 platform application도 build 중이 아님을 확인하세요. 보통은 package를 삭제하거나 교체하기 전에 Unity를 닫고, 다시 연 직후 교체하는 것이 좋습니다.

새 버전 plugin으로 다시 build하기 전에 Unity가 생성한 platform build directory를 먼저 삭제하세요. Android의 Gradle directory와 iOS의 Xcode directory를 포함합니다.

팁

이런 directory는 보통 Unity project의 Library 폴더에 있습니다. 예를 들어 Library/Bee/Android/Prj/IL2CPP/Gradle 같은 경로지만, Unity 버전에 따라 다를 수 있습니다.

이미 build했는데 해당 platform directory를 찾지 못했다면 Library 폴더 전체를 삭제하는 것이 좋습니다.

마이그레이션 후 SchemaHashNotMatched exception이 나타나면 보통 두 가지 가능성이 있습니다.

  1. 앞선 절차가 제대로 수행되지 않아 update가 실패했거나 불완전하거나, Unity가 생성한 build directory가 올바르게 갱신되지 않았습니다. 수동으로 삭제하지 않으면 높은 확률로 error가 납니다. 권장 절차를 따르거나 Library cache가 없는 project로 다시 build하는 것이 좋습니다.
  2. EasyAR tgz file을 수동으로 수정했거나 압축 해제 후 plugin 전체를 완전히 업데이트하지 않았습니다. 이 경우 EasyAR는 정상 사용을 보장할 수 없으므로 올바른 package를 다시 다운로드해 가져와야 합니다.
중요

EasyAR Sense의 library files와 build 후의 위치는 바뀔 수 있으므로, Unity가 생성한 Gradle 또는 Xcode project를 보관할 경우 EasyAR.aar, libEasyAR.so, easyar.framework 등 EasyAR 관련 files를 모두 먼저 삭제해야 합니다.

4003 버전으로 마이그레이션

팁

Mega를 사용할 때만 호환되지 않는 변경이 있으며, 다른 기능의 사용에는 영향이 없습니다.

4002에서 4003으로 옮길 때는 위의 일반 마이그레이션 가이드 외에 다음도 주의해야 합니다.

Mega 개발 workflow 변경

4003 버전에서는 Mega 개발 workflow가 크게 바뀌었습니다. 이전에 EasyAR Sense Unity Plugin의 다른 기능을 사용해 본 적이 있다면 이 workflow가 더 익숙할 것입니다.

주요 변경 사항은 다음과 같습니다.

  • com.easyar.mega package 기능 변경
    • Mega만 사용할 때는 이 package를 더 이상 반드시 가져올 필요가 없습니다. 하지만 editor에서 block model을 불러와 content 배치를 돕는 데는 여전히 필요합니다.
    • Mega Block/Landmark support 설정 항목이 추가되었습니다: build 전에 켜기.
  • editor 기능 변경
    • block mesh와 다른 data를 불러오는 데 더 이상 Mega Studio tool이 필요하지 않으며, scene에 annotation tool을 추가하더라도 Unity development에는 사용할 수 없습니다.
    • MegaBlockController component panel이 block editor 기능을 직접 제공해 관리가 더 직접적입니다.
    • session verification tool이 더 많은 유용한 Mega control option을 제공하며, 이전 Mega Studio 기능과 MegaTrackerFrameFilter의 editor testing area를 대체합니다.
  • target 동작 변경

4002에서 4003으로 옮길 때 가장 중요한 것은 scene의 block object를 다시 구성하고, 예전에 Mega Studio가 생성하던 node group을 MegaBlockController component로 바꾸는 일입니다.

  1. scene에서 예전에 Mega Studio가 생성한 node group을 삭제합니다. MegaBlocks object와 그 아래의 모든 block object를 포함합니다.
    • annotation node가 있으면 그것도 삭제해야 합니다.
    • block object 아래에 content object가 있다면 먼저 그것을 다른 node로 옮기고 local transform이 바뀌지 않도록 합니다.
  2. scene에 Mega target tracking을 추가합니다.
    • 원래 scene에 여러 block object가 있었다면 여러 개의 Mega target tracking object를 만들어야 합니다.
    • 예전 block object 아래에 있던 content object를 새로 만든 Mega target tracking object 아래로 옮기고 local transform이 바뀌지 않도록 합니다.
    • MegaBlockController.Source의 id 설정에 주의하세요. 이 id는 원래 block object의 id와 같아야 runtime이 올바르게 불러올 수 있습니다.
    • 올바른 MegaTrackerFrameFilter를 사용하도록 MegaBlockController.Tracker 설정에 주의하세요.
  3. 원래 scene에 annotation node가 있으면, 그에 비슷한 node를 수동으로 만들어 대체해야 합니다.
  4. 원래 project에 script로 block을 만드는 로직이 있으면, Mega target tracking 추가 방법으로 대체합니다.
  5. AR Session (EasyAR) 아래의 자식 node Mega Tracker (MegaTrackerFrameFilter)에서 더 이상 유효하지 않은 script를 삭제합니다.

대부분의 경우 block node를 바꾼 뒤에는 scene의 다른 content를 수정할 필요가 없으며 정상 동작합니다.

API 변경

기능 모듈 v4002 API v4003 API 설명
Mega MegaTrackerFrameFilter.BlockHolder MegaBlockController.Tracker Mega target tracking 추가
block node에서는 tracker node에 설정하던 block root 대신 loader를 설정합니다.
Mega MegaTrackerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) MegaTrackerFrameFilter.SwitchEndPoint Mega tracking process 제어
Mega MegaTrackerFrameFilter.SimulatorLocation MegaTrackerFrameFilter.SimulatorLocation
Mega CloudLocalizerFrameFilter.BlockHolder MegaBlockController.Tracker Mega target tracking 추가
block node에서는 tracker node에 설정하던 block root 대신 loader를 설정합니다.
Mega CloudLocalizerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) CloudLocalizerFrameFilter.SwitchEndPoint Mega tracking process 제어
Mega CloudLocalizerFrameFilter.SimulatorLocation CloudLocalizerFrameFilter.SimulatorLocation
Mega MegaLocalizationResponse.Blocks MegaLocalizationResponse.Blocks Mega tracking process 제어
Mega Support EasyAR.Mega.Scene.BlockHolder - 기능 삭제
Mega Support EasyAR.Mega.Scene.BlockHolder.MultiBlock - 기능 삭제
Mega Support EasyAR.Mega.Scene.BlockHolder.BlockRoot MegaBlockController.Tracker Mega target tracking 추가
block node에서는 tracker node에 설정하던 block root 대신 loader를 설정합니다.
Mega Support EasyAR.Mega.Scene.BlockHolder.BlockRootSourceType - 기능 삭제
Mega Support EasyAR.Mega.Scene.BlockHolder.MultiBlockStrategy - 기능 삭제
Mega Support EasyAR.Mega.Scene.BlockActiveController ActiveController target에 적용되는 active control strategy
Mega Support EasyAR.Mega.Scene.BlockController MegaBlockController Mega target tracking 추가
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 API 설명
보조 기능 Image.Image(Buffer, PixelFormat, int, int) Image.create

4001 버전으로 마이그레이션

팁

Mega를 사용할 때만 호환되지 않는 변경이 있으며, 다른 기능의 사용에는 영향이 없습니다.

4000에서 4001로 옮길 때는 위의 일반 마이그레이션 가이드 외에 다음도 주의해야 합니다.

API 변경

기능 모듈 v4000 API v4001 API 설명
Mega MegaTrackerFrameFilter.ResultPoseType.EnableLocalization MegaTrackerFrameFilter.EnableLocalization Mega tracking process 제어
Mega MegaTrackerFrameFilter.ResultPoseType.EnableStabilization - 기능 삭제

기존 버전 마이그레이션

4000 이전 버전에서 옮길 때는 다음을 참고하세요.

관련 주제