Panduan migrasi dari MRTK2 ke MRTK3

Artikel
04/25/2023

Saat Anda mulai menggunakan MRTK3, Anda akan melihat bahwa beberapa konsep di MRTK v2 telah diubah, diganti, atau dihapus. Dokumen ini membantu menjelang kesenjangan antara konsep MRTK v2 dan mitra MRTK3 mereka.

Interaksi

MRTK3 menggunakan kerangka kerja XR Interaction Toolkit (XRI) Unity untuk menangani interaksi, dan Sistem Input Unity ditambah OpenXR untuk input.

Penting

Untuk pengembang yang baru menggunakan XRI, kami sarankan Anda terlebih dahulu meninjau dokumentasi arsitektur XRI Unity. Semua dokumentasi XRI juga berlaku untuk MRTK3, karena sebagian besar fitur interaksi dan input hanya diwarisi dari XRI.

Terminologi

Istilah MRTK v2	Istilah MRTK3	Deskripsi
Penunjuk	Interaktor	Interaksi melakukan interaksi pada Interactables. Beberapa (tetapi tidak semua) Interaksi didorong oleh Pengontrol, tempat mereka menerima tindakan input dan pose. Interaktor lain beroperasi secara independen dari pengontrol. MRTK mengirimkan beberapa Interactor kustom yang menyediakan interaksi realitas campuran yang berguna di atas Interactors Unity dasar yang sudah disediakan. Interaksi kustom dapat dibangun baik melalui pewarisan atau dengan mengimplementasikan antarmuka Interactor (`IXRHoverInteractor`, `IXRSelectInteractor`, dan sebagainya). Untuk informasi selengkapnya, lihat dokumentasi arsitektur Interactor.
`NearInteractionGrabbable, NearInteractionTouchable, IMixedRealityPointerHandler`	Dapat berinteraksi	Dapat berinteraksi adalah penerima interaksi. MRTK mengirimkan beberapa Interactables kustom yang memberikan interaksi realitas campuran yang berguna di atas Unity Interactables dasar yang sudah disediakan. Interactable dapat dibangun baik melalui pewarisan atau dengan mengimplementasikan antarmuka yang dapat berinteraksi (`IXRHoverInteractable`, `IXRSelectInteractable`, dan sebagainya). Untuk informasi selengkapnya tentang cara MRTK memperluas XRI yang dapat berinteraksi, lihat dokumentasi arsitektur yang dapat berinteraksi.
Pengontrol	Pengontrol	ActionBasedController adalah kumpulan Tindakan Input Unity yang mewakili pengikatan yang terkait dengan perangkat tertentu. Pengumpulan Tindakan Input dapat berasal dari beberapa perangkat, karena tidak ada hubungan 1:1 antara `ActionBasedControllers` dan perangkat input yang mendasar. (A `DeviceBasedController` adalah pemetaan 1:1 dari perangkat input, tetapi kami tidak menggunakannya.) Banyak interaktor (`ControllerBasedInteractor`khususnya) mendengarkan Pengontrol untuk tindakan input--dengan kata lain, semuanya `ControllerBasedInteractor`berada di bawah XRController berbagi tindakan pilih yang sama.
Sistem Teleport	Sistem Locomotion	Sistem Locomotion memungkinkan pengguna untuk berpindah tentang adegan selama pengalaman XR. Sistem MRTK v2 memungkinkan hotspot teleportasi dan teleportasi dasar, dengan tingkat penyesuaian yang tinggi untuk kursor teleport dan perilaku pointer. XRI menawarkan kemampuan tambahan berikut untuk locomotion: Penyedia Snap Turn yang memutar rig dengan sudut tetap Penyedia Giliran Berkelanjutan yang memutar rig dengan lancar dari waktu ke waktu Penyedia Pemindahan Berkelanjutan yang memindahkan rig dengan lancar dari waktu ke waktu
Penyedia Fokus	Pengelola Interaksi XR	XRInteractionManager adalah mekanisme Unity yang berfungsi sebagai perantara antara Interactors dan Interactables di adegan. Unity `XRInteractionManager` menyinkronkan dan membuat arbitrase semua interaksi antara Interactors dan Interactables, dan memungkinkan fleksibilitas yang jauh lebih besar jika dibandingkan dengan Penyedia Fokus warisan.
Mediator Pointer	Pengelola Mode Interaksi	Pengelola Mode Interaksi baru digunakan untuk mengaktifkan/menonaktifkan set interaktor tergantung pada konteks dalam adegan. Lihat dokumentasi manajer mode untuk informasi selengkapnya.
SceneQuerymask	Lapisan Interaksi	Lapisan interaksi XRI memungkinkan pengembang untuk memfilter Interactor mana yang dapat bertindak di mana Interactables. Lapisan-lapisan ini berbeda dari lapisan fisika Unity.
Fokus	Hover	Interaksi mengeluarkan Hovers on Interactables saat Interactable adalah target yang valid untuk Interactor. Umumnya, Hover menunjukkan niat dari interaksi, seperti menargetkan dengan sinar, kedekatan tangan untuk diambil, atau jika pengguna melihat objek.
Pilih/Poke/Grab/Voice dll.	Pilih	Masalah Interaktor Memilih di Interactables saat Interactable adalah target yang valid dan Interactor memilih untuk melakukannya. ControllerBasedInteractors umumnya memancarkan Pilih saat tindakan input pilih Pengontrol yang sesuai diaktifkan. Interaksi lain dapat memiliki logika yang lebih kompleks untuk menentukan kapan pemilihan harus dikeluarkan ke Interactable yang ditargetkan. MRTK v2 menangani berbagai jenis interaksi dengan peristiwa dan codepath terpisah--dengan kata lain, perampasan adalah interaksi yang pada dasarnya berbeda dari klik sinar atau poke, yang dihasilkan oleh sistem terpisah. Di MRTK3, semua cara "memilih" objek ini disatukan di bawah interaksi Pilih yang sama. Kami sangat mencegah pengembang membangun logika interaksi yang bergantung pada jenis interaksi tertentu; sebagai gantinya, tulis kode yang dapat digeneralisasi yang merespons secara generik ke semua Pilih. Dengan cara ini, interaksi Anda bekerja di semua modalitas input, dan bahkan untuk jenis interaksi yang belum dikembangkan. Lihat arsitektur Interactable untuk membaca lebih lanjut tentang mengapa kami mencegah kursus ini.
T/A	Aktifkan	Aktifkan adalah tindakan tambahan yang dapat dinaikkan pada objek yang telah Dipilih. Misalnya, jika pengguna Memilih pistol squirt dengan cengkeraman pengontrol, pemicu akan menembakkannya dengan tindakan Aktifkan.
Penyedia Data	XRSubsystem + Penyedia	Sebagian besar penyedia data tidak lagi diperlukan di MRTK3, karena Sistem Input Unity dan OpenXR menangani sebagian besar tugas input lintas platform. Namun, untuk beberapa outlier yang belum tercakup oleh Unity, kami menyediakan `XRSubsystem`yang dapat menyediakan data di berbagai platform --misalnya, `HandsAggregatorSubsystem` dan `SpeechSubsystem`. Lihat dokumentasi arsitektur subsistem untuk membaca lebih banyak konseptual tentang pendekatan subsistem kami.

Acara

Istilah MRTK v2	Istilah XRI	Catatan
`OnFocusEnter/Exit`	`FirstHoverEnter` `LastHoverExit`	Perhatikan awalan `First` dan `Last` . Prefiks ini disertakan dalam nama peristiwa karena sejumlah Interaktor dapat secara bersamaan mengarahkan kuotasi ke Interactable. Anda juga dapat mendengarkan setiap hover individu masuk/keluar dengan `HoverEnter` dan `HoverExit`, meskipun kurang berguna daripada memantau status hover secara keseluruhan.
`OnPointerDown/Up`	`FirstSelectEnter` `LastSelectExit`	Perhatikan awalan `First` dan `Last` . Awalan ini disertakan dalam nama peristiwa karena sejumlah Interaktor dapat secara bersamaan memilih Interactable (tergantung pada mode pemilihan). Anda juga dapat mendengarkan setiap individu memilih enter/exit dengan `SelectEnter` dan `SelectExit`, meskipun kurang berguna daripada memantau status pemilihan secara keseluruhan.
`OnPointerDragged`	T/A	Cukup polling `interactorsSelecting` transformasi lampirkan dengan `GetAttachTransform` selama pilihan. Perlu diingat bahwa, tergantung pada mode pemilihan Interactable, sejumlah Interactor yang tidak terbatas dapat memilih (dan memanipulasi) interactable.
`OnSourcePoseChanged, OnSourceDetected, OnSourceLost`	T/A	XRI tidak menaikkan peristiwa ini. Mereka ditangani melalui XRController yang memantau Perangkat Input terkait.

Komponen UX

Untuk dokumentasi lengkap tentang komponen MRTK3 UX, lihat gambaran umum untuk paket UX: UX Core, , UX Componentsdan UX Components (Non-Canvas). Perubahan besar dalam MRTK3 adalah penekanan pada komponen Canvas UX, yang menggunakan Unity UI. Ada juga paket untuk komponen UX Non-Kanvas. Perbandingan antara Canvas dan Non-Canvas UX dapat ditemukan di sini.

Catatan

Hand Coach, Tooltips, Object Collection, AppBar, dan Progress Indicator komponen belum ada di MRTK3. Selain itu, Toolbox dan dioptimalkan Text Prefabs tidak diimplementasikan. Dokumen ini akan diperbarui saat komponen UX MRTK3 tambahan ditambahkan

MRTK2	MRTK3	Catatan
`Buttons`	`Canvas Button` `Non-Canvas Button`	Di MRTK3, tombol berbasis UI Unity dan tombol berbasis Collider direnovasi sebagai tombol Kanvas dan Non-Kanvas. Alat bawaan untuk mengelompokkan tombol di MRTK3 menyertakan `Button Group` dan `ToggleCollection`. Sampel dapat ditemukan di `CanvasUITearsheet` adegan dan `NonCanvasUITearsheet` .
`Slider`	`Canvas Slider` `Non-Canvas Slider`	Sampel dapat ditemukan di `HandInteractionExamples` adegan.
`Dialog`	`Dialog` `Dialog API`	Sampel dapat ditemukan di `DialogExample` adegan.
`Scrolling Collection`	`VirtualizedScrollRectList`	Sampel dapat ditemukan di `VirtualizedScrollRectList` adegan. Dokumentasi MRTK3 saat ini sedang berlangsung.
`Slate`	`Slate (Non-Canvas)`	Sampel dapat ditemukan di `SlateDrawingExample` adegan.
`See-it, Say-it Label`	`See-it, Say-it Label`	Sampel dapat ditemukan di `SeeItSayItExample` adegan.
`Hand Menu`	`Hand Menu`	Sampel dapat ditemukan di `HandMenuExamples` adegan.
`Near Menu`	`Near Menu`	Sampel dapat ditemukan di `NearMenuExamples` adegan.
`System Keyboard`	`System Keyboard`	Sampel dapat ditemukan di `HandInteractionExamples` adegan.
`Fingertip Visualization`	`Fingertip Visualization`	`FingerCursor` Skrip dan prefab diganti di MRTK3 dan ujung jari indeks divisualisasikan melalui `MRTKPokeReticleVisual`skrip , , `RingReticle`dan `ReticleMagnetism` . `MRTK LeftHand Controller` Prefab berisi contoh cara menggunakan komponen-komponen ini.
`Constraint Manager`	`Constraint Manager`	Sampel dapat ditemukan di `BoundsControlExamples` adegan.
`Bounds Control` `Bounding Box`	`Bounds Control`	`BoundingBox` Skrip telah diganti. `BoundsControl` menyediakan kotak pembatas berukuran otomatis, yang visualnya dapat disesuaikan. Ada beberapa `BoundingBox` prefab yang dapat digunakan untuk visual. Sampel dapat ditemukan di `BoundsControlExamples` adegan.
`Object Manipulator` `Manipulation Handler`	`Object Manipulator`	`Manipulation Handler` tidak digunakan lagi. Gunakan `Object Manipulator` untuk manipulasi (pindahkan, putar, skala) objek oleh interaksi mana pun dengan transformasi lampirkan yang valid. Sampel dapat ditemukan di `HandInteractionExamples` adegan.
`Interactable`	`StatefulInteractable`	Sampel dapat ditemukan di `InteractableButtonExamples` adegan.
`Dwell`	`InteractorDwellManager`	Di MRTK2, `DwellHandler` dilampirkan ke objek dan menyediakan peristiwa untuk menangani awal dan akhir tempat tinggal. Di MRTK3, ada `InteractorDwellManager` di `GazeInteractor` dan `Far Rays` di `MRTK XR Rig`, yang menggunakan `StatefulInteractable` untuk menentukan apakah objek mengaktifkan tinggal atau tidak, dan jika itu memilih objek selama durasi tinggal. Dokumentasi MRTK3 saat ini sedang berlangsung.
`Solvers`	`Solvers`	Adegan sampel MRTK3 saat ini sedang berlangsung.
`Visual Theming`	`Data Binding and Theming`	Kerangka kerja PENGIKATAN dan Tema Data MRTK3 dirancang untuk memudahkan pembuatan elemen visual yang dapat diisi dan diperbarui secara dinamis saat runtime. Belum terintegrasi dengan Canvas UX.

Konfigurasi Input

Tindakan Input

MRTK 3 menggunakan Paket Sistem Input Unity baru untuk tindakan input. Sebagian besar pengaturan dapat dikonfigurasi melalui aset Input Action .

Tugas	MRTK 2	MRTK 3
Buat `Input Action`	Profil Tindakan Input	Gunakan Peta Tindakan dalam `Input Action` aset.
Mengikat `Input Action` ke `Controller`	Profil Pemetaan Input Pengontrol	Atur pengikatan untuk tindakan dengan `Input Action` aset.

Pointer

Pointer dilampirkan ke interaktor di MRTK3. Dalam default MRTK XR Rig, interaktor diposisikan di bawah MRTK RightHand Controller dan MRTK LeftHand Controller.

Tugas	MRTK 2	MRTK 3
Mengatur prefab visual untuk penunjuk	`Pointer Prefab` properti di Profil Konfigurasi Pointer MRTK 2.	MonoBehaviours di `MRTK RightHand Controller` dan `MRTK LeftHand Controller` di `MRTK XR Rig`. Misalnya, `MRTKPokeReticleVisual`, `MRTKLineVisual`, dan `MRTKRayReticleVisual`.
Batasi lapisan mana yang dapat berinteraksi dengan	`Pointing Raycast Layer Masks` properti dalam `MRTK Pointer Profile`. Ini berlaku untuk semua pointer.	`raycastMask` properti pada `Interactor` skrip.
Mengatur tingkat raycast pointer	`Pointing Extent` properti dalam `MRTK Pointer Profile`. Ini berlaku untuk semua pointer.	`maxRaycastDistance` properti pada `Interactor` skrip.
Mengatur prioritas pointer	Dikontrol oleh `DefaultPointerMediator` atau penimpaan.	Dikonfigurasi melalui `InteractionModeManager` (MRTK3 MonoBehaviour).

Gestur

Input Actions dapat ditetapkan ke berbagai metode input gerakan (saat ini hanya didukung untuk Windows Recognition pada HoloLens 2).

Tugas	MRTK 2	MRTK 3
Menetapkan tindakan ke gerakan	Tetapkan gerakan ke `Input Action` dalam `MixedRealityGesturesProfile`.	Gerakan pada HoloLens 2 sekarang dikenali melalui plugin OpenXR.

Perintah Ucapan

KeywordRecognitionSubsystem dapat diaktifkan untuk mengizinkan perintah ucapan di MRTK 3. Informasi lebih lanjut dapat ditemukan dalam dokumentasi tentang Input Ucapan.

Tugas	MRTK 2	MRTK 3
Memetakan perintah ucapan ke `Input Actions`	`Speech Commands ProfileInput System Profile`di .	`KeywordRecongitionSubsystem` Panggil `CreateOrGetEventForKeyword` dengan kata kunci dan tindakan Anda.

Konfigurasi Pengontrol

Tugas	MRTK 2	MRTK 3
Mengonfigurasi perilaku tombol pengontrol	ControllerMappingProfile	Peta Tindakan dalam `Input Action` aset.
Mengatur prefab untuk visualisasi pengontrol	ControllerMappingProfile	Dikonfigurasi dalam `XRController` pengaturan. Misalnya, `Model Prefab` properti di `ArticulatedHandController.`

Bagikan melalui