Usa contenedores espaciales en Godot

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 →

Los contenedores espaciales permiten que tu app renderice contenido de OpenXR en 3D dentro de un cuadro delimitador volumétrico en 3D administrado por el sistema en el modo de espacio completo o que realice la transición en el entorno de ejecución a una experiencia sin límites en pantalla completa.

Sigue esta guía para configurar y usar Spatial Containers en tu proyecto.

Varios contenedores espaciales que se ejecutan en el modo de espacio completo en Android XR.
Figura 1: Contenedores espaciales en el modo de espacio completo, incluido un contenedor de terreno 3D bloqueado en el suelo y un modelo 3D vinculado con una IU en 2D.

Cómo funcionan los contenedores espaciales

Cuando habilitas Spatial Container en la configuración del proyecto, ocurre lo siguiente:

  • Toda tu escena 3D activa se coloca dentro de un único contenedor espacial principal centrado en el origen de la escena (0, 0, 0). No necesitas etiquetar ni asignar nodos Node3D individuales para colocarlos dentro del contenedor.
  • Tu app se inicia en el modo de espacio completo administrado con el modo de límites (Bounded o Immersive) y las dimensiones de límites iniciales configuradas en los parámetros de configuración del proyecto. En el modo limitado, el sistema recorta automáticamente cualquier geometría 3D de tu escena que se extienda fuera de las dimensiones del cuadro delimitador.
  • De forma predeterminada, el sistema de Android XR proporciona controles de ventana para que el usuario pueda tomar, mover y cambiar la posición del contenedor limitado en el espacio 3D, o bien minimizarlo y cerrarlo. Durante el tiempo de ejecución, tu app puede cambiar el tamaño del contenedor, alternar entre el modo limitado (OpenXRSpatialContainerState.BOUNDED) y el modo envolvente de pantalla completa (OpenXRSpatialContainerState.IMMERSIVE), y reaccionar a los cambios de límites y estado con el singleton OpenXRSpatialContainerExtension.

Requisitos previos

Antes de comenzar, asegúrate de que tu entorno de desarrollo y el dispositivo de destino cumplan con los siguientes requisitos:

  • Versión de Godot: Godot 4.8-dev o posterior.
  • Configuración del proyecto: Completa todos los pasos de la guía de configuración del proyecto de Godot Engine.
  • Complemento de proveedores de OpenXR de Godot: Instala la versión 5.2 o posterior del complemento de proveedores de OpenXR de Godot, que habilita la compatibilidad con extensiones específicas de Android XR.
  • Dispositivo de destino: Un dispositivo Android XR que admita el nivel de API espacial 4 o uno superior En el entorno de ejecución, llama a OpenXRSpatialContainerExtension.is_enabled() para verificar si la extensión está disponible en el dispositivo.

Habilita los contenedores espaciales en la configuración del proyecto

Establece la configuración del proyecto para habilitar OpenXR, los contenedores espaciales, los permisos de tiempo de ejecución automáticos y la transferencia con combinación alfa:

  1. Abre Project > Configuración del proyecto.
  2. Habilita el botón de activación Configuración avanzada en la esquina superior derecha de la ventana Configuración del proyecto.
  3. Navega a General > XR > Shaders y selecciona Enabled.
  4. Navega a General > XR > OpenXR y establece los siguientes parámetros de configuración:
    • Selecciona Enabled para activar OpenXR en el proyecto.
    • Establece el Modo de combinación del entorno en Combinación alfa.
  5. También en OpenXR, ve a la sección Extensions y establece los siguientes parámetros de configuración:
    • Selecciona Automatically Request Runtime Permissions para que tu app solicite automáticamente al usuario, durante el inicio, los permisos de XR declarados en el manifiesto de Android.
    • En el apartado Contenedor espacial, selecciona Habilitado.
    • Establece Bounds Mode en Bounded para iniciar en un cuadro delimitador 3D o en Immersive para iniciar en el modo envolvente de pantalla completa.
    • Establece Bounds en las dimensiones iniciales de ancho, alto y profundidad en metros, como Vector3(1.0, 1.0, 1.0).
  6. Navega a General > Rendering > Viewport y selecciona Transparent Background.

Configura la exportación, los permisos y el modo de espacio completo de Android

A continuación, configura el ajuste predeterminado de exportación de Android, los permisos y el modo de inicio de la actividad para que la app se ejecute en el modo de espacio completo con los contenedores espaciales habilitados.

Configura el ajuste predeterminado de exportación de Android

  1. Ve a Project > Export… y selecciona el ajuste predeterminado de exportación de Android.

  2. En Gradle Build, selecciona Use Gradle Build y establece Min SDK en 34 o una versión posterior.

    Habilita la

  3. En XR Features, establece XR Mode en OpenXR y selecciona Enable AndroidXR Plugin.

    Configura las opciones en el

  4. En Android XR Features, selecciona Use Experimental Features.

Agrega permisos de comprensión de escenas para el bloqueo de piso

La creación y renderización de un contenedor espacial básico no requiere permisos de tiempo de ejecución peligrosos (y android.permission.HEAD_TRACKING se agrega al manifiesto automáticamente cuando se habilita Use Experimental Features). Sin embargo, si tu app usa funciones de comprensión de escenas, como bloquear y fijar un contenedor espacial al piso físico, debe declarar y solicitar el permiso android.permission.SCENE_UNDERSTANDING_COARSE en el entorno de ejecución.

Consulta Información sobre los permisos para la RE para obtener detalles sobre los permisos de Android XR. Si tu app usa el bloqueo de piso o la comprensión de escenas, declara y solicita android.permission.SCENE_UNDERSTANDING_COARSE:

  1. En Project > Export… > Android, ve a Permissions > Custom Permissions y agrega android.permission.SCENE_UNDERSTANDING_COARSE.

  2. Cuando seleccionas Automatically Request Runtime Permissions en Project Settings > General > XR > OpenXR > Extensions, tu app solicita automáticamente el permiso cuando se inicia OpenXR. Si, en cambio, necesitas solicitar el permiso de forma manual en GDScript, llama a OS.request_permission():

    if not OS.get_granted_permissions().has("android.permission.SCENE_UNDERSTANDING_COARSE"):
    OS.request_permission("android.permission.SCENE_UNDERSTANDING_COARSE")

Configura el modo de espacio completo

Los contenedores espaciales en Android XR solo admiten el modo de espacio completo (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED). Asegúrate de que tu actividad de Android declare XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED en tu plantilla de compilación personalizada (android/build/AndroidManifest.xml, instalada con Project > Install Android Build Template…):

<manifest ...>
    <application ...>
        <property
            android:name="android.window.PROPERTY_XR_ACTIVITY_START_MODE"
            android:value="XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED"
            tools:replace="android:value" />
        ...
    </application>
</manifest>

Trabaja con contenedores espaciales en GDScript

El singleton OpenXRSpatialContainerExtension y la clase OpenXRSpatialContainerState exponen las extensiones XR_EXT_spatial_container y XR_EXT_spatial_container_self_rendering a GDScript. En el entorno de ejecución, usa OpenXRSpatialContainerExtension para inspeccionar el estado y los límites del contenedor espacial principal, escuchar las señales del contenedor y solicitar transiciones entre el modo BOUNDED (un cuadro delimitador 3D) y el modo IMMERSIVE (una vista sin límites de pantalla completa).

Conéctate a los indicadores de Spatial Container

Verifica OpenXRSpatialContainerExtension.is_enabled() para comprobar que la extensión de Spatial Container sea compatible y esté activa en el dispositivo actual, y conéctate a los límites del contenedor y a los indicadores de estado en _ready().

OpenXRSpatialContainerExtension emite los siguientes indicadores de estado para el contenedor espacial:

  • spatial_container_visibility_changed: Se emite con (spatial_container, is_visible) cuando se muestra (true) o se oculta (false) el contenedor. Pausa las animaciones, el audio o las actualizaciones de simulación cuando is_visible sea false.
  • spatial_container_interactability_changed: Se emite con (spatial_container, is_interactive) cuando el contenedor obtiene (true) o pierde (false) el enfoque de entrada del usuario. Habilita o inhabilita los elementos destacados interactivos y el control de entradas cuando cambia el enfoque.
  • spatial_container_bounds_mode_changed: Se emite con (spatial_container, bounds_mode) cuando el contenedor cambia entre OpenXRSpatialContainerState.BOUNDED y OpenXRSpatialContainerState.IMMERSIVE. Activar o desactivar los elementos visuales del entorno (como skyboxes o transferencia) y los controles de la IU específicos del modo
func _ready() -> void:
    if OpenXRSpatialContainerExtension.is_enabled():
        OpenXRSpatialContainerExtension.spatial_container_bounds_changed.connect(
            _on_bounds_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_bounds_mode_changed.connect(
            _on_bounds_mode_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_visibility_changed.connect(
            _on_visibility_changed
        )
        OpenXRSpatialContainerExtension.spatial_container_interactability_changed.connect(
            _on_interactability_changed
        )

func _on_visibility_changed(_rid: RID, is_visible: bool) -> void:
    # Pause or resume simulation and audio based on visibility
    pass

func _on_interactability_changed(_rid: RID, is_interactive: bool) -> void:
    # Enable or disable input handling and focus highlights
    pass

Ajusta la escala del contenido 3D a los límites del contenedor

Cuando estés en el modo BOUNDED, escala el contenido 3D de manera uniforme según la dimensión más pequeña de bounds para que conserve su relación de aspecto y siempre quepa en el lado más pequeño del contenedor. Cuando hagas la transición al modo IMMERSIVE, restablece la escena a su escala 1:1:

func _on_bounds_changed(_rid: RID, bounds: Vector3) -> void:
    var uniform_scale: float = min(bounds.x, bounds.y, bounds.z)
    content_root.scale = Vector3.ONE * uniform_scale

func _on_bounds_mode_changed(
    _rid: RID, bounds_mode: OpenXRSpatialContainerState.BoundsMode
) -> void:
    if bounds_mode == OpenXRSpatialContainerState.IMMERSIVE:
        content_root.scale = Vector3.ONE

Cómo cambiar entre los modos limitado y envolvente

Llama a request_main_spatial_container_bounds_mode con OpenXRSpatialContainerState.BOUNDED o OpenXRSpatialContainerState.IMMERSIVE para alternar entre un volumen 3D limitado y una vista envolvente de pantalla completa:

# Request transitioning to immersive mode (or pass BOUNDED to return)
OpenXRSpatialContainerExtension.request_main_spatial_container_bounds_mode(
    OpenXRSpatialContainerState.IMMERSIVE
)

Consulta también

OpenXR™ y el logotipo de OpenXR son marcas comerciales de The Khronos Group Inc. y están registradas como marcas comerciales en China, la Unión Europea, Japón y el Reino Unido.