Aggiungere il supporto di Android XR a un progetto Godot XR esistente

Dispositivi XR applicabili
Queste indicazioni ti aiutano a creare esperienze per questi tipi di dispositivi XR.
Scopri di più sui tipi di dispositivi XR →
Visori XR
Occhiali XR con cavo
Scopri di più sui tipi di dispositivi XR →

Se hai un progetto XR esistente in Godot, puoi aggiungere il supporto per Android XR senza avviare un nuovo progetto separato. Alcuni passaggi sono obbligatori per tutti i progetti, mentre altri sono facoltativi a seconda delle funzionalità XR utilizzate dal progetto. Nel corso dei passaggi, abbiamo incluso link a più progetti Godot XR open source che hanno aggiunto il supporto per Android XR, insieme a pull request pertinenti che mostrano le modifiche necessarie per abilitare determinate funzionalità.

Passaggi obbligatori per tutti i progetti

Completa i passaggi descritti negli argomenti seguenti, indipendentemente dai tipi di funzionalità XR supportati dal tuo progetto. Dopodiché, esamina le funzionalità descritte nell'elenco dei passaggi facoltativi per determinare se il tuo progetto richiede un lavoro aggiuntivo.

Aggiornare Godot e il plug-in Godot OpenXR Vendors

Segui questi passaggi per aggiornare il progetto alle versioni richieste più recenti e configurare le impostazioni del progetto per Android XR:

  1. Aggiorna Godot alla versione 4.6.2 o successive. Consulta la documentazione sulla migrazione a una nuova versione se hai bisogno di ulteriore assistenza per il tuo progetto.

  2. Scarica la versione 5.1 o successive del plug-in Godot OpenXR Vendors dall'Asset Store, dalla libreria di asset o dal repository su GitHub.

  3. Configura le impostazioni del progetto per Android XR:

    1. Aggiungi un preset di esportazione per Android XR.
    2. Attiva Usa build Gradle.

    Attiva

    1. Nella sezione Funzionalità XR, seleziona OpenXR per la Modalità XR e seleziona Attiva plug-in AndroidXR.

    Configura le opzioni in

Aggiungere il supporto per il tracciamento delle mani

Sebbene i controller possano essere disponibili, il metodo di immissione principale sui visori e sugli occhiali Android XR è il tracciamento delle mani. Se possibile, dovresti aggiungere il supporto del tracciamento delle mani al tuo progetto Godot.

Aggiungere il supporto per il tracciamento delle mani: configura le impostazioni del progetto

Innanzitutto, segui questi passaggi per configurare le impostazioni progetto in modo da attivare il tracciamento della mano e le relative estensioni OpenXR.

  1. Apri le impostazioni del progetto e vai a Generali > XR > OpenXR.

  2. Nella sezione Estensioni, seleziona Rilevamento della mano e Profilo di interazione con le mani.

    Configura le opzioni in

  3. Trova la sottosezione Meta nella sezione Estensioni e seleziona Mesh del tracciamento della mano e Puntamento del tracciamento della mano.

    Configura le opzioni in

Aggiungere il supporto del tracciamento della mano: aggiungi e configura i nodi del controller

Anziché modificare dinamicamente i nodi XRController3D esistenti per il tracciamento delle mani, aggiungi nodi del controller per tracciare e visualizzare i modelli delle mani, nonché per gestire l'input dall'estensione Hand Tracking Aim:

  1. Aggiungi altri tre nodi XRController3D al nodo XROrigin3D.

    1. Assegna il nome "HandTrackingLeft" e imposta la proprietà del tracker su /user/hand_tracker/left.
    2. Assegna un nome a un altro "HandTrackingRight" e imposta la proprietà del tracker su /user/hand_tracker/right.
    3. Assegna all'ultimo il nome "HandTrackingAimLeft" e imposta la proprietà del tracker su /user/fbhandaim/left.

    Se i nodi XRController3D originali del tuo progetto erano denominati "XRController3D_left" e "XRController3D_right", la scena avrebbe un aspetto simile a questo:

    Come potrebbe apparire la scena dopo aver aggiunto i nodi del controller.

  2. Collega il segnale tracking_changed su HandTrackingLeft e HandTrackingRight a singole funzioni che aggiornano la visibilità dei tracker dei controller corrispondenti (XRController3D_left e XRController3D_right nell'esempio precedente).

    Ad esempio, la funzione connessa al segnale su HandTrackingLeft potrebbe essere simile a questa:

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

  3. Attiva la proprietà Mostra quando tracciato sui nodi del controller di tracciamento della mano.

    Ora il tuo progetto può passare visivamente da un modello di controller a un modello di tracciamento delle mani, a seconda che l'utente utilizzi il tracciamento delle mani o i controller.

  4. Aggiungi alcuni nodi OpenXRFbHandTrackingMesh come figli ai nodi del controller di tracciamento delle mani.

  5. Aggiungi nodi XRHandModifier3D come figli di questi nodi OpenXRFbHandTrackingMesh, assicurandoti che sia impostata la proprietà Hand Tracker corretta, per applicare i dati di tracciamento delle mani in tempo reale ai modelli.

    Come potrebbe apparire la scena dopo aver aggiunto i nodi secondari ai nodi del controller.

Aggiungi il supporto per il tracciamento delle mani: configura un profilo di interazione manuale nella mappa delle azioni OpenXR

Successivamente, configurerai il profilo Interazione con le mani nella mappa delle azioni OpenXR:

  1. Apri il menu OpenXR Action Map nella parte inferiore dell'editor.
  2. Elimina il profilo Simple Controller per evitare problemi di compatibilità con i controller Galaxy XR.
  3. Fai clic su Aggiungi profilo, seleziona Interazione con le mani e poi fai clic su Ok.

  4. Mappa questo profilo a uno o più set di azioni come preferisci.

A seconda dei requisiti della tua app, potresti anche voler modificare il modo in cui l'app gestisce l'input utente con il tracciamento delle mani.

Aggiungere il supporto per il tracciamento delle mani: configura un gesto del menu per Android XR

Infine, puoi implementare un gesto del menu per Android XR. Mostra un'icona quando la mano sinistra del giocatore si trova nella posizione corretta per eseguire il gesto del menu, nonché mostra o nasconde il menu quando l'utente esegue il gesto. Per gestire questa operazione, utilizzerai il nodo HandTrackingAimLeft che hai aggiunto in precedenza.

  1. Aggiungi un quad pubblicitario al nodo di tracciamento delle mani a sinistra che mostra un'icona che hai scelto (vedi il nodo MenuIcon nell'immagine seguente dei nodi del controller che hai aggiunto in precedenza).

    Come potrebbe apparire la scena dopo aver aggiunto i nodi secondari ai nodi del controller.

  2. Connettiti ai segnali button_pressed e button_released su HandTrackingAimLeft a funzioni come questa:

    @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

Passaggi facoltativi per alcune funzionalità

Dopo aver completato i passaggi richiesti per il tuo progetto, decidi se devi svolgere un lavoro aggiuntivo per determinate funzionalità, a seconda dei requisiti e delle funzionalità della tua app. Per ulteriori informazioni su ciascuna di queste funzionalità opzionali, consulta le sezioni seguenti.

Registrare i pizzichi come pressioni dei pulsanti

In Android XR, il pizzico viene utilizzato per molte azioni di base del sistema, ad esempio per selezionare elementi, scorrere, spostare o ridimensionare finestre e spostare elementi o oggetti dell'interfaccia utente nello spazio 2D e 3D. Per allinearsi a questi pattern e promuovere un'esperienza utente coerente, la tua app deve registrare i pizzichi in modo simile alla pressione dei pulsanti su un controller quando si utilizza il tracciamento delle mani.

Per configurare l'app in questo modo, utilizza i valori float forniti dal profilo di interazione con le mani che hai creato per creare un'azione virtuale:

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)

Punti chiave sul codice

  • Controlla se il valore di float è maggiore o minore di soglie specifiche negli indicatori XRController3D input_float_changed.
  • Crea un'azione virtuale denominata pinch_pressed.

Utilizzare le funzioni di XR Tools insieme al tracciamento delle mani

Molti progetti Godot XR utilizzano Godot XR Tools, inclusi alcuni dei progetti open source collegati in questa pagina. Per il funzionamento di alcune funzioni di XR Tools, ad esempio FunctionPointer per le interazioni con il menu, è necessario un codice aggiuntivo per scambiare l'azione che cerca quando l'utente passa al tracciamento delle mani.

Ad esempio, quando utilizzi FunctionPointer per le interazioni con i menu, aggiorna la proprietà active_button_action all'azione di tracciamento delle mani in base all'indicatore tracking_changed dei nodi XRController3D per il tracciamento delle mani (questi nodi erano HandTrackingLeft e HandTrackingRight nei precedenti passaggi di configurazione del tracciamento delle mani).

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

Punti chiave sul codice

Utilizzare il tracciamento della mano insieme al movimento artificiale

Se il tuo progetto utilizza la locomozione artificiale, il supporto del tracciamento della mano è comunque possibile. Ad esempio, puoi creare un sistema di movimento che consenta ai giocatori di disegnare percorsi da attraversare con un gesto oppure puoi consentire ai giocatori di muovere le mani su e giù per accelerare, con gesti aggiuntivi per saltare, arrampicarsi e planare.

The Museum of All Things, ha una locomozione artificiale che utilizza i thumbstick sui controller. La locomozione con il tracciamento delle mani è stata implementata aggiungendo "levette virtuali" che il giocatore attiva pizzicando l'aria e muovendo la mano nella direzione in cui vuole che si muova la levetta.

Ecco alcuni dei punti chiave della richiesta di pull che ha implementato questo supporto:

  • Una scena XRVirtualThumbstick viene istanziata quando viene rilevato il pizzico.
  • Mentre il pizzico è mantenuto, la distanza e la direzione relative dalla posizione originale del pizzico vengono trasformate in un Vector2 e mappate virtualmente all'input normale dello stick analogico.
  • Il giocatore riceve anche un feedback visivo di questo input sotto forma di due mesh quad con cartelloni pubblicitari, che illustrano la posizione dello stick analogico.

Puoi provare un approccio simile per far funzionare il codice di locomozione esistente basato su joystick con modifiche minime. Tuttavia, il tuo progetto potrebbe comunque richiedere una soluzione di locomozione personalizzata per il tracciamento delle mani.

Aggiungere il supporto passthrough

Puoi aggiungere il supporto passthrough alla tua app in modo che gli utenti possano vedere l'ambiente reale che li circonda.

Per farlo per la tua app, apporta le seguenti modifiche al codice:

  • Imposta environment_blend_mode di OpenXR XRInterface su XR_ENV_BLEND_MODE_ALPHA_BLEND.
  • Imposta background_mode del nodo WorldEnvironment su BG_COLOR.
  • Imposta il background_color del nodo WorldEnvironment su un colore completamente trasparente.
  • Imposta la proprietà Viewport transparent_bg su true.

Utilizzare l'estensione di stima della luce

Quando attivi la modalità Passthrough, valuta la possibilità di utilizzare l'estensione OpenXR per la stima della luce di Android XR. Questa estensione modifica le proprietà di WorldEnvironment e DirectionalLight3D per emulare meglio l'illuminazione dell'ambiente reale di un utente, in modo che gli oggetti virtuali si integrino meglio con le condizioni di illuminazione del mondo reale. Puoi attivare questa estensione nelle impostazioni del progetto.

  1. Apri le impostazioni del progetto e vai a Generali > XR > OpenXR.

  2. Nella sezione Androidxr, seleziona Light Estimation.

    Configura le opzioni in

  3. Aggiungi un nodo OpenXRAndroidLightEstimation all'albero delle scene e collegalo a WorldEnvironment e DirectionalLight3D della scena.

    Opzioni per

Esempio: attivare o disattivare il passthrough e la stima della luce

Il codice seguente attiva o disattiva il passthrough e la stima della luce:

@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
Punti chiave sul codice
  • Quando disattivi la stima della luce, la direzione originale del DirectionalLight3D deve essere ripristinata manualmente.
  • Per un esempio completo di un progetto che utilizza passthrough e Light Estimation, consulta Expedition to Blobotopia su GitLab.