Les manettes sont utilisées comme une interface familière permettant aux utilisateur·ices d’interagir au sein des applications Unity XR. Elles acceptent les entrées des utilisateurs et des utilisatrices, comme les pressions de boutons ou les mouvements de joystick, et suivent les mouvements des mains de l’utilisateur ou l’utilisatrice.

OVRInput est l’API unifiée de Meta pour l’entrée et le suivi des manettes dans Unity, conçue pour les manettes Meta Quest Touch. Elle fournit une interface pour accéder aux données en temps réel des éléments suivants :

État de la manette, boutons, sticks analogiques, gâchettes et toucher capacitif

Poses de la main et de la manette

Use Unity's Input System

Pour les nouveaux projets, utilisez le package Input System⁠ d’Unity à la place d’OVRInput. OVRInput est conservé pour des raisons de compatibilité avec les anciennes versions, mais les nouvelles fonctionnalités et les nouveaux appareils pourraient être uniquement disponibles dans le système d’entrée d’Unity.

Pour faciliter l’ajout d’interactions basées sur les manettes, telles que la saisie d’objets, le déplacement dans une scène ou la configuration des interfaces d’utilisation, consultez la Présentation du SDK Interaction.

Configuration

Pour utiliser OVRInput, vous devez installer le SDK Meta XR Interaction dans votre projet Unity. Pour un guide étape par étape, consultez Configurer le SDK Interaction.

Ensuite, placez un prefab OVRManager n’importe où dans votre scène. Elle gère l’état de l’appareil et les mises à jour des entrées.

Dans les scripts qui gèrent l’entrée ou la logique du jeu, ajouter respectivement OVRInput.Update() et OVRInput.FixedUpdate() une fois par image au début de toutes les méthodes Update et FixedUpdate. Par exemple :

public class XRInputManager : MonoBehaviour {
    void Update() {
        OVRInput.Update();
        // Handle input logic here
    }
    void FixedUpdate() {
        OVRInput.FixedUpdate();
        // Handle physics-based input here
    }
}

Remarque : suivez les recommandations ci-dessous pour appeler les méthodes de mise à jour d’OVRInput :

Centralisez les appels de fonction de mise à jour dans un script de gestionnaire d’entrée principal pour garantir un état cohérent.

Appelez la fonction de mise à jour avant les autres scripts qui dépendent de l’état de la saisie.

Si votre projet comporte plusieurs scènes, assurez-vous que le gestionnaire d’entrée est présent dans chaque scène.

Lorsque vous incluez OVRInput, le système ajoute automatiquement des liaisons d’entrée, qui définissent la manière dont les actions de la manette sont mappées sur Unity. Vous pouvez les référencer dans le fichier de configuration InputManager.asset de votre projet.

Pour plus d’informations, consultez la documentation de référence de l’API OVRInput.

Fonctionnement

Les sections suivantes expliquent comment récupérer les données de manettes et de suivi à l’aide d’OVRInput.

Interrogation des entrées

OVRInput fournit des méthodes pour interroger l’état des manettes, notamment :

Get() : renvoie l’état actuel d’un bouton, d’un axe ou d’un capteur de toucher

GetDown() : indique si le bouton a été enfoncé dans cette image

GetUp() : renvoie 1 si un bouton a été relâché dans cette image, 0 dans le cas contraire

Par exemple, le code suivant vérifie si la gâchette de la manette droite a été actionnée dans l’image actuelle :

if (OVRInput.GetDown(OVRInput.Button.PrimaryIndexTrigger, OVRInput.Controller.RTouch)) {
    // Trigger pressed on right controller
}

Suivi de la pose des manettes

OVRInput indique la position des manettes dans le même cadre que le casque, par rapport à la position initiale du centre des yeux. Les positions sont prévues en synchronisation avec le casque pour un rendu à faible latence.

Utilisez OVRManager.display.RecenterPose() pour réinitialiser les positions de la manette et du casque par rapport à la position actuelle.

OVRInput fournit les fonctions de suivi de position suivantes :

GetLocalControllerPosition() : renvoie la position dans un Vector3

GetLocalControllerRotation() : renvoie l’orientation dans un Quaternion

Identification des manettes

OVRInput utilise les désignations suivantes pour les manettes Meta Quest Touch :

Primary : manette gauche

Secondary : manette droite

Énumérations des entrées de commande

OVRInput propose des variantes de Get() qui permettent d’accéder à différents ensembles de commandes, notamment les suivantes :

Commande	Énumère
`OVRInput.Button`	Les boutons classiques présents sur les manettes de jeu, les manettes et le bouton Retour.
`OVRInput.Touch`	Surfaces de contrôle sensibles à la capacité de la manette.
`OVRInput.NearTouch`	Surfaces de contrôle sensibles à la proximité situées sur la manette.
`OVRInput.Axis1D`	Commandes unidimensionnelles comme les gâchettes qui rapportent un état en virgule flottante.
`OVRInput.Axis2D`	Commandes à deux dimensions, y compris les sticks analogiques. Établit un rapport sur l’état d’un Vector2.

Un ensemble secondaire d’énumérations reflète le premier, défini comme suit :

Commande
`OVRInput.RawButton`
`OVRInput.RawTouch`
`OVRInput.RawNearTouch`
`OVRInput.RawAxis1D`
`OVRInput.RawAxis2D`

La première série d’énumérations fournit une cartographie d’entrées virtuelles qui permet aux développeur·ses de créer des schémas de contrôle fonctionnant sur différents types de manettes. Le mappage virtuel fournit des fonctionnalités utiles, présentées dans les sections suivantes.

Le second ensemble d’énumérations fournit un accès brut et non modifié à l’état sous-jacent des manettes.

Bouton, Touch et NearTouch

Outre les boutons classiques de la manette de jeu, les manettes sont équipées de surfaces de contrôle sensibles au capacitif qui détectent le contact physique des doigts ou des pouces de l’utilisateur·ice (Touch), ainsi que leur proximité (NearTouch). Cela permet de détecter plusieurs états distincts d’interaction de l’utilisateur·ice avec une surface de contrôle spécifique. Par exemple, si l’index d’un utilisateur ou d’une utilisatrice est complètement retiré d’une surface de contrôle, la valeur NearTouch associée à cette commande sera false (faux). Lorsque le doigt de l’utilisateur·ice s’approche de la commande et entre à proximité immédiate de celui-ci, le NearTouch rapporte la valeur true avant que l’utilisateur·ice n’ait contact avec la commande. Lorsque l’utilisateur·ice établit un contact physique, la valeur Touch de cette commande sera définie sur true (vrai). Lorsque l’utilisateur·ice pousse la gâchette d’index vers le bas, la valeur Button de cette commande sera définie sur true (vrai). Ces états distincts permettent de détecter précisément les interactions de l’utilisateur ou l’utilisatrice avec la manette et d’activer différents schémas de contrôle.

Exemple d’utilisation

Les exemples suivants montrent comment interroger différents types d’entrées, y compris les boutons, les sticks analogiques, les gâchettes et les capteurs de toucher capacitifs :

// returns true if the primary button (typically “A”) is currently pressed.
OVRInput.Get(OVRInput.Button.One);

// returns true if the primary button (typically “A”) was pressed this frame.
OVRInput.GetDown(OVRInput.Button.One);

// returns true if the “X” button was released this frame.
OVRInput.GetUp(OVRInput.RawButton.X);

// returns a Vector2 of the primary (typically the Left) thumbstick’s current state.
// (X/Y range of -1.0f to 1.0f)
OVRInput.Get(OVRInput.Axis2D.PrimaryThumbstick);

// returns true if the primary thumbstick is currently pressed (clicked as a button)
OVRInput.Get(OVRInput.Button.PrimaryThumbstick);

// returns true if the primary thumbstick has been moved upwards more than halfway.
// (Up/Down/Left/Right - Interpret the thumbstick as a D-pad).
OVRInput.Get(OVRInput.Button.PrimaryThumbstickUp);

// returns a float of the secondary (typically the Right) index finger trigger’s current state.
// (range of 0.0f to 1.0f)
OVRInput.Get(OVRInput.Axis1D.SecondaryIndexTrigger);

// returns a float of the left index finger trigger’s current state.
// (range of 0.0f to 1.0f)
OVRInput.Get(OVRInput.RawAxis1D.LIndexTrigger);

// returns true if the left index finger trigger has been pressed more than halfway.
// (Interpret the trigger as a button).
OVRInput.Get(OVRInput.RawButton.LIndexTrigger);

// returns true if the secondary gamepad button, typically “B”, is currently touched by the user.
OVRInput.Get(OVRInput.Touch.Two);

Outre la spécification d’une commande, Get() peut inclure un paramètre de commande facultatif. La liste des commandes prises en charge est définie dans la section "Enumeration Controller" de OVRInput.

La spécification d’une commande peut être utilisée si un schéma de commande particulier est destiné uniquement à un certain type de commande. Si aucun paramètre de manette n’est fourni à Get(), la valeur par défaut est d’utiliser la commande Active, qui correspond à la manette qui a le plus récemment signalé l’entrée de l’utilisateur·ice. Par exemple, l’utilisateur·ice peut utiliser une paire de manettes, les poser et prendre une manette Xbox. Dans ce cas, la manette active sera définie sur la manette Xbox dès que l’utilisateur·ice l’utilisera. La manette Active actuelle peut être interrogée avec OVRInput.GetActiveController() et un masque de bits de toutes les manettes connectées peut être interrogé avec OVRInput.GetConnectedControllers().

L’exemple suivant montre comment spécifier explicitement la paire de manettes combinée pour interroger les gâchettes des mains gauche et droite :

// returns a float of the hand trigger's current state on the left controller.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, OVRInput.Controller.Touch);

// returns a float of the hand trigger's current state on the right controller.
OVRInput.Get(OVRInput.Axis1D.SecondaryHandTrigger, OVRInput.Controller.Touch);

Remarque : les manettes Meta Quest Touch peuvent être spécifiées soit en tant que paire combinée (avec OVRInput.Controller.Touch), soit individuellement (avec OVRInput.Controller.LTouch et RTouch). Il s’agit d’un élément important car la spécification LTouch ou RTouch utilise un ensemble différent de mappages d’entrée virtuelle qui permettent un développement plus pratique du code d’entrée indépendant de la main.

L’exemple suivant montre une saisie indépendante des mains en utilisant PrimaryHandTrigger avec des manettes individuelles, où Primary correspond toujours à la main spécifiée :

// returns a float of the hand trigger's current state on the left controller.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, OVRInput.Controller.LTouch);

// returns a float of the hand trigger's current state on the right controller.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, OVRInput.Controller.RTouch);

Cette approche peut être étendue pour permettre au même code de fonctionner pour les deux mains en spécifiant la manette dans une variable définie en externe, telle qu’une variable publique.

L’exemple suivant montre comment écrire un code d’entrée réutilisable en exposant la manette comme une variable configurable :

// public variable that can be set to LTouch or RTouch in the Unity Inspector
public OVRInput.Controller controller;

// returns a float of the hand trigger’s current state on the controller
// specified by the controller variable.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, controller);

// returns true if the primary button (“A” or “X”) is pressed on the controller
// specified by the controller variable.
OVRInput.Get(OVRInput.Button.One, controller);

Cela évite les contrôles if/else fréquents pour les mappages des entrées des mains gauche et droite.

Cartographie des entrées Touch

Les schémas suivants illustrent les mappages d’entrée les plus courants pour les manettes. Pour plus d’informations sur les autres mappages disponibles, consultez la documentation de référence de l’API OVRInput.

Mappage virtuel pour les manettes combinées

Lorsque vous accédez aux manettes en tant que paire combinée avec OVRInput.Controller.Touch, le mappage virtuel correspond étroitement à la disposition d’une manette de jeu typique répartie entre les mains gauche et droite.

Mappage virtuel pour les manettes individuelles

Lorsque vous accédez à la manette gauche ou droite individuellement avec OVRInput.Controller.LTouch ou OVRInput.Controller.RTouch, le mappage virtuel change pour permettre des liaisons d’entrée indépendantes des mains. Par exemple, le même script peut demander dynamiquement à la manette gauche ou droite laquelle il est attaché et Button.One est associé en conséquence au bouton A ou X.

Mappage brut

Le mappage brut expose directement les manettes. La disposition des manettes correspond étroitement à celle d’une manette de jeu classique répartie entre la main gauche et la main droite.