Agrega compatibilidad con Android XR a un proyecto de Godot XR existente

Dispositivos de realidad extendida correspondientes
Esta guía te ayuda a crear experiencias para estos tipos de dispositivos de realidad extendida.
Más información sobre los tipos de dispositivos de realidad extendida →
Visores de realidad extendida
Lentes de realidad extendida con cable
Más información sobre los tipos de dispositivos de realidad extendida →

Si tienes un proyecto de realidad extendida existente en Godot, puedes agregar compatibilidad con Android XR sin iniciar un proyecto nuevo y separado. Algunos pasos son obligatorios para todos los proyectos, mientras que otros son opcionales según las funciones de realidad extendida que use tu proyecto. A lo largo de los pasos, incluimos vínculos a varios proyectos de realidad extendida de Godot de código abierto que agregaron compatibilidad con Android XR, junto con solicitudes de extracción pertinentes que muestran los cambios necesarios para habilitar ciertas funciones.

Pasos obligatorios para todos los proyectos

Completa los pasos de los siguientes temas, sin importar qué tipos de funciones de realidad extendida admita tu proyecto. Luego, revisa las funciones que se describen en la lista de pasos opcionales para determinar si tu proyecto requiere trabajo adicional.

Actualiza Godot y el complemento de proveedores de OpenXR de Godot

Sigue estos pasos para actualizar tu proyecto a las versiones obligatorias más recientes y configurar los parámetros de configuración de tu proyecto para Android XR:

  1. Actualiza tu versión de Godot a 4.6.2 o una posterior. Consulta la documentación sobre la migración a una versión nueva si necesitas ayuda adicional para tu proyecto.

  2. Descarga el complemento de proveedores de OpenXR de Godot versión 5.1 o posterior desde Asset Store, Asset Library o el repositorio en GitHub.

  3. Configura los parámetros de configuración de tu proyecto para Android XR:

    1. Agrega un ajuste predeterminado de exportación para Android XR.
    2. Habilita Usar compilación de Gradle.

    Habilita la opción

    1. En la sección Funciones de realidad extendida, selecciona OpenXR para el Modo de realidad extendida, y selecciona Habilitar complemento de AndroidXR.

    Configura las opciones en el

Agrega compatibilidad con el monitoreo de manos

Si bien los controles pueden estar disponibles, el método de entrada principal en los visores de realidad extendida y los lentes de realidad extendida de Android XR es el monitoreo de manos. Si es posible, debes agregar compatibilidad con el seguimiento de manos a tu proyecto de Godot.

Agrega compatibilidad con el monitoreo de manos: Configura los parámetros de configuración del proyecto

Primero, sigue estos pasos para configurar los parámetros de configuración de tu proyecto para habilitar el seguimiento de manos y sus extensiones de OpenXR relacionadas.

  1. Abre los parámetros de configuración de tu proyecto y navega a General > XR > OpenXR.

  2. En la sección Extensiones, selecciona Seguimiento de manos y Perfil de interacción con las manos.

    Configura las opciones en el

  3. Busca la subsección Meta en la sección Extensiones y selecciona Malla de seguimiento de manos y Objetivo de seguimiento de manos.

    Configura las opciones en el

Agrega compatibilidad con el monitoreo de manos: Agrega y configura nodos de control

En lugar de modificar de forma dinámica los nodos XRController3D existentes para el seguimiento de manos, agrega nodos de control para realizar un seguimiento y mostrar los modelos de manos, así como para controlar la entrada de la extensión Objetivo de seguimiento de manos:

  1. Agrega tres nodos XRController3D adicionales a tu nodo XROrigin3D.

    1. Asigna el nombre "HandTrackingLeft" a uno y establece la propiedad del rastreador en /user/hand_tracker/left.
    2. Asigna el nombre "HandTrackingRight" a otro y establece la propiedad del rastreador en /user/hand_tracker/right.
    3. Asigna el nombre "HandTrackingAimLeft" al último y establece la propiedad del rastreador en /user/fbhandaim/left.

    Si los nodos XRController3D originales de tu proyecto se llamaban "XRController3D_left" y "XRController3D_right", tu escena se vería de la siguiente manera:

    Cómo podría verse tu escena después de agregar los nodos del controlador

  2. Conecta la señal tracking_changed en HandTrackingLeft y HandTrackingRight a funciones individuales que actualicen la visibilidad de los rastreadores de control correspondientes (XRController3D_left y XRController3D_right en el ejemplo anterior).

    Por ejemplo, la función conectada a la señal en HandTrackingLeft podría verse de la siguiente manera:

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

  3. Habilita la propiedad Mostrar cuando se monitorea en los nodos de control de monitoreo de manos.

    Ahora, tu proyecto puede intercambiar visualmente entre modelos de control y modelos de monitoreo de manos, según si el usuario usa el monitoreo de manos o los controles.

  4. Agrega algunos nodos OpenXRFbHandTrackingMesh como elementos secundarios a los nodos de control de monitoreo de manos.

  5. Agrega nodos XRHandModifier3D como elementos secundarios a estos nodos OpenXRFbHandTrackingMesh y asegúrate de que se establezca la propiedad Hand Tracker correcta para aplicar datos de monitoreo de manos en tiempo real a los modelos.

    Así podría verse tu escena después de agregar los nodos secundarios a los nodos del controlador.

Agrega compatibilidad con el monitoreo de manos: Configura un perfil de interacción con las manos en el mapa de acciones de OpenXR

A continuación, configurarás el perfil de interacción con las manos en el mapa de acciones de OpenXR :

  1. Abre el menú Mapa de acciones de OpenXR en la parte inferior del editor.
  2. Borra el perfil Controlador simple para evitar problemas de compatibilidad con los controles de Galaxy XR.
  3. Haz clic en Agregar perfil, selecciona Interacción con las manos y, luego, haz clic en Aceptar.

  4. Asigna este perfil a uno o más conjuntos de acciones como quieras.

Según los requisitos de tu app, es posible que también quieras ajustar la forma en que tu app controla la entrada del usuario con el monitoreo de manos.

Agrega compatibilidad con el monitoreo de manos: Configura un gesto de menú para Android XR

Por último, puedes implementar un gesto de menú para Android XR. Esto muestra un ícono cuando la mano izquierda del jugador está en la posición correcta para realizar el gesto de menú, además de mostrar u ocultar el menú cuando el usuario realiza el gesto. Usarás el nodo HandTrackingAimLeft que agregaste antes para controlar esto.

  1. Agrega un quad con cartelera al nodo de monitoreo de manos izquierdo que muestre un ícono que elegiste (consulta el nodo MenuIcon en la siguiente imagen de los nodos de control que agregaste antes).

    Así podría verse tu escena después de agregar los nodos secundarios a los nodos del controlador.

  2. Conéctate a las señales button_pressed y button_released en HandTrackingAimLeft a funciones como esta:

    @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

Pasos opcionales para ciertas funciones

Después de completar los pasos obligatorios para tu proyecto, decides si necesitas realizar trabajo adicional para ciertas funciones, según los requisitos y las capacidades de tu app. Para obtener más información sobre cada una de estas funciones opcionales, consulta las siguientes secciones.

Registra los pellizcos como presiones de botones

En Android XR, el pellizco se usa para muchas acciones fundamentales del sistema, como seleccionar elementos, desplazarse, mover o cambiar el tamaño de las ventanas, y mover elementos o objetos de la IU en espacios 2D y 3D. Para alinearse con estos patrones y promover una experiencia del usuario coherente, tu app debe registrar los pellizcos de manera similar a las presiones de botones en un control cuando se usa el monitoreo de manos.

Para configurar tu app de esta manera, usa los valores de número de punto flotante que proporciona el perfil de interacción con las manos que creaste para crear una acción virtual:

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)

Puntos clave sobre el código

  • Verifica si el valor float es mayor o menor que los umbrales específicos en las señales XRController3D input_float_changed.
  • Crea una acción virtual llamada pinch_pressed.

Usa las funciones de XR Tools junto con el monitoreo de manos

Muchos proyectos de realidad extendida de Godot utilizan XR Tools de Godot, incluidos algunos de los proyectos de código abierto que se vinculan en esta página. Para que funcionen algunas funciones de XR Tools, como FunctionPointer para las interacciones de menú, necesitarás código adicional para intercambiar la acción que busca cuando el usuario cambia al monitoreo de manos.

Por ejemplo, cuando uses FunctionPointer para las interacciones de menú, actualiza la active_button_action propiedad a la acción de monitoreo de manos según la tracking_changed señal de los XRController3D nodos para el monitoreo de manos (estos nodos eran HandTrackingLeft y HandTrackingRight en los pasos anteriores de configuración del monitoreo de manos).

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

Puntos clave sobre el código

Usa el monitoreo de manos junto con la locomoción artificial

Si tu proyecto usa la locomoción artificial, aún es posible la compatibilidad con el monitoreo de manos. Por ejemplo, puedes crear un sistema de movimiento que permita a los jugadores dibujar rutas para atravesar con un gesto, o puedes permitir que los jugadores bombeen sus manos hacia arriba y hacia abajo para acelerar, con gestos adicionales para saltar, escalar y deslizarse.

El Museo de todas las cosas tiene locomoción artificial con los joysticks de los controles. La locomoción de monitoreo de manos se implementó agregando "joysticks virtuales" que el jugador activa pellizcando en el aire y moviendo la mano en la dirección en la que quiere que se mueva ese joystick.

Estos son algunos de los puntos clave de la solicitud de extracción que implementó esta compatibilidad:

  • Se crea una instancia de una escena XRVirtualThumbstick cuando se detecta un pellizco.
  • Mientras se mantiene el pellizco, la distancia y la dirección relativas desde la ubicación original del pellizco se convierten en un Vector2 y se asignan virtualmente a la entrada normal del joystick.
  • También se le proporciona al jugador feedback visual de esta entrada en forma de dos mallas quad con cartelera, que ilustran la posición del joystick.

Puedes probar un enfoque similar para que tu código de locomoción existente basado en joystick funcione con cambios mínimos. Sin embargo, es posible que tu proyecto aún requiera una solución de locomoción personalizada para el monitoreo de manos.

Agrega compatibilidad con el modo de transmisión

Puedes agregar compatibilidad con el modo de transmisión a tu app para que los usuarios puedan ver su entorno del mundo real.

Para hacerlo en tu app, realiza los siguientes cambios de código:

  • Establece el environment_blend_mode de OpenXR XRInterface en XR_ENV_BLEND_MODE_ALPHA_BLEND.
  • Establece el background_mode del nodo WorldEnvironment en BG_COLOR.
  • Establece el background_color del nodo WorldEnvironment en cualquier color que sea completamente transparente.
  • Establece la propiedad Viewport transparent_bg en true.

Usa la extensión de estimación de luz

Cuando habilites el modo de transmisión, considera usar la extensión de OpenXR de estimación de luz de Android XR. Esta extensión ajusta las propiedades de WorldEnvironment y DirectionalLight3D para emular mejor la iluminación del entorno del mundo real de un usuario, de modo que los objetos virtuales se combinen mejor con las condiciones de iluminación del mundo real. Puedes habilitar esta extensión en la configuración de tu proyecto.

  1. Abre los parámetros de configuración de tu proyecto y navega a General > XR > OpenXR.

  2. En la sección Androidxr, selecciona Estimación de luz.

    Configura las opciones en el

  3. Agrega un nodo OpenXRAndroidLightEstimation al árbol de escena y conéctalo a WorldEnvironment y DirectionalLight3D de tu escena.

    Opciones para el

Ejemplo: Habilita o inhabilita el modo de transmisión y la estimación de luz

El siguiente código habilita o inhabilita el modo de transmisión y la estimación de luz:

@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
Puntos clave sobre el código
  • Cuando se inhabilita la estimación de luz, se debe restablecer manualmente la dirección original de DirectionalLight3D.
  • Para obtener un ejemplo completo de un proyecto que usa el modo de transmisión y la estimación de luz, consulta Expedition to Blobotopia en GitLab.