Разработка

Общие сведения о вводе с контроллера и отслеживании контроллера

Обновлено: 13 фев 2026 г.

Контроллеры предоставляют пользователям привычный интерфейс для взаимодействия с приложениями Unity XR. Они принимают ввод пользователя, например нажатие кнопок или движение джойстика, и отслеживают движения рук пользователя.

OVRInput — это унифицированный API от Meta для ввода и отслеживания контроллеров в Unity, предназначенный для контроллеров Meta Quest Touch. Он предоставляет интерфейс для доступа к данным в режиме реального времени:

состояние контроллера, нажатие кнопок, джойстиков, курков и сенсорных элементов управления;

Положение рук и контроллеров

Use Unity's Input System

Для новых проектов используйте пакет Input System Package⁠ от Unity вместо OVRInput. OVRInput поддерживается для устаревших приложений, но новые функции и устройства могут быть доступны только в системе ввода Unity.

Подробнее о том, как добавить взаимодействия на основе контроллера, такие как взятие объектов, перемещение по сцене или настройка пользовательских интерфейсов, см. в статье Обзор Interaction SDK.

Настройка

Чтобы использовать OVRInput, необходимо установить Meta XR Interaction SDK в проект Unity. Пошаговое руководство см. в разделе Настройка Interaction SDK.

Затем разместите prefab OVRManager в любой части сцены. Это позволяет управлять состоянием устройства и обновлениями ввода.

Добавьте OVRInput.Update() и OVRInput.FixedUpdate() один раз за кадр в начале работы всех методов Update и FixedUpdate в скриптах, которые обрабатывают ввод или логику игры. Пример:

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

Примечание. Используйте следующие рекомендации для вызова методов обновления OVRInput:

Централизуйте вызовы функции обновления в основном скрипте диспетчера ввода для обеспечения согласованного состояния.

Вызывайте функцию обновления перед другими скриптами, которые зависят от состояния ввода.

Если в вашем проекте несколько сцен, убедитесь, что в каждой из них присутствует диспетчер ввода.

При добавлении OVRInput система автоматически добавляет привязки ввода, которые определяют, как действия контроллера отображаются в Unity. На них можно ссылаться в файле конфигурации InputManager.asset вашего проекта.

Подробнее см. в справочной документации по API OVRInput.

Принципы работы

В следующих разделах описано, как получить данные контроллера и отслеживания с помощью OVRInput.

Запрос ввода

OVRInput предоставляет методы для запроса состояния контроллера, в том числе:

Get(): возвращает текущее состояние кнопки, оси или сенсорного датчика

GetDown(): возвращает информацию о том, была ли кнопка нажата в этом кадре

GetUp(): возвращает информацию о том, была ли кнопка отпущена в этом кадре

Например, следующий код проверяет, был ли курок нажат на правом контроллере в текущем кадре:

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

Отслеживание положения контроллера

OVRInput сообщает о положении контроллера в том же кадре, что и гарнитура, относительно начального центрального положения глаза. Позы предсказываются синхронно с гарнитурой для рендеринга с минимальной задержкой.

Используйте OVRManager.display.RecenterPose(), чтобы сбросить позы контроллера и гарнитуры до текущего положения.

OVRInput предоставляет следующие функции отслеживания позы:

GetLocalControllerPosition(): возвращает позицию в Vector3

GetLocalControllerRotation(): возвращает ориентацию в Quaternion

Идентификация контроллера

В OVRInput используются следующие обозначения для контроллеров Meta Quest Touch:

Primary: левый контроллер

Secondary: правый контроллер

Перечисления ввода для управления

OVRInput предлагает варианты Get() которые обеспечивают доступ к разным наборам элементов управления, в том числе:

Управление	Перечисления
`OVRInput.Button`	Традиционные кнопки на геймпадах, контроллерах и кнопка "Назад".
`OVRInput.Touch`	Поверхности контроллера с поддержкой сенсорного управления.
`OVRInput.NearTouch`	Поверхности контроллера, чувствительные к приближению.
`OVRInput.Axis1D`	Одномерные элементы управления, такие как курки, которые сообщают о состоянии с плавающей запятой.
`OVRInput.Axis2D`	Двухмерные элементы управления, в том числе джойстики. Представляет состояние Vector2.

Второй набор перечислений зеркально отражает первый:

Управление
`OVRInput.RawButton`
`OVRInput.RawTouch`
`OVRInput.RawNearTouch`
`OVRInput.RawAxis1D`
`OVRInput.RawAxis2D`

Первая группа перечислений обеспечивает виртуализированное сопоставление ввода, которое позволяет разработчикам создавать схемы управления для различных типов контроллеров. Виртуальное сопоставление предоставляет полезную функциональность, которая продемонстрирована в следующих разделах.

Второй набор перечислений обеспечивает необработанный доступ к базовому состоянию контроллеров.

Button, Touch и NearTouch

Помимо традиционных кнопок на геймпаде, контроллеры оснащены чувствительными к касаниям поверхностями, которые обнаруживают, когда пальцы или большой палец пользователя физически контактируют с ними (Touch), а также когда они находятся в непосредственной близости от этих поверхностей (NearTouch). Это позволяет обнаруживать несколько различных состояний взаимодействия пользователя с определенной поверхностью управления. Например, если указательный палец пользователя полностью удален с поверхности управления, NearTouch для этого управления будет сообщать false. Когда палец пользователя приближается к элементу управления и находится в непосредственной близости от него, NearTouch сообщит о приближении до того, как пользователь физически коснется элемента. Когда пользователь физически контактирует с контроллером, Touch для этого действия сообщит значение true. Когда пользователь нажмет на курок для указательного пальца, Button для этого действия сообщит значение true. Эти различные состояния можно использовать для точного обнаружения взаимодействия пользователя с контроллером и реализации различных схем управления.

Пример использования

Следующие примеры демонстрируют, как выполнять запросы различных типов ввода, включая кнопки, джойстики, курки и сенсорные элементы управления:

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

Помимо указания элемента управления, Get() также принимает необязательный параметр контроллера. Список поддерживаемых контроллеров определен в разделе "Контроллер перечисления" документа OVRInput.

Вы можете указать контроллер, если конкретная схема управления предназначена только для определенного типа контроллера. Если в Get() не указан параметр контроллера, по умолчанию будет использоваться контроллер Active, который соответствует контроллеру, который последним сообщил о вводе пользователя. Например, пользователь может использовать пару контроллеров, отложить их и взять контроллер Xbox. В этом случае активный контроллер переключится на контроллер Xbox, как только пользователь начнет вводить данные с помощью этого контроллера. Текущий активный контроллер можно запросить с помощью OVRInput.GetActiveController(), а битовая маска всех подключенных контроллеров может быть запрошена с помощью OVRInput.GetConnectedControllers().

В следующем примере показано, как явно указать комбинацию контроллеров для запроса курков на рукоятке левого и правого контроллеров:

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

Примечание. Контроллеры Meta Quest Touch можно указать либо в виде одной пары (с OVRInput.Controller.Touch), либо по отдельности (с OVRInput.Controller.LTouch и RTouch). Это важно, потому что при указании LTouch или RTouch используется другой набор виртуальных сопоставлений ввода, что позволяет более удобно разрабатывать код ввода, не зависящий от руки.

В следующем примере демонстрируется ввод, не зависящий от руки. Для этого используется PrimaryHandTrigger с отдельными контроллерами, где Primary всегда сопоставляется с указанной рукой:

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

Этот подход можно расширить, чтобы один и тот же код работал для любой руки. Для этого нужно указать контроллер в переменной, которая задается вне функции, например в общедоступной переменной.

В следующем примере показано, как написать код ввода с возможностью повторного использования, предоставив контроллер в виде настраиваемой переменной:

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

Это позволяет избежать распространенного паттерна проверок if/else для сопоставления ввода с левой или правой руки.

Сопоставление сенсорного ввода

Ниже приведены стандартные схемы ввода для контроллеров. Подробнее о доступных дополнительных сопоставлениях см. в справочной документации по API OVRInput.

Виртуальное сопоставление для комбинированных контроллеров

При доступе к контроллерам в виде объединенной пары с OVRInput.Controller.Touch виртуальное сопоставление точно соответствует расположению элементов управления на типичном геймпаде для левой и правой руки.

Виртуальное сопоставление для отдельных контроллеров

При доступе к левому или правому контроллеру по отдельности с помощью OVRInput.Controller.LTouch или OVRInput.Controller.RTouch виртуальное сопоставление меняется, что позволяет реализовать привязку ввода независимо от руки. Например, один и тот же скрипт может динамически запрашивать левый или правый контроллер в зависимости от того, к какой руке он прикреплен, а Button.One соответствующим образом сопоставляется с кнопкой A или X.

Примерная схема

Примерная схема контроллеров выглядит следующим образом: Размещение элементов контроллера в значительной мере соответствует стандартной конфигурации геймпада для левой и правой руки.