Table of Contents

Panduan migrasi EasyAR Sense Unity Plugin

Artikel ini menjelaskan cara bermigrasi dari versi lama EasyAR Sense Unity Plugin ke versi baru.

Penjelasan kompatibilitas

Mulai versi 4000, EasyAR Sense Unity Plugin mengikuti kontrol versi paket (menggunakan Semantic Versioning) yang diwajibkan Unity, sehingga kompatibilitas dapat dinilai dari nomor versi.

4.7 adalah versi pembaruan bertahap; dua versi 4.7 mana pun tidak kompatibel.

Untuk versi sebelum 4.7, hanya nomor versi ketiga yang menunjukkan kompatibilitas mundur. Perubahan pada dua nomor versi pertama berarti tidak kompatibel. Misalnya, 4.6.2 kompatibel dengan 4.6.1, tetapi 4.6.0 tidak kompatibel dengan 4.5.0.

Peringatan

Mengubah file tgz atau hanya memperbarui sebagian plugin setelah diekstrak akan menyebabkan ketidakcocokan.

Panduan migrasi umum

Untuk bermigrasi ke versi baru, pertama hapus paket plugin versi lama melalui Package Manager window dan tambahkan paket baru.

Disarankan melakukan langkah-langkah berikut:

  1. Tutup Unity yang sedang digunakan.
  2. Hapus direktori kompilasi platform yang dibuat saat Unity melakukan build aplikasi.
  3. Buka kembali project Unity, lalu hapus EasyAR Sense Unity Plugin versi lama dari project.
  4. Impor EasyAR Sense Unity Plugin versi baru.

Catatan

File contoh yang disediakan plugin tidak dijamin kompatibel antar versi. Setelah upgrade plugin, contoh yang sudah diimpor ke project mungkin tidak dapat bekerja normal. Disarankan menghapus contoh versi lama sebelum melanjutkan.

EasyAR menyertakan file library native. Jika file library sudah dipakai sebelum dihapus atau diganti, file tersebut akan terkunci oleh sistem dan tidak dapat dihapus atau diganti.

Penting

Sebelum menghapus versi lama, pastikan tidak ada scene yang sedang dijalankan di editor dan tidak ada aplikasi platform yang sedang dibangun. Biasanya disarankan menutup Unity terlebih dahulu sebelum menghapus atau mengganti paket, lalu menggantinya segera setelah dibuka kembali.

Sebelum membangun ulang dengan plugin versi baru, hapus dulu direktori kompilasi platform yang dihasilkan Unity, termasuk direktori project Gradle untuk Android dan direktori Xcode untuk iOS.

Kiat

Biasanya direktori ini berada di folder Library project Unity, misalnya Library/Bee/Android/Prj/IL2CPP/Gradle, tetapi bisa berbeda pada versi Unity yang lain.

Jika Anda pernah membangun tetapi tidak menemukan direktori platform terkait, disarankan menghapus seluruh folder Library.

Jika setelah migrasi muncul exception SchemaHashNotMatched, biasanya ada dua kemungkinan:

  1. Langkah sebelumnya tidak dilakukan dengan benar sehingga upgrade gagal atau tidak lengkap, atau direktori kompilasi yang dibuat Unity belum diperbarui dengan benar. Jika tidak dihapus manual, kemungkinan besar akan terjadi error. Disarankan mengikuti langkah yang dianjurkan atau membangun ulang menggunakan project tanpa cache Library.
  2. File tgz EasyAR dimodifikasi secara manual atau seluruh plugin tidak diperbarui dengan lengkap setelah diekstrak. Dalam kasus ini EasyAR tidak dapat menjamin penggunaan yang benar, sehingga Anda perlu mengunduh ulang paket yang benar dan mengimpornya.
Penting

Karena file library EasyAR Sense dan lokasi file setelah dibangun dapat berubah, jika Anda menyimpan project Gradle atau Xcode yang dihasilkan Unity, Anda harus menghapus terlebih dahulu semua file terkait EasyAR, seperti EasyAR.aar, libEasyAR.so, easyar.framework, dan sebagainya.

Migrasi ke versi 4003

Kiat

Hanya saat menggunakan Mega ada perubahan yang tidak kompatibel; penggunaan fitur lain tidak terpengaruh.

Saat bermigrasi dari versi 4002 ke 4003, selain panduan migrasi umum di atas, Anda juga perlu memperhatikan hal berikut.

Perubahan alur pengembangan Mega

Pada versi 4003, alur pengembangan Mega mengalami perubahan besar. Jika sebelumnya Anda sudah pernah menggunakan fitur lain dari EasyAR Sense Unity Plugin, alur ini akan terasa lebih familiar.

Perubahan utama meliputi:

  • Perubahan fungsi paket com.easyar.mega
    • Untuk menggunakan Mega, paket ini tidak lagi wajib diimpor; tetapi untuk memuat model block di editor guna membantu penempatan konten, paket ini tetap perlu diimpor.
    • Ditambahkan opsi konfigurasi Mega Block/Landmark support: aktifkan sebelum build.
  • Perubahan fungsi editor
    • Pemuatan block mesh dan data lain tidak lagi memerlukan tool Mega Studio, dan meskipun tool anotasi ditambahkan ke scene, tool tersebut tidak dapat digunakan untuk pengembangan Unity.
    • Panel komponen MegaBlockController langsung menyediakan fungsi editor untuk block, sehingga pengelolaannya lebih langsung.
    • session verification tool menyediakan lebih banyak opsi kontrol Mega yang berguna, menggantikan fungsi Mega Studio sebelumnya dan area pengujian editor dari MegaTrackerFrameFilter.
  • Perubahan perilaku target

Saat bermigrasi dari 4002 ke 4003, hal yang paling penting adalah menyusun ulang objek block di scene dan mengganti grup node yang sebelumnya dihasilkan Mega Studio menjadi komponen MegaBlockController:

  1. Hapus grup node yang sebelumnya dihasilkan Mega Studio di scene, termasuk objek MegaBlocks dan semua objek block di bawahnya.
    • Jika ada node anotasi, node tersebut juga harus dihapus.
    • Jika objek block memiliki objek konten di bawahnya, disarankan memindahkan objek konten terlebih dahulu ke node lain, lalu pastikan local transform tetap tidak berubah.
  2. Tambahkan target tracking Mega di scene.
    • Jika scene asli memiliki beberapa objek block, Anda perlu membuat beberapa target tracking Mega di scene.
    • Pindahkan objek konten yang sebelumnya berada di bawah objek block ke target tracking Mega yang baru dibuat, lalu pastikan local transform tetap tidak berubah.
    • Perhatikan pengaturan id pada MegaBlockController.Source; id ini harus sama dengan id objek block asli agar runtime dapat memuatnya dengan benar.
    • Perhatikan pengaturan MegaBlockController.Tracker agar menggunakan MegaTrackerFrameFilter yang benar.
  3. Jika scene asli memiliki node anotasi, Anda perlu membuat node serupa secara manual sebagai pengganti node anotasi.
  4. Jika project asli memiliki logika untuk membuat block di script, gunakan metode Tambahkan target tracking Mega sebagai pengganti.
  5. Hapus skrip yang tidak valid pada node anak Mega Tracker (MegaTrackerFrameFilter) di bawah AR Session (EasyAR).

Untuk sebagian besar kasus, setelah mengganti node block, isi scene lainnya tidak perlu diubah dan dapat berjalan normal.

Perubahan API

Modul fungsi v4002 API v4003 API Penjelasan
Mega MegaTrackerFrameFilter.BlockHolder MegaBlockController.Tracker Tambahkan target tracking Mega
Di node block, konfigurasi loader menggantikan block root yang dikonfigurasi pada node tracker.
Mega MegaTrackerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) MegaTrackerFrameFilter.SwitchEndPoint Kontrol proses tracking Mega
Mega MegaTrackerFrameFilter.SimulatorLocation MegaTrackerFrameFilter.SimulatorLocation
Mega CloudLocalizerFrameFilter.BlockHolder MegaBlockController.Tracker Tambahkan target tracking Mega
Di node block, konfigurasi loader menggantikan block root yang dikonfigurasi pada node tracker.
Mega CloudLocalizerFrameFilter.SwitchEndPoint(ExplicitAddressAccessData, BlockRootController) CloudLocalizerFrameFilter.SwitchEndPoint Kontrol proses tracking Mega
Mega CloudLocalizerFrameFilter.SimulatorLocation CloudLocalizerFrameFilter.SimulatorLocation
Mega MegaLocalizationResponse.Blocks MegaLocalizationResponse.Blocks Kontrol proses tracking Mega
Mega Support EasyAR.Mega.Scene.BlockHolder - Fitur dihapus
Mega Support EasyAR.Mega.Scene.BlockHolder.MultiBlock - Fitur dihapus
Mega Support EasyAR.Mega.Scene.BlockHolder.BlockRoot MegaBlockController.Tracker Tambahkan target tracking Mega
Di node block, konfigurasi loader menggantikan block root yang dikonfigurasi pada node tracker.
Mega Support EasyAR.Mega.Scene.BlockHolder.BlockRootSourceType - Fitur dihapus
Mega Support EasyAR.Mega.Scene.BlockHolder.MultiBlockStrategy - Fitur dihapus
Mega Support EasyAR.Mega.Scene.BlockActiveController ActiveController Strategi kontrol active yang berlaku untuk target
Mega Support EasyAR.Mega.Scene.BlockController MegaBlockController Tambahkan target tracking Mega
Mega Support EasyAR.Mega.Scene.BlockRootController - Fitur dihapus
Mega Support EasyAR.Mega.Scene.LocalTransform LocalTransform
Mega Support EasyAR.Mega.Scene.Location Location
Mega Support EasyAR.Mega.Scene.LocationConverter - Fitur dihapus
Mega Support EasyAR.Mega.Scene.AnnotationNode - Fitur dihapus
Mega Support EasyAR.Mega.Scene.AnnotationGroup - Fitur dihapus
Mega Support EasyAR.Mega.Scene.NavPointGraph - Fitur dihapus

Migrasi ke versi 4002

Saat bermigrasi dari versi 4001 ke 4002, selain panduan migrasi umum di atas, Anda juga perlu memperhatikan hal berikut.

Perubahan API

Modul fungsi v4001 API v4002 API Penjelasan
Fitur bantu Image.Image(Buffer, PixelFormat, int, int) Image.create

Migrasi ke versi 4001

Kiat

Hanya saat menggunakan Mega ada perubahan yang tidak kompatibel; penggunaan fitur lain tidak terpengaruh.

Saat bermigrasi dari versi 4000 ke 4001, selain panduan migrasi umum di atas, Anda juga perlu memperhatikan hal berikut.

Perubahan API

Modul fungsi v4000 API v4001 API Penjelasan
Mega MegaTrackerFrameFilter.ResultPoseType.EnableLocalization MegaTrackerFrameFilter.EnableLocalization Kontrol proses tracking Mega
Mega MegaTrackerFrameFilter.ResultPoseType.EnableStabilization - Fitur dihapus

Migrasi versi historis

Saat bermigrasi dari versi sebelum 4000, Anda perlu merujuk pada:

Topik terkait