Table of Contents

EasyAR Sense Unity Plugin 마이그레이션 가이드

이 문서에서는 구 버전의 EasyAR Sense Unity Plugin에서 새 버전으로 마이그레이션하는 방법을 소개합니다.

호환성 설명

버전 4000부터 EasyAR Sense Unity Plugin은 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로 패키징할 때 생성된 플랫폼 컴파일 디렉토리를 삭제해야 합니다. 여기에는 Android를 패키징할 때 생성된 Gradle 프로젝트 디렉토리와 iOS를 패키징할 때 생성된 Xcode 디렉토리가 포함됩니다.

팁

일반적으로 이러한 디렉토리는 Unity 프로젝트의 Library 폴더에 있을 수 있습니다(예: Library/Bee/Android/Prj/IL2CPP/Gradle). 그러나 Unity 버전에 따라 다를 수 있습니다.

패키징을 했지만 해당 플랫폼의 디렉토리를 찾을 수 없는 경우 전체 Library 폴더를 삭제하는 것이 좋습니다.

마이그레이션 후 SchemaHashNotMatched 예외가 발생하면 일반적으로 두 가지 가능성이 있습니다.

  1. 이전 작업이 올바르게 수행되지 않아 업그레이드가 실패하거나 불완전하거나 Unity에서 생성된 컴파일 디렉토리가 올바르게 업데이트되지 않았습니다(참고: 수동으로 삭제하지 않으면 실패할 가능성이 높습니다). 제안된 단계에 따라 작업하거나 Library 캐시가 없는 프로젝트를 사용하여 다시 컴파일하는 것이 좋습니다.
  2. EasyAR의 tgz 파일을 수동으로 수정하거나 압축 해제 후 전체 플러그인을 완전히 업데이트하지 않았습니다. 이 경우 EasyAR는 사용 가능성을 보장할 수 없으며 올바른 패키지를 다시 다운로드하여 가져와야 합니다.
중요

EasyAR Sense의 라이브러리 파일 및 라이브러리 파일을 패키징한 후의 위치가 변경될 수 있으므로 Unity에서 생성한 Gradle 또는 Xcode 프로젝트를 보관 중인 경우 EasyAR.aar, libEasyAR.so, easyar.framework 등 EasyAR와 관련된 모든 파일을 미리 삭제해야 합니다.

버전 4003으로 마이그레이션

팁

Mega를 사용하는 경우에만 호환성 문제가 발생하며, 다른 기능의 사용은 영향을 받지 않습니다.

버전 4002에서 4003으로 마이그레이션할 때, 위의 일반적인 마이그레이션 가이드 외에도 다음 사항에 주의해야 합니다.

Mega 개발 프로세스 변경

4003 버전에서 Mega의 개발 프로세스가 크게 변경되었습니다. 이전에 EasyAR Sense Unity Plugin의 다른 기능을 사용한 경험이 있다면 이 프로세스에 익숙할 것입니다.

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

  • com.easyar.mega 패키지 기능 변경
    • Mega를 사용할 때 이 패키지를 더 이상 가져올 필요가 없습니다. 그러나 편집기에서 블록 모델을 로드하여 콘텐츠 배치를 보조하려면 여전히 가져와야 합니다.
    • Mega Block/Landmark 지원 구성 옵션이 추가되었습니다. 패키징 전에 활성화해야 함
  • 편집기 기능 변경
    • 블록 메시 및 기타 데이터 로드는 더 이상 Mega Studio 도구가 필요하지 않습니다. 시나리오에 주석 도구를 추가하더라도 Unity 개발에 사용할 수 없습니다.
    • MegaBlockController 컴포넌트 패널에서 직접 블록 편집 기능을 제공하므로 관리가 더 직관적입니다.
    • 세션 검증 도구는 더 많은 실용적인 Mega 제어 옵션을 제공하며 이전 Mega Studio의 기능 및 MegaTrackerFrameFilter의 편집기 테스트 영역 기능을 대체합니다.
  • 타겟 동작 변경

4002 버전에서 4003 버전으로 마이그레이션할 때 주요 작업은 시나리오의 블록 오브젝트를 재구성하고, 이전에 Mega Studio에서 생성된 노드 그룹을 MegaBlockController 컴포넌트로 대체하는 것입니다.

  1. 시나리오에서 이전에 Mega Studio에서 생성된 노드 그룹( MegaBlocks 오브젝트 및 그 하위의 모든 블록 오브젝트)을 삭제합니다.
    • 주석 노드가 있는 경우에도 삭제해야 합니다.
    • 블록 오브젝트 아래에 콘텐츠 오브젝트가 있는 경우 먼저 콘텐츠 오브젝트를 다른 노드로 이동하는 것이 좋으며, 로컬 변환을 변경하지 않도록 주의하세요.
  2. 시나리오에서 Mega 추적 대상 추가
    • 이전 시나리오에 여러 블록 오브젝트가 있는 경우 시나리오에서 여러 Mega 추적 대상을 생성해야 합니다.
    • 이전 블록 오브젝트 아래의 콘텐츠 오브젝트를 새로 생성된 Mega 추적 대상 아래로 이동하되, 로컬 변환을 변경하지 않도록 주의하세요.
    • MegaBlockController.Source의 ID를 구성하여 이전 블록 오브젝트의 ID와 일치하도록 하여 런타임에 올바르게 로드되도록 합니다.
    • MegaBlockController.Tracker를 구성하여 올바른 MegaTrackerFrameFilter를 사용하도록 합니다.
  3. 이전 시나리오에 주석 노드가 있는 경우 유사한 3D 오브젝트 노드를 직접 생성하여 주석 노드를 대체해야 합니다.
  4. 이전 프로젝트에 스크립트에서 블록을 생성하는 로직이 있는 경우, Mega 추적 대상 추가의 방법을 사용하여 대체해야 합니다.
  5. AR Session (EasyAR) 하위 노드 Mega Tracker(MegaTrackerFrameFilter)에서 더 이상 작동하지 않는 스크립트를 삭제합니다.

대부분의 사용 사례에서는 블록 노드를 대체한 후 시나리오의 다른 콘텐츠를 수정하지 않아도 정상적으로 작동합니다.

인터페이스 변경

기능 모듈 v4002 API v4003 API 사용 설명
Mega MegaTrackerFrameFilter.BlockHolder MegaBlockController.Tracker Mega 추적 대상 추가
tracker 노드에서 블록 루트 노드를 로드하도록 구성하는 대신 block 노드에서 로더를 구성합니다.
Mega MegaTrackerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) MegaTrackerFrameFilter.SwitchEndPoint Mega 추적 프로세스 제어
Mega MegaTrackerFrameFilter.SimulatorLocation MegaTrackerFrameFilter.SimulatorLocation
Mega CloudLocalizerFrameFilter.BlockHolder MegaBlockController.Tracker Mega 추적 대상 추가
tracker 노드에서 블록 루트 노드를 로드하도록 구성하는 대신 block 노드에서 로더를 구성합니다.
Mega CloudLocalizerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) CloudLocalizerFrameFilter.SwitchEndPoint Mega 추적 프로세스 제어
Mega CloudLocalizerFrameFilter.SimulatorLocation CloudLocalizerFrameFilter.SimulatorLocation
Mega MegaLocalizationResponse.Blocks MegaLocalizationResponse.Blocks Mega 추적 프로세스 제어
Mega 지원 EasyAR.Mega.Scene.BlockHolder - 기능이 삭제되었습니다.
Mega 지원 EasyAR.Mega.Scene.BlockHolder.MultiBlock - 기능이 삭제되었습니다.
Mega 지원 EasyAR.Mega.Scene.BlockHolder.BlockRoot MegaBlockController.Tracker Mega 추적 대상 추가
tracker 노드에서 블록 루트 노드를 로드하도록 구성하는 대신 block 노드에서 로더를 구성합니다.
Mega 지원 EasyAR.Mega.Scene.BlockHolder.BlockRootSourceType - 기능이 삭제되었습니다.
Mega 지원 EasyAR.Mega.Scene.BlockHolder.MultiBlockStrategy - 기능이 삭제되었습니다.
Mega 지원 EasyAR.Mega.Scene.BlockActiveController ActiveController target에 대한 active 제어 전략
Mega 지원 EasyAR.Mega.Scene.BlockController MegaBlockController Mega 추적 대상 추가
Mega 지원 EasyAR.Mega.Scene.BlockRootController - 기능이 삭제되었습니다.
Mega 지원 EasyAR.Mega.Scene.LocalTransform LocalTransform
Mega 지원 EasyAR.Mega.Scene.Location Location
Mega 지원 EasyAR.Mega.Scene.LocationConverter - 기능이 삭제되었습니다.
Mega 지원 EasyAR.Mega.Scene.AnnotationNode - 기능이 삭제되었습니다.
Mega 지원 EasyAR.Mega.Scene.AnnotationGroup - 기능이 삭제되었습니다.
Mega 지원 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 이전 버전에서 마이그레이션할 때는 다음 내용을 참조해야 합니다.

관련 주제