Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Configurazione del XR

Introduzione al sistema XR in Godot

Godot fornisce un sistema XR modulare che astrae molte delle specifiche della piattaforma XR dall'utente. Al centro si trova XRServer, che funge da interfaccia centrale per il sistema XR, consentendo agli utenti di scoprire interfacce e interagire con i componenti del sistema XR.

Ogni piattaforma XR supportata è implementata come XRInterface. Un elenco delle piattaforme supportate è disponibile nella pagina dell'elenco delle funzionalità qui. Le interfacce supportate si registrano con XRServer e si possono interrogare con il metodo find_interface su XRServer. Una volta trovata, l'interfaccia desiderata si può inizializzare chiamando initialize sull'interfaccia.

Avvertimento

Un'interfaccia registrata non significa altro che l'interfaccia è disponibile; se l'interfaccia non è supportata dal sistema host, l'inizializzazione potrebbe fallire e restituire false. Questo può avere diverse cause, e purtroppo le cause sono diverse da piattaforma a piattaforma. Può essere perché l'utente non ha installato il software richiesto o non ha collegato le cuffie e basta. In qualità di sviluppatore, è quindi necessario reagire adeguatamente a un'interfaccia che non riesce a inizializzarsi.

A causa dei requisiti speciali per l'output in XR, in particolare per i dispositivi montati sulla testa che forniscono immagini diverse a ciascun occhio, XRServer in Godot sovrascriverà diverse funzionalità del sistema di rendering. Per i dispositivi autonomi, ciò significa che l'output finale è gestito da XRInterface e il solito sistema di output di Godot è disabilitato. Per i dispositivi XR desktop che funzionano come secondo schermo, è possibile dedicare una Viewport separata per gestire l'output XR, lasciando la finestra principale di Godot disponibile per visualizzare contenuti alternativi.

Nota

Si noti che solo un'interfaccia può essere responsabile di gestire l'output verso un dispositivo XR: questa è nota come interfaccia primaria e, come predefinito, sarà la prima interfaccia inizializzata. Godot attualmente supporta quindi solo implementazioni con un singolo visore. È possibile, ma sempre più raro, avere un'interfaccia secondaria, ad esempio per aggiungere il tracciamento a un dispositivo altrimenti unicamente 3DOF (3 gradi di libertà di movimento).

Esistono tre tipi di nodi specifici di XR che si troveranno in quasi tutte le applicazioni XR:

XROrigin3D rappresenta, a tutti gli effetti, il punto centrale del tuo spazio di gioco. Questa è una dichiarazione molto semplificata, ma ne parleremo più in dettaglio più avanti. Tutti gli oggetti tracciati nello spazio fisico dalla piattaforma XR sono posizionati in relazione a questo punto.
XRCamera3D rappresenta la telecamera (stereoscopica) utilizzata durante il rendering dell'output per il dispositivo XR. Il posizionamento di questo nodo è controllato dal sistema XR e aggiornato automaticamente tramite le informazioni di tracciamento fornite dalla piattaforma XR.
XRController3D rappresenta un controller utilizzato dal giocatore; solitamente ce ne sono due, uno per ciascuna mano. Questi nodi danno accesso a vari stati dei controller e inviano segnali quando il giocatore preme i pulsanti. Il posizionamento di questo nodo è controllato dal sistema XR e aggiornato automaticamente tramite le informazioni di tracciamento fornite dalla piattaforma XR.

Esistono altri nodi correlati a XR e ci sarebbe molto altro da dire su questi tre nodi, ma ne parleremo più avanti.

Quale Renderer utilizzare

Godot has 3 renderer options for projects: Compatibility, Mobile, and Forward+. The current recommendation is to use the Mobile renderer for any desktop VR project, or any project running on a standalone headset like the Meta Quest 3. XR projects will run with the Forward+ renderer, but it isn't well optimized for XR right now compared to the other two.

OpenXR

OpenXR is the industry standard API that allows different XR platforms to interact with XR applications. This standard is an open standard maintained by the Khronos Group and thus aligns very well with Godot's interests. We are thus using this as the example in this introduction. Check the respective chapters for differences in other APIs.

L'implementazione Vulkan di OpenXR è strettamente integrata con Vulkan, prendendo il controllo di parte del sistema Vulkan. Ciò richiede una stretta integrazione di alcune funzionalità grafiche base nel renderer Vulkan, necessarie prima di configurare il sistema XR. Questo è stato uno dei principali fattori decisivi per aver incluso OpenXR come interfaccia di base.

Ciò significa anche che è necessario abilitare OpenXR all'avvio di Godot per poter configurare correttamente il tutto. Abilita l'impostazione Enabled nelle impostazioni del progetto, in XR > OpenXR.

Qui puoi trovare anche diverse altre impostazioni relative a OpenXR. Queste non si possono cambiare mentre l'applicazione è in esecuzione. Le impostazioni predefinite sono sufficienti per cominciare, ma per maggiori informazioni su cosa c'è qui consulta Impostazioni OpenXR.

Dovrai anche andare su XR > Shader nelle impostazioni del progetto e selezionare la casella Enabled per abilitarli. Una volta fatto, clicca sul pulsante Salva e riavvia.

Avvertimento

Molti effetti di post-elaborazione non sono ancora stati aggiornati per supportare il rendering stereoscopico. Il loro utilizzo avrà effetti negativi.

Configurare una scena XR

Ogni applicazione XR ha bisogno di almeno un nodo XROrigin3D e un nodo XRCamera3D. La maggior parte avrà due nodi XRController3D, uno per la mano sinistra e uno per la mano destra. Ricorda che i nodi della telecamera e di controller devono essere figli del nodo di origine. Aggiungi questi nodi a una nuova scena e rinomina i nodi di controller in LeftHand e RightHand; la tua scena dovrebbe apparire più o meno così:

Le icone di avvertimento sono previste e dovrebbero scomparire dopo aver configurato i controller. Seleziona il controller sinistro e configuralo come segue:

E la mano destra:

Al momento tutti questi nodi si trovano sul pavimento, ma saranno posizionati correttamente in fase di esecuzione. Per facilitare lo sviluppo, può essere utile spostare la telecamera verso l'alto così che il suo y sia impostato su 1.7 e spostare i nodi di controller a -0.5, 1.0, -0.5 e 0.5, 1.0, -0.5 rispettivamente per la mano sinistra e destra.

Successivamente, dobbiamo aggiungere uno script al nostro nodo radice. Aggiungi il seguente codice a questo script:

extends Node3D

var xr_interface: XRInterface

func _ready():
    xr_interface = XRServer.find_interface("OpenXR")
    if xr_interface and xr_interface.is_initialized():
        print("OpenXR initialized successfully")

        # Change our main viewport to output to the HMD.
        get_viewport().use_xr = true
    else:
        print("OpenXR not initialized, please check if your headset is connected")

using Godot;

public partial class MyNode3D : Node3D
{
    private XRInterface _xrInterface;

    public override void _Ready()
    {
        _xrInterface = XRServer.FindInterface("OpenXR");
        if(_xrInterface != null && _xrInterface.IsInitialized())
        {
            GD.Print("OpenXR initialized successfully");

            // Change our main viewport to output to the HMD.
            GetViewport().UseXR = true;
        }
        else
        {
            GD.Print("OpenXR not initialized, please check if your headset is connected");
        }
    }
}

Nota

There is no restriction to where this code is executed from. It is common to add this script to the XROrigin3D node or as a Node3D child of the root node.

The OpenXR interface is unique in that we have to start it before the project loads, hence is_initialized is checked here. Most interfaces require a call to their initialize function instead.

If you wish to support multiple XR interfaces, say release a game both targeting OpenXR hardware and deploy over WebXR, you can check one after the other until a functioning interface is found.

Avvertimento

As OpenXR outputs the rendering result to an HMD, which often runs at a higher framerate than the monitor, Godot's V-Sync settings are ignored and V-sync will always be disabled.

Instead, OpenXR perform its own frame timing to ensure a consistent framerate.

Nota inoltre che, normalmente, il motore fisico funziona a 60 Hz e questo può causare una fisica instabile. Si consiglia di impostare Engine.physics_ticks_per_second su un valore più alto.

If you run your project at this point in time, everything will work but you will be in a dark world. So to finish off our starting point add a DirectionalLight3D and a WorldEnvironment node to your scene. You may wish to also add a mesh instance as a child to each controller node just to temporarily visualize them. Make sure you configure a sky in your world environment.

Ora esegui il tuo progetto: dovresti star fluttuando da qualche parte nello spazio e sarai capace di guardarti attorno.

Nota

Sebbene il tradizionale cambio di livello si possa certamente fare con le applicazioni XR, dove questa configurazione di scena viene ripetuta in ogni livello, molti trovano più semplice configurarla una sola volta e caricare i livelli come sotto-scene. Se cambi scena e replichi la configurazione XR in ciascuna, assicurarti di non eseguire initialize più volte. L'effetto può essere imprevedibile a seconda dell'interfaccia XR utilizzata.

Per il resto di questa serie di tutorial base, creeremo un gioco che utilizza una singola scena.