Utilizza i container spaziali in Godot

Dispositivi XR applicabili

Queste indicazioni ti aiutano a creare esperienze per questi tipi di dispositivi XR.

Scopri di più sui tipi di dispositivi XR →

Scopri di più sui tipi di dispositivi XR →

I container spaziali consentono alla tua app di eseguire il rendering di contenuti OpenXR 3D all'interno di un riquadro di delimitazione volumetrico 3D gestito dal sistema in modalità spazio intero o di passare in fase di runtime a un'esperienza a schermo intero senza limiti.

Segui questa guida per configurare e utilizzare i container spaziali nel tuo progetto.

Come funzionano i container spaziali

Quando attivi Spatial Container nelle impostazioni progetto:

• L'intera scena 3D attiva viene posizionata all'interno di un unico contenitore spaziale principale centrato sull'origine della scena (0, 0, 0). Non è necessario taggare o assegnare singoli nodi Node3D per inserirli nel container.
• L'app si avvia in modalità spazio intero gestito utilizzando la modalità limiti (Bounded o Immersive) e le dimensioni iniziali dei limiti configurate nelle impostazioni progetto. In modalità delimitata, il sistema ritaglia automaticamente qualsiasi geometria 3D della scena che si estende oltre le dimensioni del riquadro di delimitazione.
• Per impostazione predefinita, il sistema Android XR fornisce controlli della finestra in modo che l'utente possa afferrare, spostare e riposizionare il container delimitato nello spazio 3D o ridurlo a icona e chiuderlo. In fase di runtime, l'app può ridimensionare il container, passare dalla modalità limitata (OpenXRSpatialContainerState.BOUNDED) alla modalità immersiva a schermo intero (OpenXRSpatialContainerState.IMMERSIVE) e reagire alle modifiche dei limiti e dello stato utilizzando il singleton OpenXRSpatialContainerExtension.

Prerequisiti

Prima di iniziare, assicurati che l'ambiente di sviluppo e il dispositivo di destinazione soddisfino i seguenti requisiti:

• Versione di Godot: Godot 4.8-dev o versioni successive.
• Configurazione del progetto: completa tutti i passaggi della guida alla configurazione del progetto Godot Engine.
• Plug-in Godot OpenXR Vendors: installa la versione 5.2 o successive del plug-in Godot OpenXR Vendors, che abilita il supporto delle estensioni specifiche di Android XR.
• Dispositivo di destinazione: un dispositivo Android XR che supporta il livello API Spatial 4 o versioni successive. In fase di runtime, chiama OpenXRSpatialContainerExtension.is_enabled() per verificare se l'estensione è disponibile sul dispositivo.

Abilita i container spaziali nelle impostazioni progetto

Configura le impostazioni del progetto per abilitare OpenXR, i container spaziali, le autorizzazioni di runtime automatiche e il passthrough con alpha blending:

1. Apri Project > Project Settings (Progetto > Impostazioni progetto).
2. Attiva l'opzione Impostazioni avanzate nell'angolo in alto a destra della finestra Impostazioni progetto.
3. Vai a Generali > XR > Shader e seleziona Attivato.
4. Vai a General (Generali) > XR > OpenXR e configura le seguenti impostazioni:
   • Seleziona Enabled (Attivato) per attivare OpenXR per il progetto.
   • Imposta Environment Blend Mode (Modalità fusione ambiente) su Alpha Blend (Fusione alfa).
5. Sempre in OpenXR, vai alla sezione Extensions (Estensioni) e configura le seguenti impostazioni:
   • Seleziona Automatically Request Runtime Permissions (Richiedi automaticamente le autorizzazioni di runtime) in modo che l'app chieda automaticamente all'utente all'avvio le autorizzazioni XR dichiarate nel manifest Android.
   • Nella sottosezione Contenitore spaziale, seleziona Attivato.
   • Imposta Bounds Mode (Modalità limiti) su Bounded (Limitata) per l'avvio in un riquadro di delimitazione 3D o su Immersive (Immersiva) per l'avvio in modalità immersiva a schermo intero.
   • Imposta Limiti sulle dimensioni iniziali di larghezza, altezza e profondità in metri, ad esempio Vector3(1.0, 1.0, 1.0).
6. Vai a General (Generali) > Rendering > Viewport e seleziona Transparent Background (Sfondo trasparente).

Configura l'esportazione, le autorizzazioni e la modalità Spazio intero per Android

Successivamente, configura il preset di esportazione, le autorizzazioni e la modalità di avvio dell'attività di Android in modo che l'app venga eseguita in modalità Spazio intero con i container spaziali attivati.

Configura il preset di esportazione per Android

1. Vai a Project > Export… (Progetto > Esporta…) e seleziona il preset di esportazione Android.

2. In Gradle Build, seleziona Use Gradle Build e imposta Min SDK su 34 o versioni successive.

   

3. In Funzionalità XR, imposta Modalità XR su OpenXR e seleziona Attiva il plug-in AndroidXR.

   

4. In Funzionalità di Android XR, seleziona Utilizza funzionalità sperimentali.

Aggiungi le autorizzazioni di comprensione della scena per il blocco del pavimento

La creazione e il rendering di un container spaziale di base non richiedono autorizzazioni di runtime pericolose (e android.permission.HEAD_TRACKING viene aggiunto automaticamente al manifest quando è attiva l'opzione Utilizza funzionalità sperimentali). Tuttavia, se la tua app utilizza funzionalità di comprensione della scena, come il blocco e l'ancoraggio di un contenitore spaziale al pavimento fisico, deve dichiarare e richiedere l'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE in fase di runtime.

Per informazioni dettagliate sulle autorizzazioni di Android XR, consulta Informazioni sulle autorizzazioni per XR. Se la tua app utilizza il blocco del pavimento o la comprensione della scena, dichiara e richiedi android.permission.SCENE_UNDERSTANDING_COARSE:

1. In Progetto > Esporta… > Android, vai a Autorizzazioni > Autorizzazioni personalizzate e aggiungi android.permission.SCENE_UNDERSTANDING_COARSE.

2. Quando selezioni Richiedi automaticamente le autorizzazioni di runtime in Impostazioni progetto > Generali > XR > OpenXR > Estensioni, l'app richiede automaticamente l'autorizzazione all'avvio di OpenXR. Se invece devi richiedere l'autorizzazione manualmente in GDScript, chiama OS.request_permission():

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

Configura la modalità Spazio intero

I container spaziali su Android XR supportano solo la modalità spazio intero (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED). Assicurati che l'attività Android dichiari XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED nel modello di build personalizzato (android/build/AndroidManifest.xml, installato utilizzando 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>

Lavora con i container spaziali in GDScript

Il singleton OpenXRSpatialContainerExtension e la classe OpenXRSpatialContainerState espongono le estensioni XR_EXT_spatial_container e XR_EXT_spatial_container_self_rendering a GDScript. In fase di runtime, utilizza OpenXRSpatialContainerExtension per ispezionare lo stato e i limiti del container spaziale principale, ascoltare i segnali del container e richiedere transizioni tra la modalità BOUNDED (un riquadro di delimitazione 3D) e la modalità IMMERSIVE (una visualizzazione illimitata a schermo intero).

Connettiti agli indicatori di Spatial Container

Controlla OpenXRSpatialContainerExtension.is_enabled() per verificare che l'estensione Spatial Container sia supportata e attiva sul dispositivo corrente e connettiti ai segnali di stato e ai limiti del container in _ready().

OpenXRSpatialContainerExtension emette i seguenti indicatori di stato per il container spaziale:

• spatial_container_visibility_changed: viene emesso con (spatial_container, is_visible) quando il container viene mostrato (true) o nascosto (false). Metti in pausa le animazioni, l'audio o gli aggiornamenti della simulazione quando is_visible è false.
• spatial_container_interactability_changed: attivato con (spatial_container, is_interactive) quando il container acquisisce (true) o perde (false) lo stato attivo dell'input utente. Attiva o disattiva l'evidenziazione interattiva e la gestione degli input quando lo stato attivo cambia.
• spatial_container_bounds_mode_changed: attivato con (spatial_container, bounds_mode) quando il container passa da OpenXRSpatialContainerState.BOUNDED a OpenXRSpatialContainerState.IMMERSIVE. Attiva/disattiva gli elementi visivi dell'ambiente (come skybox o passthrough) e i controlli UI specifici della modalità.

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

Scala i contenuti 3D in base ai limiti del contenitore

In modalità BOUNDED, scala i contenuti 3D in modo uniforme in base alla dimensione più piccola di bounds, in modo da preservare le proporzioni e adattarli sempre al lato più piccolo del contenitore. Quando passi alla modalità IMMERSIVE, ripristina la scala 1:1 della scena:

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

Passa dalla modalità delimitata a quella immersiva e viceversa

Chiama request_main_spatial_container_bounds_mode con OpenXRSpatialContainerState.BOUNDED o OpenXRSpatialContainerState.IMMERSIVE per passare da un volume 3D delimitato a una visualizzazione immersiva a schermo intero:

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

Vedi anche

• Crea con i container spaziali
• Informazioni sulle autorizzazioni per XR
• Aggiungi il supporto di Android XR a un progetto Godot XR esistente

OpenXR™ e il logo OpenXR sono marchi di proprietà di The Khronos Group Inc. e sono registrati come marchi in Cina, nell'Unione Europea, in Giappone e nel Regno Unito.