Cara menggunakan kemampuan EasyAR di Apple Vision Pro

Panduan ini akan membantu Anda menyelesaikan konfigurasi proyek Unity dan Xcode untuk membuka seluruh kemampuan inti EasyAR di aplikasi Apple Vision Pro, termasuk Mega cloud localization.

Sebelum mulai

• Pelajari cara menggunakan contoh headset
• Pastikan lingkungan pengembangan memenuhi persyaratan berikut:
  • visionOS 2.0 atau lebih baru
  • Xcode 16.0 atau lebih baru yang sesuai dengan versi visionOS, serta visionOS simulator yang sudah terpasang
  • Versi Unity yang direkomendasikan adalah LTS 6000.0.23 atau lebih baru

Mengajukan lisensi API enterprise ke Apple Inc.

Karena mendapatkan frame kamera dan parameternya di Apple Vision Pro memerlukan entitlement sebagai enterprise API, Anda perlu mengajukan file license yang menyertakan entitlement tersebut kepada Apple Inc.. Cara pengajuan dan penggunaan license ini dapat dirujuk pada Building spatial experiences for business apps with enterprise APIs for visionOS.

Penting

Bundle ID di dalam entitlement yang Anda peroleh dari Apple harus sama persis dengan yang diisi saat membuat EasyAR Sense License Key.

Cara memilih visionOS App Mode

Aplikasi yang berjalan di visionOS hanya dapat memperoleh data ARKit saat berada dalam Immersive Space. Aplikasi yang dibangun dari Unity Editor, saat berjalan dalam Immersive Space, perlu memilih mode RealityKit with PolySpatial atau Metal Rendering with Compositor Services tergantung pada perbedaan alur rendering dan API.

Untuk definisi Immersive Space, Anda dapat merujuk ke dokumentasi resmi Apple.

Untuk penjelasan rinci tentang App Mode di Unity, Anda dapat merujuk ke visionOS Platform Overview dalam dokumentasi Unity PolySpatial.

Kiat

Saran pemilihan App Mode

• Rekomendasi utama: RealityKit with PolySpatial

  Jika Anda baru pertama kali menggunakan visionOS, disarankan memilih mode ini terlebih dahulu. Keunggulannya adalah integrasi yang dalam dengan rendering tingkat sistem visionOS, stabilitas tinggi, dan hasil rendering yang baik. Mode ini tidak mendukung shader kustom (HLSL/ShaderLab), sehingga Anda harus menggunakan Shader Graph, dan hanya fitur yang lolos pemeriksaan kompatibilitas PolySpatial yang didukung (akan dikonversi menjadi MaterialX).

  Shader bawaan Unity Standard (Built-in) dan Lit (URP) sudah disesuaikan oleh pihak resmi dan dapat langsung digunakan.

• Lanjutan/kebutuhan khusus: Metal Rendering with Compositor Services

  Cocok untuk proyek kompleks yang memiliki kebutuhan migrasi aset 3D besar atau harus menggunakan shader kustom. Karena mode ini membuat Unity menangani seluruh logika rendering, melewati pipeline RealityKit sistem, hasil rendering umumnya tidak sebaik RealityKit dan mungkin menghadapi masalah rendering yang tidak terduga.

Saran integrasi EasyAR:

Saat mencoba mengintegrasikan EasyAR, pastikan terlebih dahulu untuk menjalankan alur dasar dengan mode RealityKit with PolySpatial. Ini membantu mengisolasi variabel, sehingga masalah adaptasi Metal bawah dan masalah AR tidak bercampur dan sulit dilacak penyebabnya.

Konfigurasi di proyek Unity

Di proyek Unity, Anda perlu melakukan konfigurasi berikut:

Mengimpor package yang diperlukan ke proyek Unity

Unity 6 (direkomendasikan):

• RealityKit/Hybrid
• Metal

• com.unity.xr.visionos (2.0.4+)
• com.unity.polyspatial (2.0.4+)
• com.unity.polyspatial.visionos (2.0.4+)

Penting

Semua versi package harus benar-benar sama.

Disarankan memprioritaskan Unity 6. Beberapa versi awal Unity 2023.x belum mendukung visionOS.

Unity 2022.3:

• RealityKit/Hybrid
• Metal

• com.unity.xr.visionos (1.2.3)
• com.unity.polyspatial (1.2.3)
• com.unity.polyspatial.visionos (1.2.3)

Penting

Semua versi package harus benar-benar sama.

Versi 1.3.x tidak didukung, pastikan terkunci di 1.2.3.

Memilih Build Platform

Klik File > Build Profiles di menu bar untuk mengganti Platform menjadi visionOS.

Mengonfigurasi Input System

Pastikan menggunakan Input System Package versi baru:

Klik Edit > Project Settings > Player, lalu set slot Active Input Handling ke Input System Package(New).

Setelah itu Unity mungkin akan meminta Anda me-restart proyek, klik Apply agar perubahan berlaku.

Mengonfigurasi XR Plug-in Management

Klik Edit > Project Settings > XR Plug-in Management, lalu pada tab visionOS centang Apple visionOS di Plug-in Providers.

Mengonfigurasi plugin Apple visionOS

Klik Edit > Project Settings > XR Plug-in Management > Apple visionOS.

Pilih App Mode yang sesuai menurut penjelasan sebelumnya.

Catatan

Mode Windowed bukan berjalan di Immersive Space, sehingga tidak dapat menggunakan kemampuan AR.

Mode Hybrid berarti pengembang harus berpindah manual antara mode Metal dan RealityKit. Karena cara pakainya cukup rumit, mode ini tidak direkomendasikan. Detailnya bisa dilihat di penjelasan resmi Unity tentang mode ini.

Lalu pada halaman yang sama, lakukan perubahan berikut:

• Tambahkan deskripsi pada slot World Sensing Usage Description.
• Set Metal Immersion Style ke Mixed.
• Set Reality Kit Immersion Style ke Mixed.
• Centang IL2CPP Large Exe Workaround.

[Hanya diperlukan untuk mode RealityKit] Mengimpor TextMesh Pro Essentials

Klik Edit > Project Settings > TextMesh Pro > klik Import TMP Essentials

Catatan

Saat ini mode RealityKit with PolySpatial hanya mendukung teks TextMesh Pro. Jika tidak diimpor, teks tidak akan bisa dirender.

[Hanya diperlukan untuk mode RealityKit] Pengaturan terkait PolySpatial

Klik Edit > Project Settings > PolySpatial, lalu lakukan perubahan berikut di halaman tersebut:

• Set Default Volume Camera Window Config ke Default Unbounded Configuration.
• Centang Auto-Create Volume Camera

Jika Anda perlu menentukan Default Volume Camera Window Config secara terpisah, pastikan Mode-nya adalah Unbounded.

Jika ada Volume Camera di scene, hapus objek tersebut.

Peringatan

• Volume Camera dengan nilai World Transform yang bukan identity tidak didukung.
• Jika karena alasan khusus Anda perlu menambahkan satu-satunya Volume Camera kustom di scene, pastikan:
  • World Transform-nya diset ke identity.
  • Mode pada Volume Camera Window Configuration diset ke Unbounded.
  • Anda menggunakannya setelah benar-benar memahami arti dan tujuannya pada dokumentasi resmi Unity.

[Saat menggunakan Mega] Tambahkan Location Usage Description

Hati-Hati

Jika Anda mengaktifkan izin Location di konfigurasi EasyAR (saat menggunakan fitur Mega), deskripsi izin harus ditambahkan, jika tidak Build akan gagal.

Karena saat ini tab visionOS di Project Settings > Player Unity tidak menampilkan field Location Usage Description, ikuti langkah berikut:

1. Pindahkan tab platform: sementara ubah tab ke iOS.
2. Isi deskripsi: masukkan penjelasan tujuan izin pada slot Location Usage Description.
3. Kembalikan ke visionOS: pindahkan tab kembali ke visionOS, dan konfigurasi yang tadi diisi akan tetap tersimpan serta berlaku.

Konfigurasi di proyek Xcode

Di proyek Xcode yang dihasilkan dari Unity, Anda perlu melakukan konfigurasi berikut:

Mengonfigurasi entitlement data kamera

• Salin file Enterprise.license yang telah Anda peroleh ke direktori file proyek Xcode.

  

• Seret Enterprise.license dari direktori file proyek Xcode ke dalam proyek Xcode.

  

Mengubah info.plist agar aplikasi dapat menyimpan dan membagikan file

Jika Anda perlu merekam EIF di aplikasi dan membagikannya ke komputer atau perangkat lain melalui aplikasi file visionOS, tambahkan dan ubah field berikut di Info.plist:

• Tambahkan LSSupportsOpeningDocumentsInPlace dan set nilainya ke true.
• Tambahkan UIFileSharingEnabled dan set nilainya ke true.

Kiat

Setelah field ditambahkan, nama Key yang ditampilkan Xcode akan berbeda dari string yang Anda tambahkan secara manual. Misalnya Anda memasukkan LSSupportsOpeningDocumentsInPlace tetapi yang tampil Supports opening documents in place. Ini normal.