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 offre 3 opzioni di rendering per i progetti: Compatibilità, Mobile e Forward+. Attualmente si consiglia di utilizzare il rendering Mobile per qualsiasi progetto VR su desktop e il rendering Compatibilità per qualsiasi progetto eseguito su un visore autonomo come Meta Quest 3. I progetti XR funzioneranno con il rendering Forward+, ma al momento non è ottimizzato bene per XR rispetto agli altri due.

OpenXR

OpenXR è un nuovo standard dell'industria che consente a diverse piattaforme XR di presentarsi alle applicazioni XR tramite un'API standardizzata. Questo standard è uno standard aperto gestito dal Khronos Group e quindi si allinea molto bene agli interessi di Godot.

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

Every XR application needs at least an XROrigin3D and an XRCamera3D node. Most will have two XRController3D, one for the left hand and one for the right. Keep in mind that the camera and controller nodes should be children of the origin node. Add these nodes to a new scene and rename the controller nodes to LeftHand and RightHand, your scene should look something like this:

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:

Right now all these nodes are on the floor, they will be positioned correctly in runtime. To help during development, it can be helpful to move the camera upwards so its y is set to 1.7, and move the controller nodes to -0.5, 1.0, -0.5 and 0.5, 1.0, -0.5 for respectively the left and right hand.

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")

        # Turn off v-sync!
        DisplayServer.window_set_vsync_mode(DisplayServer.VSYNC_DISABLED)

        # 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");

            // Turn off v-sync!
            DisplayServer.WindowSetVsyncMode(DisplayServer.VSyncMode.Disabled);

            // 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");
        }
    }
}

Questo frammento di codice presuppone l'utilizzo di OpenXR; se desideri utilizzare un'altra interfaccia, puoi modificare la chiamata find_interface.

Avvertimento

As you can see in the code snippet above, we turn off v-sync. When using OpenXR you are outputting the rendering results to an HMD that often requires us to run at 90Hz or higher. If your monitor is a 60hz monitor and v-sync is turned on, you will limit the output to 60 frames per second.

Le interfacce XR come OpenXR effettuano la propria sincronizzazione.

Nota inoltre che, normalmente, il motore di fisica 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 visualise them. Make sure you configure a sky in your world environment.

Now run your project, you should be floating somewhere in space and be able to look around.

Nota

While traditional level switching can definitely be used with XR applications, where this scene setup is repeated in each level, most find it easier to set this up once and loading levels as a subscene. If you do switch scenes and replicate the XR setup in each one, do make sure you do not run initialize multiple times. The effect can be unpredictable depending on the XR interface used.

For the rest of this basic tutorial series we will create a game that uses a single scene.