Guida al pacchetto di interazione

• Version 1.0.2
• Device: Youbiquo Leonardo XR
• Base SDK: Snapdragon Spaces 1.0.4

Questa guida descrive come configurare il livello di interazione per le applicazioni LeonardoXR utilizzando i pacchetti standard di Unity:

• XR Interaction Toolkit (XRIT) 3.3.0 — sistema di interazione di alto livello per controller, interattori a raggi e interattori diretti.
• XR Hands 1.7.2 — accesso ai dati delle articolazioni della mano e riconoscimento dei gesti.

Dipendenze e versioni

NOTA: Tutte le dipendenze devono essere installate come descritto nella guida introduttiva prima di procedere con la configurazione dell’interazione.

1. Configurazione del toolkit di interazione XR

Installazione

Installa tramite Window > Package Manager > Unity Registry > XR Interaction Toolkit > Install (versione 3.3.0). Se viene visualizzato il messaggio “Abilitare il nuovo sistema di input?”, fare clic su Sì. Se viene visualizzato il messaggio “Aggiornamento della maschera del livello di interazione XR richiesto”, fare clic su Ho creato un backup, procedi! (per i nuovi progetti) oppure su No grazie se non era presente alcuna versione precedente di XRIT.

Importa risorse iniziali

1. Aprire Window > Package Manager, selezionare In Project poi XR Interaction Toolkit.
2. Sotto Samples, clic Import su Starter Assets.
3. Anche clic Import su Hand Interaction Demo (richiesto per i campioni di tracciamento manuale).

Le risorse iniziali includono:

• Asset di input preconfigurato per controller e mani XR.
• Prefab di riferimento per XR Origin con Ray Interactor e Direct Interactor.
• Materiali di base e shader per il feedback visivo dell’interazione.

Configura le azioni di input

Dopo l’importazione, viene aggiunto un asset denominato XRI Default Input Actions alla cartella Assets/Samples/XR Interaction Toolkit/[version]/Starter Assets/. Questo asset è preconfigurato per i profili controller standard (incluso il Companion Controller tramite il profilo Microsoft MMRC) e per le mani.

Per associare la risorsa al sistema: vai a Edit > Project Settings > XR Plug-in Management > Input System e garantire Active Input Handling è impostato su Entrambi o Pacchetto sistema di input (Nuovo).

2. Configurazione della scena — XR Origin

Gerarchia della scena di base

AR Session
XR Origin (Action-based)
  └── Camera Offset
        ├── Main Camera (tagged "MainCamera")
        ├── LeftHand Controller
        │     ├── XR Ray Interactor (left)
        │     └── XR Direct Interactor (left)
        └── RightHand Controller
              ├── XR Ray Interactor (right)
              └── XR Direct Interactor (right)

Crea la struttura di base selezionando GameObject > XR > XR Origin (Action-based).

NOTA: Disabilitare lo sfondo della fotocamera AR: non è supportato su LeonardoXR e viene disabilitato automaticamente in fase di esecuzione. Disabilitare anche AR Camera Manager se non si acquisiscono frame RGB dalla fotocamera.

Gestore delle azioni di input

Aggiungi il componente Input Action Manager all’XR Origin (o a un GameObject persistente). Nel campo Action Assets, assegna:

• XR Input Actions (from Samples/LeonardoXR SDK/[version]/Core Samples/Shared Assets).

3. Configurazione mani XR

Installazione

Installa tramite Window > Package Manager > Unity Registry > XR Hands > Install (versione 1.7.2).

Importazione di campioni di mani

Aprire Window > Package Manager > In Project > XR Hands > Samples e importare:

• Gesti — sistema di riconoscimento dei gesti.
• Visualizzatore della mano — visualizzazione della mesh della mano.

Abilita il sottosistema di tracciamento della mano

1. Vai a Edit > Project Settings > XR Plug-in Management > OpenXR (Android tab).
2. Sotto All Features, abilitare Hand Tracking Subsystem.
3. Abilita anche Hand Tracking nel gruppo di funzionalità Snapdragon Spaces.

NOTA: Il sottosistema di tracciamento della mano deve essere abilitato in Tutte le funzionalità, non solo nella sezione Snapdragon Spaces, per funzionare correttamente su LeonardoXR.

Accesso ai dati della mano tramite l’API XR Hands

using UnityEngine.XR.Hands;

XRHandSubsystem handSubsystem = XRHandSubsystemUtility.GetSubsystem();
if (handSubsystem != null)
{
    XRHand leftHand = handSubsystem.leftHand;
    if (leftHand.isTracked)
    {
        if (leftHand.GetJoint(XRHandJointID.IndexTip).TryGetPose(out Pose indexTipPose))
        {
            // indexTipPose.position = position of left index fingertip
        }
    }
}

Riconoscimento dei gesti

[SerializeField] XRHandGestures gestures;

void OnEnable()
{
    gestures.gesturePerformed += OnGesturePerformed;
}

void OnGesturePerformed(XRHandGesture gesture, Handedness handedness)
{
    Debug.Log($"Gesture: {gesture.gestureName} performed with {handedness}");
}

4. Configurazione degli elementi interattivi

Aggiungere un elemento interattivo a un oggetto

1. Aggiungi un Collider all’oggetto (ad esempio Box Collider).
2. Aggiungi XR Grab Interactable per oggetti afferrabili, o XR Simple Interactable per oggetti che ricevono eventi senza essere spostati.

public class MyButton : MonoBehaviour
{
    [SerializeField] XRSimpleInteractable interactable;

    void OnEnable()
    {
        interactable.selectEntered.AddListener(OnSelected);
    }

    void OnSelected(SelectEnterEventArgs args)
    {
        Debug.Log("Selected by: " + args.interactorObject);
    }
}

Maschera dello strato di interazione

XRIT 3.x utilizza le maschere di livello di interazione per filtrare quali interattori possono interagire con quali elementi interattivi:

interactable.interactionLayers = InteractionLayerMask.GetMask("Default", "UI");

5. Canvas dell’interfaccia utente e interazione

Spazio mondiale su tela

1. Crea un Canvas e imposta la modalità di rendering su World Space.
2. Aggiungi il componente Tracked Device Graphic Raycaster al Canvas (sostituisce il Graphic Raycaster standard).
3. Aggiungi il componente XR UI Input Module all’oggetto di gioco EventSystem nella scena (sostituisce il modulo di input UI Input Module predefinito).

Impostazioni consigliate per la tela

6. Combinazione di controllo e tracciamento della mano

Su LeonardoXR non è possibile utilizzare contemporaneamente i controller del visore e il tracciamento completo delle mani (con raycast da entrambe le mani) a causa di conflitti tra i profili OpenXR.

Option A —Solo controller (controller ausiliario)

• Aggiungi il profilo Microsoft MMRC ai profili abilitati.

• Non aggiungere il profilo Interazione con le mani.

• Il Companion Controller gestisce il puntamento; le mani possono essere utilizzate come collider, ma non come interattori raycast.

Opzione B — Solo mani (modalità a due mani)

• Aggiungi il profilo di interazione manuale ai profili abilitati.

• Non aggiungere il profilo Microsoft MMRC.

• Rimuovi il prefab del puntatore del dispositivo dal controller.

• Entrambe le mani vengono tracciate come interattori completi; nessun input dal telefono.

Opzione C — Controller + Una mano

• Aggiungi il profilo Microsoft MMRC ai profili abilitati.
• Mantieni attivo solo il controller della mano destra nell’XR Origin.
• La mano sinistra può ancora funzionare come collider e trigger di interazione poke, ma non come interattore ray.

7. UniTask — Operazioni asincrone

UniTask 2.5.10 è incluso come dipendenza per operazioni asincrone ad alte prestazioni (caricamento di risorse, attesa di sottosistemi, ecc.) senza allocazioni di garbage collection.

using Cysharp.Threading.Tasks;

public class HandSubsystemWaiter : MonoBehaviour
{
    async UniTaskVoid Start()
    {
        // Wait until the XR Hands subsystem is ready
        await UniTask.WaitUntil(() =>
            XRHandSubsystemUtility.GetSubsystem()?.running ?? false);
        Debug.Log("XR Hands subsystem ready.");
    }
}

UniTask viene utilizzato internamente dall’SDK di LeonardoXR per le operazioni asincrone. Si consiglia di utilizzarlo anche nel codice dell’applicazione per coerenza con il ciclo di vita dell’SDK.

Riferimento al profilo di interazione OpenXR