Добавить поддержку Android XR в существующий проект Godot XR

Применимые устройства XR
Данное руководство поможет вам создавать приложения для устройств XR такого типа.
Узнайте о типах устройств XR →
XR-гарнитуры
Проводные XR-очки
Узнайте о типах устройств XR →

Если у вас уже есть проект XR в Godot, вы можете добавить поддержку Android XR, не создавая новый отдельный проект. Некоторые шаги необходимы для всех проектов, в то время как другие являются необязательными в зависимости от функций XR, которые использует ваш проект. В описании шагов мы привели ссылки на несколько проектов Godot XR с открытым исходным кодом, в которых добавлена ​​поддержка Android XR, а также соответствующие запросы на слияние (pull requests), демонстрирующие изменения, необходимые для включения определенных функций.

Обязательные шаги для всех проектов

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

Обновите Godot и плагин Godot OpenXR Vendors.

Учитесь на примерах
Ознакомьтесь с запросом на слияние (pull request), чтобы изучить материал на реальном примере.

Выполните следующие шаги, чтобы обновить ваш проект до последних необходимых версий и настроить параметры проекта для Android XR:

  1. Обновите версию Godot до 4.6.2 или выше. Если вам нужна дополнительная помощь для вашего проекта, обратитесь к документации по миграции на новую версию .

  2. Загрузите плагин Godot OpenXR Vendors версии 5.1 или выше из Asset Store , Asset Library или репозитория на GitHub .

  3. Настройте параметры вашего проекта для Android XR:

    1. Добавить предустановку экспорта для Android XR.
    2. Включить использование команды `Gradle Build` .

    Включить

    1. В разделе «Функции XR» выберите OpenXR для режима XR и выберите «Включить плагин AndroidXR» .

    Настройте параметры в

Добавить поддержку отслеживания движений рук.

Учитесь на примерах
Ознакомьтесь с запросом на слияние (pull request), чтобы изучить материал на реальном примере.

Хотя контроллеры и доступны, основным методом ввода на Android XR-гарнитурах и XR-очках является отслеживание движений рук. По возможности, следует добавить поддержку отслеживания движений рук в ваш проект Godot.

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

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

  1. Откройте настройки вашего проекта и перейдите в раздел «Общие» > «XR» > «OpenXR» .

  2. В разделе «Расширения» выберите «Отслеживание движений рук» и «Профиль взаимодействия с руками» .

    Настройте параметры в

  3. В разделе «Расширения» найдите подраздел «Мета» и выберите «Hand Tracking Mesh» и «Hand Tracking Aim» .

    Настройте параметры в

Добавить поддержку отслеживания движений рук: добавить и настроить узлы контроллера.

Вместо динамического изменения существующих узлов XRController3D для отслеживания движений рук, добавьте узлы контроллера для отслеживания и отображения моделей рук, а также для обработки входных данных из расширения Hand Tracking Aim:

  1. Добавьте три дополнительных узла XRController3D к вашему узлу XROrigin3D .

    1. Присвойте одному из них имя "HandTrackingLeft" и установите свойство tracker в значение /user/hand_tracker/left .
    2. Назовите другой объект "HandTrackingRight" и установите свойство tracker равным /user/hand_tracker/right .
    3. Назовите последний объект "HandTrackingAimLeft" и установите свойство tracker равным /user/fbhandaim/left .

    Если бы исходные узлы XRController3D вашего проекта назывались "XRController3D_left" и "XRController3D_right", ваша сцена выглядела бы примерно так:

    Вот как может выглядеть ваша сцена после добавления узлов контроллера.

  2. Свяжите сигнал tracking_changed на контроллерах HandTrackingLeft и HandTrackingRight с отдельными функциями, которые обновляют видимость соответствующих трекеров контроллеров ( XRController3D_left и XRController3D_right в приведенном выше примере).

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

    func _on_hand_tracking_left_hand_tracking_changed(tracking):
    $XROrigin3D/XRController3D_left.visible = not tracking

  3. Включите свойство « Показывать при отслеживании» на узлах контроллера отслеживания рук.

    Теперь в вашем проекте можно визуально переключаться между моделями контроллеров и моделями отслеживания движений рук в зависимости от того, использует ли пользователь отслеживание движений рук или контроллеры.

  4. Добавьте несколько узлов OpenXRFbHandTrackingMesh в качестве дочерних элементов к узлам контроллера отслеживания движений рук.

  5. Добавьте узлы XRHandModifier3D в качестве дочерних элементов к этим узлам OpenXRFbHandTrackingMesh , убедившись, что установлено правильное свойство Hand Tracker , чтобы применять данные отслеживания движений рук в реальном времени к моделям.

    Вот как может выглядеть ваша сцена после добавления дочерних узлов к узлам контроллера.

Добавить поддержку отслеживания движений рук: Настройте профиль взаимодействия с руками на карте действий OpenXR.

Далее вам нужно будет настроить профиль взаимодействия с рукой на карте действий OpenXR :

  1. Откройте меню « Карта действий OpenXR» в нижней части редактора.
  2. Удалите профиль Simple Controller , чтобы избежать проблем с совместимостью с контроллерами Galaxy XR.
  3. Нажмите «Добавить профиль» , выберите «Взаимодействие с рукой» , а затем нажмите «ОК» .

  4. Назначьте этому профилю одно или несколько заданий по своему усмотрению.

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

Добавить поддержку отслеживания движений рук: настроить жест меню для Android XR

Наконец, вы можете реализовать жест меню для Android XR. Он отображает значок, когда левая рука игрока находится в правильном положении для выполнения жеста меню, а также показывает или скрывает меню, когда пользователь выполняет жест. Для этого вы будете использовать узел HandTrackingAimLeft , который вы добавили ранее .

  1. Добавьте к левому узлу отслеживания четырехугольник с рекламным щитом, отображающий выбранную вами иконку (см. узел MenuIcon на следующем изображении среди добавленных ранее узлов контроллера).

    Вот как может выглядеть ваша сцена после добавления дочерних узлов к узлам контроллера.

  2. Подключитесь к сигналам button_pressed и button_released на HandTrackingAimLeft для выполнения таких функций:

    @onready var menu_icon: MeshInstance3D = $XROrigin3D/HandTrackingLeft/MenuIcon

func _on_hand_tracking_aim_left_button_pressed(p_name):
  if p_name == "menu_pressed":
toggle_menu()
  elif p_name == "menu_gesture":
    if OS.has_feature("androidxr"):
      menu_icon.visible = true

func _on_hand_tracking_aim_left_button_released(p_name):
  if p_name == "menu_gesture":
    menu_icon.visible = false

Дополнительные шаги для некоторых функций

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

Регистрировать нажатия щипков как нажатия кнопок

В Android XR жест «щипка» используется для многих базовых системных действий , таких как выбор элементов, прокрутка, перемещение или изменение размера окон, а также перемещение элементов пользовательского интерфейса или объектов в 2D и 3D пространстве. Чтобы соответствовать этим шаблонам и обеспечить единообразный пользовательский опыт, ваше приложение должно регистрировать жесты «щипка» аналогично нажатиям кнопок на контроллере при использовании отслеживания движений рук.

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

const PRESSED_THRESHOLD := 0.8
const RELEASED_THRESHOLD := 0.6

@onready var left_controller: XRController3D = $XROrigin/XRController3D_left

func _on_xr_controller_3d_left_input_float_changed(p_name: String, value: float):
    if p_name == "pinch":
        var xr_tracker = XRServer.get_tracker(left_controller.tracker)
        if _left_hand_pinching:
            if value < RELEASED_THRESHOLD:
                _left_hand_pinching = false
                xr_tracker.set_input("pinch_pressed", false)
        else:
            if value > PRESSED_THRESHOLD:
                _left_hand_pinching = true
                xr_tracker.set_input("pinch_pressed", true)

Основные моменты, касающиеся кода.

  • Проверяет, превышает ли значение типа float заданные пороговые значения в сигналах input_float_changed XRController3D или нет.
  • Создает виртуальное действие с именем pinch_pressed .

Используйте функции XR Tools вместе с отслеживанием движений рук.

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

Например, при использовании FunctionPointer для взаимодействия с меню обновите свойство active_button_action , указав действие отслеживания руки на основе сигнала tracking_changed узлов XRController3D , отвечающих за отслеживание руки (в предыдущих шагах настройки отслеживания руки эти узлы назывались HandTrackingLeft и HandTrackingRight ).

const TRIGGER_POINTER_ACTION = "trigger_click"
const PINCH_POINTER_ACTION = "pinch_pressed"

@onready var func_point_left: XRToolsFunctionPointer = %FunctionPointerLeft

func _on_hand_tracking_left_tracking_changed(tracking: bool) -> void:
    if tracking:
        func_point_left.active_button_action = PINCH_POINTER_ACTION
else:
func_point_left.active_button_action = TRIGGER_POINTER_ACTION

Основные моменты, касающиеся кода.

Используйте отслеживание движений рук в сочетании с искусственным передвижением.

Если в вашем проекте используется искусственное передвижение, поддержка отслеживания движений рук по-прежнему возможна. Например, вы можете создать систему передвижения, которая позволит игрокам рисовать пути для перемещения с помощью жестов, или вы можете позволить игрокам двигать руками вверх и вниз для ускорения, с дополнительными жестами для прыжков, лазания и планирования.

В игре «Музей всего сущего » используется искусственное перемещение с помощью джойстиков на контроллерах. Отслеживание движения рук было реализовано путем добавления «виртуальных джойстиков», которые игрок активирует, сжимая руку в воздухе и перемещая ее в нужном направлении.

Вот некоторые ключевые моменты из запроса на слияние, в котором была реализована эта поддержка :

  • Сценарий XRVirtualThumbstick создается при обнаружении жеста масштабирования.
  • Пока удерживается щипок, относительное расстояние и направление от исходного положения щипка преобразуются в вектор Vector2 и виртуально сопоставляются с обычным вводом с помощью джойстика.
  • Визуальная обратная связь от этого ввода также предоставляется игроку в виде двух плоских четырехугольных моделей, иллюстрирующих положение джойстика.

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

Добавить поддержку сквозной передачи

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

Для этого внесите следующие изменения в код вашего приложения:

  • Установите параметр environment_blend_mode интерфейса OpenXR XRInterface в значение XR_ENV_BLEND_MODE_ALPHA_BLEND .
  • Установите параметр background_mode узла WorldEnvironment в BG_COLOR .
  • Установите background_color узла WorldEnvironment на любой полностью прозрачный цвет.
  • Установите свойство Viewport transparent_bg в true .

Используйте расширение для оценки освещенности.

При включении сквозной передачи данных рекомендуется использовать расширение Android XR Light Estimation OpenXR. Это расширение изменяет свойства WorldEnvironment и DirectionalLight3D для более точной имитации освещения реального мира пользователя, благодаря чему виртуальные объекты лучше сливаются с реальными условиями освещения. Вы можете включить это расширение в настройках своего проекта.

  1. Откройте настройки вашего проекта и перейдите в раздел «Общие» > «XR» > «OpenXR» .

  2. В разделе Androidxr выберите «Оценка освещенности» .

    Настройте параметры в

  3. Добавьте узел OpenXRAndroidLightEstimation в дерево сцены и подключите его к WorldEnvironment и DirectionalLight3D вашей сцены.

    Варианты для

Пример: Включение или отключение сквозной передачи и оценки освещенности.

Следующий код включает или отключает сквозную передачу и оценку освещенности:

@onready var world_environment = $WorldEnvironment
@onready var directional_light = $DirectionalLight3D
@onready var directional_light_orig_transform: Transform3D = directional_light.transform

func set_passthrough_enabled(p_enabled: bool) -> void:
    var xr_interface = XRServer.find_interface("OpenXR")
    if xr_interface == null:
        return

    var supported_blend_modes = xr_interface.get_supported_environment_blend_modes()
    if not supported_blend_modes.has(XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND):
        return

    # Passthrough
    if p_enabled:
        xr_interface.set_play_area_mode(XRInterface.XR_PLAY_AREA_STAGE)
        xr_interface.environment_blend_mode = XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND
        world_environment.environment.background_mode = Environment.BG_COLOR
        world_environment.environment.background_color = Color(0.0, 0.0, 0.0, 0.0)
        get_viewport().transparent_bg = true
    else:
        xr_interface.set_play_area_mode(XRInterface.XR_PLAY_AREA_ROOMSCALE)
        xr_interface.environment_blend_mode = XRInterface.XR_ENV_BLEND_MODE_OPAQUE
        world_environment.environment.background_mode = Environment.BG_SKY
        get_viewport().transparent_bg = false

    # Light Estimation
    if OS.has_feature("androidxr"):
        var light_estimation = Engine.get_singleton("OpenXRAndroidLightEstimationExtension")
        if p_enabled and light_estimation.is_light_estimation_supported():
            light_estimation.start_light_estimation()
        elif light_estimation.is_light_estimation_started():
            light_estimation.stop_light_estimation()
            directional_light.transform = directional_light_orig_transform
Основные моменты, касающиеся кода.
  • При отключении оценки освещенности необходимо вручную восстановить исходное направление объекта DirectionalLight3D .
  • Полный пример проекта, использующего сквозную передачу данных и оценку освещенности, можно найти в проекте Expedition to Blobotopia на GitLab.