Interaction Package Guides — LeonardoXR SDK

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

Questa guida descrive come configurare il layer di interazione per applicazioni LeonardoXR usando i pacchetti standard Unity:

• XR Interaction Toolkit (XRIT) 3.3.0 — sistema di interazione ad alto livello per controller, ray interactor e direct interactor.
• XR Hands 1.7.2 — accesso ai dati delle giunture della mano e gesture recognition.

Dipendenze e Versioni

Nota: Tutte le dipendenze devono essere installate secondo la procedura descritta in Getting Started prima di procedere con la configurazione dell’interazione.

1. Configurazione XR Interaction Toolkit

Installazione

Il pacchetto è installato tramite Window > Package Manager > Unity Registry > XR Interaction Toolkit > Install (versione 3.3.0).

Se durante l’installazione compare il prompt “Enable the new input system?”, clicca Yes. Se compare il prompt “XR Interaction Layer Mask Update Required”, clicca I Made a Backup, Go Ahead! (per nuovi progetti) oppure No Thanks se non era già presente una versione precedente di XRIT.

Importa gli Starter Assets

1. Apri Window > Package Manager, seleziona In Project e poi il pacchetto XR Interaction Toolkit.
2. Nella sezione Samples, clicca Import su Starter Assets.
3. Clicca anche Import su Hand Interaction Demo (necessario per i sample di hand tracking).

Gli Starter Assets includono:

• Input Action Asset preconfigurato per controller XR e hands.
• Prefab di riferimento per XR Origin con Ray Interactor e Direct Interactor.
• Material e shader di base per i visual feedback di interazione.

Configurazione Input Actions

Dopo l’import, un asset XRI Default Input Actions viene aggiunto in Assets/Samples/XR Interaction Toolkit/[versione]/Starter Assets/. Questo asset è già configurato per i profili controller standard (incluso il Companion Controller via Microsoft MMRC Profile) e per le mani.

Per associare l’asset al sistema:

1. Vai su Edit > Project Settings > XR Plug-in Management > Input System.
2. Assicurati che Active Input Handling sia impostato su Both o Input System Package (New).

2. Configurazione della Scena — XR Origin

Struttura Base della Scena

La gerarchia minima per una scena interattiva su LeonardoXR è:

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

Crea la struttura base selezionando GameObject > XR > XR Origin (Action-based) nel menu principale.

Attenzione: Disabilita il componente AR Camera Background — non è supportato su LeonardoXR e viene disabilitato automaticamente a runtime. Disabilita anche AR Camera Manager se non recuperi frame RGB dalla camera.

Input Action Manager

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

1. XRI Default Input Actions (dagli Starter Assets importati).
2. Snapdragon Spaces Input Actions (da Samples/Snapdragon Spaces/[versione]/Core Samples/Shared Assets/Input Actions).

3. Configurazione Controller (Companion Controller)

Il Companion Controller di Leonardo XR usa il Microsoft Mixed Reality Motion Controller Profile per inviare input di puntamento e pulsanti dall’app companion sullo smartphone.

Aggiunta del Profilo Controller

1. Vai su Edit > Project Settings > XR Plug-in Management > OpenXR > Enabled Interaction Profiles.
2. Clicca + e aggiungi Microsoft Mixed Reality Motion Controller Profile.

Nota: Non aggiungere il Hand Interaction Profile insieme al Companion Controller — ha la precedenza e interferisce con il puntamento del controller.

Device Pointer Prefab

1. Trova il prefab del Device Pointer in Samples/Snapdragon Spaces/[versione]/Core Samples/Shared Assets/Prefabs/Interaction.
2. Aggiungilo come figlio del Controller (destra o sinistra) nell’XR Origin.
3. Nel componente XR Interactor Line Visual, imposta Line Width su 0.005.

4. Configurazione XR Hands

Installazione

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

Importa i Hand Samples

1. Apri Window > Package Manager > In Project > XR Hands > Samples.
2. Importa:
   • Gestures — sistema di riconoscimento gesture.
   • Hand Visualizer — visualizzazione delle mesh delle mani.

Attivazione Hand Tracking Subsystem

1. Vai su Edit > Project Settings > XR Plug-in Management > OpenXR (scheda Android).
2. In All Features, abilita Hand Tracking Subsystem.
3. Abilita anche Hand Tracking nel Snapdragon Spaces feature group.

Attenzione: Il Hand Tracking Subsystem deve essere abilitato in All Features — non solo nella sezione Snapdragon Spaces — per funzionare correttamente su LeonardoXR.

Attivazione Hand Interaction Profile

1. Vai su Edit > Project Settings > XR Plug-in Management > OpenXR > Enabled Interaction Profiles.
2. Clicca + e aggiungi Hand Interaction Profile.

Nota: Non aggiungere Hand Interaction Profile se stai usando il Companion Controller — i due profili sono in conflitto. Vedi la sezione “Combinare Controller e Hand Tracking” più in basso.

XR Hand Subsystem e XR Origin

Il pacchetto XR Hands si integra con XR Interaction Toolkit tramite i componenti XR Hand Tracking Events e XR Hand Skeleton Driver. Questi componenti vengono configurati automaticamente sugli XR Origin Controller se si usano i prefab degli Starter Assets del Hand Interaction Demo.

Struttura raccomandata con XR Hands:

XR Origin (Action-based)
  └── Camera Offset
        ├── Left Hand
        │     ├── XR Hand Skeleton Driver
        │     ├── XR Hand Mesh Renderer (opzionale)
        │     └── XR Direct Interactor
        └── Right Hand
              ├── XR Hand Skeleton Driver
              ├── XR Hand Mesh Renderer (opzionale)
              └── XR Ray Interactor (per puntamento a distanza)

Accesso ai Dati delle Giunture via XR Hands API

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 = posizione della punta dell'indice sinistro
        }
    }
}

Gesture Recognition

Usa il sistema Gestures di XR Hands per rilevare pose statiche o dinamiche delle mani:

using UnityEngine.XR.Hands;

// Sulla scena: aggiungi XRHandGestures component all'XR Origin
// Poi sottoscrivi gli eventi:

[SerializeField] XRHandGestures gestures;

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

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

5. Configurazione degli Interactable

Aggiungere Interactable a un Oggetto

Per rendere un oggetto selezionabile da ray o direct interactor:

1. Aggiungi un Collider all’oggetto (es. Box Collider).
2. Aggiungi il componente XR Grab Interactable per oggetti afferrabili, oppure XR Simple Interactable per oggetti che ricevono eventi senza essere spostati.

// Esempio: reazione al select con XR Simple Interactable
using UnityEngine.XR.Interaction.Toolkit;

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

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

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

Interaction Layer Mask

XRIT 3.x usa le Interaction Layer Masks per filtrare quali interactor possono interagire con quali interactable. Configura i layer dall’inspector o tramite:

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

6. UI Canvas e Interazione

Canvas in World Space

Per UI 3D interattive su LeonardoXR:

1. Crea un Canvas e imposta Render Mode su World Space.
2. Aggiungi il componente Tracked Device Graphic Raycaster al Canvas (al posto del Canvas standard Graphic Raycaster).
3. Aggiungi XR UI Input Module al GameObject EventSystem della scena (sostituisce il default Input System UI Input Module).

Impostazioni Canvas Consigliate

7. Combinare Controller e Hand Tracking

Su LeonardoXR non è possibile usare simultaneamente il Companion Controller (con raycast) e il Hand Tracking completo (con raycast da entrambe le mani) a causa dei conflitti tra profili OpenXR.

Opzione A — Solo Controller (Companion Controller)

• Aggiungi Microsoft MMRC Profile tra i profili abilitati.
• Non aggiungere Hand Interaction Profile.
• Il Companion Controller gestisce il puntamento; le mani possono essere usate come collider ma non come interactor di raycast.

Opzione B — Solo Mani (Dual Hand Mode)

• Aggiungi Hand Interaction Profile tra i profili abilitati.
• Non aggiungere Microsoft MMRC Profile.
• Rimuovi il Device Pointer Prefab dal Controller.
• Entrambe le mani tracciate come interactor completi; nessun input dal telefono.

Opzione C — Controller + Una Mano

• Aggiungi Microsoft MMRC Profile tra i profili abilitati.
• Lascia attivo solo il Right Hand Controller nell’XR Origin.
• La mano sinistra può ancora funzionare come collider e trigger per poke interaction, ma non come ray interactor.

8. UniTask — Operazioni Asincrone

UniTask 2.5.10 è incluso come dipendenza per gestire operazioni asincrone ad alte performance (caricamento asset, attesa di subsystem, ecc.) senza allocazioni GC.

Installazione

Installato tramite Window > Package Manager > Unity Registry > UniTask > Install (versione 2.5.10), oppure come git URL.

Utilizzo Base

using Cysharp.Threading.Tasks;

public class HandSubsystemWaiter : MonoBehaviour
{
    async UniTaskVoid Start()
    {
        // Attendi che il subsystem XR Hands sia pronto
        await UniTask.WaitUntil(() =>
            XRHandSubsystemUtility.GetSubsystem()?.running ?? false);

        Debug.Log("XR Hands subsystem pronto.");
    }
}

UniTask è usato internamente dall’LeonardoXR SDK per operazioni asincrone. Si raccomanda di usarlo anche nel codice dell’applicazione per coerenza con il lifecycle dell’SDK.

Riferimenti ai Profili di Interazione OpenXR

Ricorda: I due profili non possono coesistere con raycast attivo su entrambi. Scegli una delle opzioni descritte nella sezione “Combinare Controller e Hand Tracking”.