Menggunakan Spatial Container di Godot

Perangkat XR yang kompatibel

Panduan ini membantu Anda membangun pengalaman untuk jenis perangkat XR ini.

Mempelajari jenis perangkat XR →

Mempelajari jenis perangkat XR →

Penampung Spasial memungkinkan aplikasi Anda merender konten OpenXR 3D di dalam kotak pembatas volumetrik 3D yang dikelola sistem dalam Mode Ruang Penuh, atau bertransisi saat runtime ke pengalaman layar penuh tanpa batas.

Ikuti panduan ini untuk mengonfigurasi dan menggunakan Spatial Containers dalam project Anda.

Cara kerja Penampung Spasial

Saat Anda mengaktifkan Penampung Spasial di setelan project:

• Seluruh scene 3D aktif Anda ditempatkan di dalam satu penampung spasial utama yang berpusat di origin scene (0, 0, 0). Anda tidak perlu memberi tag atau menetapkan node Node3D satu per satu untuk menempatkannya di dalam container.
• Aplikasi Anda diluncurkan ke Mode Ruang Penuh terkelola menggunakan Mode Batas (Bounded atau Immersive) dan dimensi Batas awal yang dikonfigurasi di setelan project Anda. Dalam mode terbatas, sistem akan otomatis memangkas geometri 3D apa pun dalam tampilan Anda yang melampaui dimensi kotak pembatas.
• Secara default, sistem Android XR menyediakan kontrol jendela sehingga pengguna dapat mengambil, memindahkan, dan memosisikan ulang penampung terbatas dalam ruang 3D, atau meminimalkan dan menutupnya. Saat runtime, aplikasi Anda dapat mengubah ukuran container, beralih antara mode terbatas (OpenXRSpatialContainerState.BOUNDED) dan mode imersif layar penuh (OpenXRSpatialContainerState.IMMERSIVE), serta bereaksi terhadap perubahan batas dan status menggunakan singleton OpenXRSpatialContainerExtension.

Prasyarat

Sebelum memulai, pastikan lingkungan pengembangan dan perangkat target Anda memenuhi persyaratan berikut:

• Versi Godot: Godot 4.8-dev atau yang lebih tinggi.
• Penyiapan project: Selesaikan semua langkah dalam panduan Penyiapan project Godot Engine.
• Plugin Vendor Godot OpenXR: Instal versi 5.2 atau yang lebih tinggi dari Plugin Vendor Godot OpenXR, yang memungkinkan dukungan untuk ekstensi khusus Android XR.
• Perangkat target: Perangkat Android XR yang mendukung Spatial API Level 4 atau yang lebih tinggi. Saat runtime, panggil OpenXRSpatialContainerExtension.is_enabled() untuk memverifikasi apakah ekstensi tersedia di perangkat.

Mengaktifkan Penampung Spasial di setelan project

Konfigurasikan setelan project Anda untuk mengaktifkan OpenXR, Spatial Containers, izin runtime otomatis, dan passthrough alpha-blended:

1. Buka Project > Setelan project.
2. Aktifkan tombol Advanced Settings di pojok kanan atas jendela setelan project.
3. Buka General > XR > Shaders, lalu pilih Enabled.
4. Buka General > XR > OpenXR dan konfigurasikan setelan berikut:
   • Pilih Enabled untuk mengaktifkan OpenXR untuk project.
   • Setel Environment Blend Mode ke Alpha Blend.
5. Masih di bagian OpenXR, buka bagian Extensions, lalu konfigurasikan setelan berikut:
   • Pilih Automatically Request Runtime Permissions agar aplikasi Anda otomatis meminta izin runtime XR kepada pengguna saat sistem dimulai, yang dideklarasikan dalam manifes Android Anda.
   • Di subbagian Penampung Spasial, pilih Diaktifkan.
   • Setel Bounds Mode ke Bounded untuk meluncurkan dalam kotak pembatas 3D, atau Immersive untuk meluncurkan dalam mode imersif layar penuh.
   • Tetapkan Bounds ke dimensi lebar, tinggi, dan kedalaman awal dalam meter, seperti Vector3(1.0, 1.0, 1.0).
6. Buka General > Rendering > Viewport, lalu pilih Transparent Background.

Mengonfigurasi ekspor, izin, dan Mode Ruang Penuh Android

Selanjutnya, konfigurasikan preset ekspor, izin, dan mode mulai aktivitas Android Anda agar aplikasi berjalan dalam Mode Ruang Penuh dengan Spatial Container diaktifkan.

Mengonfigurasi preset ekspor Android

1. Buka Project > Export..., lalu pilih preset ekspor Android.

2. Di bagian Gradle Build, pilih Use Gradle Build dan tetapkan Min SDK ke 34 atau yang lebih tinggi.

   

3. Di bagian XR Features, tetapkan XR Mode ke OpenXR, lalu pilih Enable AndroidXR Plugin.

   

4. Di bagian Android XR Features, pilih Use Experimental Features.

Menambahkan izin pemahaman scene untuk penguncian lantai

Membuat dan merender penampung spasial dasar tidak memerlukan izin runtime yang berbahaya (dan android.permission.HEAD_TRACKING ditambahkan ke manifes secara otomatis saat Gunakan Fitur Eksperimental diaktifkan). Namun, jika aplikasi Anda menggunakan fitur pemahaman scene seperti mengunci dan menambatkan container spasial ke lantai fisik, aplikasi Anda harus mendeklarasikan dan meminta izin android.permission.SCENE_UNDERSTANDING_COARSE saat runtime.

Lihat Memahami izin untuk XR untuk mengetahui detail tentang izin Android XR. Jika aplikasi Anda menggunakan penguncian lantai atau pemahaman scene, deklarasikan dan minta android.permission.SCENE_UNDERSTANDING_COARSE:

1. Di Project > Export... > Android, buka Permissions > Custom Permissions, lalu tambahkan android.permission.SCENE_UNDERSTANDING_COARSE.

2. Saat Anda memilih Automatically Request Runtime Permissions di Project Settings > General > XR > OpenXR > Extensions, aplikasi Anda akan otomatis meminta izin saat OpenXR dimulai. Jika Anda perlu meminta izin secara manual di GDScript, panggil OS.request_permission():

   if not OS.get_granted_permissions().has("android.permission.SCENE_UNDERSTANDING_COARSE"):
       OS.request_permission("android.permission.SCENE_UNDERSTANDING_COARSE")
   

Mengonfigurasi Mode Ruang Penuh

Penampung Spasial di Android XR hanya mendukung Mode Ruang Penuh (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED). Pastikan aktivitas Android Anda mendeklarasikan XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED di template build kustom Anda (android/build/AndroidManifest.xml, diinstal menggunakan Project > Install Android Build Template...):

<manifest ...>
    <application ...>
        <property
            android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
            android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED"
            tools:replace="android:value" />
        ...
    </application>
</manifest>

Menggunakan Spatial Container di GDScript

Singleton OpenXRSpatialContainerExtension dan class OpenXRSpatialContainerState mengekspos ekstensi XR_EXT_spatial_container dan XR_EXT_spatial_container_self_rendering ke GDScript. Saat runtime, gunakan OpenXRSpatialContainerExtension untuk memeriksa status dan batas penampung spasial utama, memproses sinyal penampung, dan meminta transisi antara mode BOUNDED (kotak pembatas 3D) dan mode IMMERSIVE (tampilan layar penuh tanpa batas).

Menghubungkan ke sinyal Spatial Container

Periksa OpenXRSpatialContainerExtension.is_enabled() untuk memastikan bahwa ekstensi Penampung Spasial didukung dan aktif di perangkat saat ini, serta hubungkan ke batas penampung dan sinyal status di _ready().

OpenXRSpatialContainerExtension memunculkan sinyal status berikut untuk penampung spasial:

• spatial_container_visibility_changed: Dipancarkan dengan (spatial_container, is_visible) saat penampung ditampilkan (true) atau disembunyikan (false). Jeda animasi, audio, atau update simulasi saat is_visible adalah false.
• spatial_container_interactability_changed: Dipancarkan dengan (spatial_container, is_interactive) saat penampung mendapatkan (true) atau kehilangan (false) fokus input pengguna. Mengaktifkan atau menonaktifkan penanda interaktif dan penanganan input saat fokus berubah.
• spatial_container_bounds_mode_changed: Dipancarkan dengan (spatial_container, bounds_mode) saat penampung beralih antara OpenXRSpatialContainerState.BOUNDED dan OpenXRSpatialContainerState.IMMERSIVE. Mengalihkan visual lingkungan (seperti skybox atau passthrough) dan kontrol UI khusus mode.

func _ready() -> void:
    if OpenXRSpatialContainerExtension.is_enabled():
        OpenXRSpatialContainerExtension.spatial_container_bounds_changed.connect(
            _on_bounds_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_bounds_mode_changed.connect(
            _on_bounds_mode_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_visibility_changed.connect(
            _on_visibility_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_interactability_changed.connect(
            _on_interactability_changed
        )

func _on_visibility_changed(_rid: RID, is_visible: bool) -> void:
    # Pause or resume simulation and audio based on visibility
    pass

func _on_interactability_changed(_rid: RID, is_interactive: bool) -> void:
    # Enable or disable input handling and focus highlights
    pass

Menskalakan konten 3D ke batas penampung

Saat dalam mode BOUNDED, skalakan konten 3D Anda secara seragam berdasarkan dimensi terkecil bounds sehingga mempertahankan rasio aspeknya dan selalu pas di dalam sisi terkecil penampung. Saat beralih ke mode IMMERSIVE, pulihkan tampilan Anda ke skala 1:1:

func _on_bounds_changed(_rid: RID, bounds: Vector3) -> void:
    var uniform_scale: float = min(bounds.x, bounds.y, bounds.z)
    content_root.scale = Vector3.ONE * uniform_scale

func _on_bounds_mode_changed(
    _rid: RID, bounds_mode: OpenXRSpatialContainerState.BoundsMode
) -> void:
    if bounds_mode == OpenXRSpatialContainerState.IMMERSIVE:
        content_root.scale = Vector3.ONE

Beralih antara mode terbatas dan imersif

Panggil request_main_spatial_container_bounds_mode dengan OpenXRSpatialContainerState.BOUNDED atau OpenXRSpatialContainerState.IMMERSIVE untuk beralih antara volume 3D terbatas dan tampilan imersif layar penuh:

# Request transitioning to immersive mode (or pass BOUNDED to return)
OpenXRSpatialContainerExtension.request_main_spatial_container_bounds_mode(
    OpenXRSpatialContainerState.IMMERSIVE
)

Lihat juga

• Membangun dengan Spatial Containers
• Memahami izin untuk XR
• Menambahkan dukungan untuk Android XR ke project Godot XR yang ada

OpenXR™ dan logo OpenXR adalah merek dagang yang dimiliki oleh The Khronos Group Inc. dan terdaftar sebagai merek dagang di China, Uni Eropa, Jepang, dan Inggris Raya.