Menambahkan dukungan untuk Android XR ke project Godot XR yang ada

Perangkat XR yang kompatibel
Panduan ini membantu Anda membangun pengalaman untuk jenis perangkat XR ini.
Mempelajari jenis perangkat XR →
Headset XR
Kacamata XR Berkabel
Mempelajari jenis perangkat XR →

Jika memiliki project XR yang ada di Godot, Anda dapat menambahkan dukungan untuk Android XR tanpa memulai project baru yang terpisah. Beberapa langkah diperlukan untuk semua project, sementara langkah lainnya bersifat opsional, bergantung pada fitur XR yang digunakan project Anda. Selama langkah-langkah ini, kami telah menyertakan link ke beberapa project Godot XR open source yang telah menambahkan dukungan untuk Android XR, beserta permintaan pull yang relevan yang menunjukkan perubahan yang diperlukan untuk mengaktifkan fitur tertentu.

Langkah-langkah yang diperlukan untuk semua project

Selesaikan langkah-langkah dalam topik berikut, apa pun jenis fitur XR yang didukung project Anda. Setelah itu, tinjau fitur yang diuraikan dalam daftar langkah opsional untuk menentukan apakah project Anda memerlukan pekerjaan tambahan.

Mengupdate Godot dan Plugin Vendor Godot OpenXR

Ikuti langkah-langkah berikut untuk mengupdate project Anda ke versi terbaru yang diperlukan dan mengonfigurasi setelan project untuk Android XR:

  1. Update versi Godot Anda ke 4.6.2 atau yang lebih baru. Lihat dokumentasi tentang migrasi ke versi baru jika Anda memerlukan bantuan tambahan untuk project Anda.

  2. Download Plugin Vendor Godot OpenXR versi 5.1 atau yang lebih baru dari Asset Store, Asset Library atau repositori di GitHub.

  3. Konfigurasi setelan project Anda untuk Android XR:

    1. Tambahkan preset ekspor untuk Android XR.
    2. Aktifkan Use Gradle Build.

    Aktifkan

    1. Di bagian XR Features, pilih OpenXR untuk XR Mode, lalu pilih Enable AndroidXR Plugin.

    Konfigurasi opsi di

Menambahkan dukungan untuk pelacakan tangan

Meskipun pengontrol mungkin tersedia, metode input utama di headset Android XR dan kacamata XR adalah pelacakan tangan. Jika memungkinkan, Anda harus menambahkan dukungan pelacakan tangan ke project Godot Anda.

Menambahkan dukungan untuk pelacakan tangan: Mengonfigurasi setelan project

Pertama, ikuti langkah-langkah berikut untuk menyiapkan setelan project Anda guna mengaktifkan pelacakan tangan dan ekstensi OpenXR terkait.

  1. Buka setelan project Anda dan buka General > XR > OpenXR.

  2. Di bagian Extensions, pilih Hand Tracking dan Hand Interaction Profile.

    Konfigurasi opsi di

  3. Temukan subbagian Meta di bagian Extensions, lalu pilih Hand Tracking Mesh dan Hand Tracking Aim.

    Konfigurasi opsi di

Menambahkan dukungan untuk pelacakan tangan: Menambahkan dan mengonfigurasi node pengontrol

Daripada mengubah node XRController3D yang ada secara dinamis untuk pelacakan tangan, tambahkan node pengontrol untuk melacak dan menampilkan model tangan, serta menangani input dari ekstensi Hand Tracking Aim:

  1. Tambahkan tiga node XRController3D tambahan ke node XROrigin3D Anda.

    1. Beri nama satu "HandTrackingLeft", dan tetapkan properti pelacak ke /user/hand_tracker/left.
    2. Beri nama satu "HandTrackingRight", dan tetapkan properti pelacak ke /user/hand_tracker/right.
    3. Beri nama yang terakhir "HandTrackingAimLeft", dan tetapkan properti pelacak ke /user/fbhandaim/left.

    Jika node XRController3D asli project Anda diberi nama "XRController3D_left" dan "XRController3D_right", scene Anda akan terlihat seperti ini:

    Tampilan adegan Anda setelah menambahkan node pengontrol.

  2. Hubungkan sinyal tracking_changed di HandTrackingLeft dan HandTrackingRight ke fungsi individual yang memperbarui visibilitas pelacak pengontrol yang sesuai (XRController3D_left dan XRController3D_right dalam contoh sebelumnya).

    Misalnya, fungsi yang terhubung ke sinyal di HandTrackingLeft dapat terlihat seperti:

    func _on_hand_tracking_left_hand_tracking_changed(tracking):
    $XROrigin3D/XRController3D_left.visible = not tracking

  3. Aktifkan properti Show When Tracked di node pengontrol pelacakan tangan.

    Sekarang project Anda dapat bertukar secara visual antara model pengontrol dan model pelacakan tangan, bergantung pada apakah pengguna menggunakan pelacakan tangan atau pengontrol.

  4. Tambahkan beberapa node OpenXRFbHandTrackingMesh sebagai turunan ke node pengontrol pelacakan tangan Anda.

  5. Tambahkan node XRHandModifier3D sebagai turunan ke node OpenXRFbHandTrackingMesh ini, pastikan properti Hand Tracker yang benar ditetapkan, untuk menerapkan data pelacakan tangan real time ke model.

    Tampilan adegan Anda setelah menambahkan node turunan ke node pengontrol.

Menambahkan dukungan untuk pelacakan tangan: Menyiapkan profil Interaksi Tangan di Peta Tindakan OpenXR

Selanjutnya, Anda akan menyiapkan profil Hand Interaction di OpenXR Action Map:

  1. Buka menu OpenXR Action Map di bagian bawah editor.
  2. Hapus profil Simple Controller untuk menghindari masalah kompatibilitas dengan pengontrol Galaxy XR.
  3. Klik Add Profile, pilih Hand Interaction, lalu klik OK.

  4. Petakan profil ini ke satu atau beberapa set tindakan sesuai keinginan Anda.

Bergantung pada persyaratan aplikasi Anda, Anda mungkin juga ingin menyesuaikan cara aplikasi menangani input pengguna dengan pelacakan tangan.

Menambahkan dukungan untuk pelacakan tangan: Menyiapkan gestur menu untuk Android XR

Terakhir, Anda dapat menerapkan gestur menu untuk Android XR. Hal ini akan menampilkan ikon saat tangan kiri pemain berada di posisi yang benar untuk melakukan gestur menu, serta menampilkan atau menyembunyikan menu saat pengguna melakukan gestur. Anda akan menggunakan node HandTrackingAimLeft yang ditambahkan sebelumnya untuk menanganinya.

  1. Tambahkan quad billboard ke node pelacakan tangan kiri yang menampilkan ikon yang telah Anda pilih (lihat node MenuIcon pada gambar berikut dari node pengontrol yang Anda tambahkan sebelumnya).

    Tampilan adegan Anda setelah menambahkan node turunan ke node pengontrol.

  2. Hubungkan ke sinyal button_pressed dan button_released di HandTrackingAimLeft ke fungsi seperti ini:

    @onready var menu_icon: MeshInstance3D = $XROrigin3D/HandTrackingLeft/MenuIcon

func _on_hand_tracking_aim_left_button_pressed(p_name):
  if p_name == "menu_pressed":
toggle_menu()
  elif p_name == "menu_gesture":
    if OS.has_feature("androidxr"):
      menu_icon.visible = true

func _on_hand_tracking_aim_left_button_released(p_name):
  if p_name == "menu_gesture":
    menu_icon.visible = false

Langkah-langkah opsional untuk fitur tertentu

Setelah menyelesaikan langkah-langkah yang diperlukan untuk project Anda, Anda dapat memutuskan apakah perlu melakukan pekerjaan tambahan untuk fitur tertentu, bergantung pada persyaratan dan kemampuan aplikasi Anda. Untuk mengetahui informasi selengkapnya tentang setiap fitur opsional ini, lihat bagian berikut.

Mendaftarkan gerakan mencubit sebagai penekanan tombol

Di Android XR, gerakan mencubit digunakan untuk banyak tindakan sistem dasar, seperti memilih item, men-scroll, memindahkan atau mengubah ukuran jendela, dan memindahkan elemen atau objek UI di ruang 2D dan 3D. Untuk menyelaraskan dengan pola ini dan meningkatkan pengalaman pengguna yang konsisten, aplikasi Anda harus mendaftarkan gerakan mencubit dengan cara yang sama seperti penekanan tombol pada pengontrol saat menggunakan pelacakan tangan.

Untuk mengonfigurasi aplikasi Anda dengan cara ini, gunakan nilai float yang disediakan oleh profil Interaksi Tangan yang Anda buat untuk membuat tindakan virtual:

const PRESSED_THRESHOLD := 0.8
const RELEASED_THRESHOLD := 0.6

@onready var left_controller: XRController3D = $XROrigin/XRController3D_left

func _on_xr_controller_3d_left_input_float_changed(p_name: String, value: float):
    if p_name == "pinch":
        var xr_tracker = XRServer.get_tracker(left_controller.tracker)
        if _left_hand_pinching:
            if value < RELEASED_THRESHOLD:
                _left_hand_pinching = false
                xr_tracker.set_input("pinch_pressed", false)
        else:
            if value > PRESSED_THRESHOLD:
                _left_hand_pinching = true
                xr_tracker.set_input("pinch_pressed", true)

Poin-poin penting tentang kode

  • Memeriksa apakah nilai float lebih besar atau lebih kecil dari nilai minimum tertentu dalam sinyal XRController3D input_float_changed.
  • Membuat tindakan virtual yang disebut pinch_pressed.

Menggunakan fungsi Alat XR bersama dengan pelacakan tangan

Banyak project Godot XR menggunakan Alat XR Godot, termasuk beberapa project open source yang ditautkan di halaman ini. Agar beberapa fungsi Alat XR berfungsi, seperti FunctionPointer untuk interaksi menu, Anda memerlukan beberapa kode tambahan untuk menukar tindakan yang dicari saat pengguna beralih ke pelacakan tangan.

Misalnya, saat menggunakan FunctionPointer untuk interaksi menu, perbarui properti active_button_action ke tindakan pelacakan tangan berdasarkan sinyal tracking_changed dari node XRController3D untuk pelacakan tangan (node ini adalah HandTrackingLeft dan HandTrackingRight dalam langkah penyiapan pelacakan tangan sebelumnya).

const TRIGGER_POINTER_ACTION = "trigger_click"
const PINCH_POINTER_ACTION = "pinch_pressed"

@onready var func_point_left: XRToolsFunctionPointer = %FunctionPointerLeft

func _on_hand_tracking_left_tracking_changed(tracking: bool) -> void:
    if tracking:
        func_point_left.active_button_action = PINCH_POINTER_ACTION
else:
func_point_left.active_button_action = TRIGGER_POINTER_ACTION

Poin-poin penting tentang kode

Menggunakan pelacakan tangan bersama dengan lokomosi buatan

Jika project Anda menggunakan lokomosi buatan, dukungan pelacakan tangan masih memungkinkan. Misalnya, Anda dapat membuat sistem gerakan yang memungkinkan pemain menggambar jalur untuk dilalui dengan gestur, atau Anda dapat mengizinkan pemain menggerakkan tangan ke atas dan ke bawah untuk mempercepat, dengan gestur tambahan untuk melompat, memanjat, dan meluncur.

Museum of All Things memiliki lokomosi buatan menggunakan thumbstick pada pengontrol. Lokomosi pelacakan tangan diterapkan dengan menambahkan "thumbstick virtual" yang dipicu pemain dengan mencubit di udara, dan menggerakkan tangan ke arah yang diinginkan thumbstick tersebut.

Berikut beberapa poin penting dari permintaan pull yang menerapkan dukungan ini:

  • Scene XRVirtualThumbstick dibuat instance-nya saat gerakan mencubit terdeteksi.
  • Saat gerakan mencubit ditahan, jarak dan arah relatif dari lokasi gerakan mencubit asli akan diubah menjadi Vector2 dan dipetakan secara virtual ke input thumbstick normal.
  • Masukan visual dari input ini juga diberikan kepada pemain dalam bentuk dua mesh quad billboard, yang menggambarkan posisi thumbstick.

Anda dapat mencoba pendekatan serupa untuk membuat kode lokomosi berbasis thumbstick yang ada berfungsi dengan perubahan minimal. Namun, project Anda mungkin masih memerlukan solusi lokomosi kustom untuk pelacakan tangan.

Menambahkan dukungan passthrough

Anda dapat menambahkan dukungan passthrough ke aplikasi sehingga pengguna dapat melihat lingkungan dunia nyata mereka.

Untuk melakukannya di aplikasi Anda, lakukan perubahan kode berikut:

  • Tetapkan environment_blend_mode OpenXR XRInterface ke XR_ENV_BLEND_MODE_ALPHA_BLEND.
  • Tetapkan background_mode node WorldEnvironment ke BG_COLOR.
  • Tetapkan background_color node WorldEnvironment ke warna apa pun yang sepenuhnya transparan.
  • Tetapkan properti Viewport transparent_bg ke true.

Menggunakan ekstensi estimasi cahaya

Saat mengaktifkan passthrough, pertimbangkan untuk menggunakan ekstensi OpenXR Estimasi Cahaya Android XR. Ekstensi ini mengubah properti WorldEnvironment dan DirectionalLight3D untuk meniru pencahayaan lingkungan dunia nyata pengguna dengan lebih baik, sehingga objek virtual dapat berbaur dengan lebih baik dengan kondisi pencahayaan dunia nyata. Anda dapat mengaktifkan ekstensi ini di setelan project Anda.

  1. Buka setelan project Anda dan buka General > XR > OpenXR.

  2. Di bagian Androidxr, pilih Light Estimation.

    Konfigurasi opsi di

  3. Tambahkan node OpenXRAndroidLightEstimation ke pohon scene Anda dan hubungkan ke WorldEnvironment dan DirectionalLight3D scene Anda.

    Opsi untuk

Contoh: Mengaktifkan atau menonaktifkan passthrough dan estimasi cahaya

Kode berikut mengaktifkan atau menonaktifkan passthrough dan estimasi cahaya:

@onready var world_environment = $WorldEnvironment
@onready var directional_light = $DirectionalLight3D
@onready var directional_light_orig_transform: Transform3D = directional_light.transform

func set_passthrough_enabled(p_enabled: bool) -> void:
    var xr_interface = XRServer.find_interface("OpenXR")
    if xr_interface == null:
        return

    var supported_blend_modes = xr_interface.get_supported_environment_blend_modes()
    if not supported_blend_modes.has(XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND):
        return

    # Passthrough
    if p_enabled:
        xr_interface.set_play_area_mode(XRInterface.XR_PLAY_AREA_STAGE)
        xr_interface.environment_blend_mode = XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND
        world_environment.environment.background_mode = Environment.BG_COLOR
        world_environment.environment.background_color = Color(0.0, 0.0, 0.0, 0.0)
        get_viewport().transparent_bg = true
    else:
        xr_interface.set_play_area_mode(XRInterface.XR_PLAY_AREA_ROOMSCALE)
        xr_interface.environment_blend_mode = XRInterface.XR_ENV_BLEND_MODE_OPAQUE
        world_environment.environment.background_mode = Environment.BG_SKY
        get_viewport().transparent_bg = false

    # Light Estimation
    if OS.has_feature("androidxr"):
        var light_estimation = Engine.get_singleton("OpenXRAndroidLightEstimationExtension")
        if p_enabled and light_estimation.is_light_estimation_supported():
            light_estimation.start_light_estimation()
        elif light_estimation.is_light_estimation_started():
            light_estimation.stop_light_estimation()
            directional_light.transform = directional_light_orig_transform
Poin-poin penting tentang kode
  • Saat menonaktifkan estimasi cahaya, arah asli DirectionalLight3D harus dipulihkan secara manual.
  • Untuk contoh lengkap project yang menggunakan passthrough dan Estimasi Cahaya, lihat Expedition to Blobotopia di GitLab.