Usar contêineres espaciais no Godot

Dispositivos XR relevantes
Estas orientações ajudam você a criar experiências para esses tipos de dispositivos XR.
Saiba mais sobre esses dispositivos →
Headsets XR
Óculos XR com fio
Saiba mais sobre esses dispositivos →

Os contêineres espaciais permitem que o app renderize conteúdo 3D do OpenXR dentro de uma caixa delimitadora volumétrica 3D gerenciada pelo sistema no Modo de Espaço Ampliado ou faça a transição em tempo de execução para uma experiência sem limites em tela cheia.

Siga este guia para configurar e usar contêineres espaciais no seu projeto.

Vários contêineres espaciais em execução no Modo de Espaço Ampliado no Android XR.
Figura 1. Contêineres espaciais no modo Espaço Ampliado, incluindo um contêiner de terreno 3D fixado ao chão e um modelo 3D pareado com uma interface 2D.

Como funcionam os contêineres espaciais

Ao ativar o contêiner espacial nas configurações do projeto:

  • Toda a cena 3D ativa é colocada em um único contêiner espacial principal centralizado na origem da cena (0, 0, 0). Não é necessário marcar ou atribuir nós Node3D individuais para colocá-los dentro do contêiner.
  • O app é iniciado no Modo de Espaço Ampliado gerenciado usando o Modo de Limites (Bounded ou Immersive) e as dimensões iniciais de Limites configuradas nas configurações do projeto. No modo limitado, o sistema corta automaticamente qualquer geometria 3D na cena que se estenda além das dimensões da caixa delimitadora.
  • Por padrão, o sistema Android XR oferece controles de janela para que o usuário possa pegar, mover e reposicionar o contêiner limitado no espaço 3D ou minimizá-lo e fechá-lo. No ambiente de execução, o app pode redimensionar o contêiner, alternar entre o modo limitado (OpenXRSpatialContainerState.BOUNDED) e o modo imersivo de tela cheia (OpenXRSpatialContainerState.IMMERSIVE) e reagir a mudanças de limites e estado usando o singleton OpenXRSpatialContainerExtension.

Pré-requisitos

Antes de começar, verifique se o ambiente de desenvolvimento e o dispositivo de destino atendem aos seguintes requisitos:

  • Versão do Godot: Godot 4.8-dev ou mais recente.
  • Configuração do projeto: conclua todas as etapas do guia de configuração do projeto do Godot Engine.
  • Plug-in Godot OpenXR Vendors: instale a versão 5.2 ou mais recente do plug-in Godot OpenXR Vendors, que permite o suporte a extensões específicas do Android XR.
  • Dispositivo de destino: um dispositivo Android XR com suporte ao nível 4 da API Spatial ou mais recente. No momento da execução, chame OpenXRSpatialContainerExtension.is_enabled() para verificar se a extensão está disponível no dispositivo.

Ativar contêineres espaciais nas configurações do projeto

Defina as configurações do projeto para ativar o OpenXR, os contêineres espaciais, as permissões de execução automáticas e o Passthrough com mesclagem alfa:

  1. Abra Project > Configurações do projeto.
  2. Ative a opção Configurações avançadas no canto superior direito da janela Configurações do projeto.
  3. Acesse Geral > XR > Shaders e selecione Ativado.
  4. Acesse General > XR > OpenXR e defina as seguintes configurações:
    • Selecione Ativado para ativar o OpenXR no projeto.
    • Defina Environment Blend Mode como Alpha Blend.
  5. Ainda em OpenXR, acesse a seção Extensions e defina as seguintes configurações:
    • Selecione Automatically Request Runtime Permissions para que o app solicite automaticamente ao usuário, na inicialização, todas as permissões de execução de XR declaradas no manifesto do Android.
    • Na subseção Contêiner espacial, selecione Ativado.
    • Defina o Modo de limites como Limitado para iniciar em uma caixa delimitadora 3D ou Imersivo para iniciar no modo imersivo em tela cheia.
    • Defina Limites como as dimensões iniciais de largura, altura e profundidade em metros, como Vector3(1.0, 1.0, 1.0).
  6. Acesse General > Rendering > Viewport e selecione Transparent Background.

Configurar a exportação, as permissões e o modo de Espaço Ampliado do Android

Em seguida, configure a predefinição de exportação, as permissões e o modo de início de atividade do Android para que o app seja executado no Modo de Espaço Ampliado com os contêineres espaciais ativados.

Configurar a predefinição de exportação do Android

  1. Acesse Project > Export... e selecione a predefinição de exportação do Android.

  2. Em Gradle Build, selecione Use Gradle Build e defina Min SDK como 34 ou mais recente.

    Ative o

  3. Em XR Features, defina XR Mode como OpenXR e selecione Enable AndroidXR Plugin.

    Configure as opções na

  4. Em Recursos do Android XR, selecione Usar recursos experimentais.

Adicionar permissões de compreensão de cena para o bloqueio de piso

A criação e a renderização de um contêiner espacial básico não exigem permissões de execução perigosas, e android.permission.HEAD_TRACKING é adicionado ao manifesto automaticamente quando a opção Usar recursos experimentais está ativada. No entanto, se o app usa recursos de compreensão de cena, como bloquear e fixar um contêiner espacial no chão físico, ele precisa declarar e solicitar a permissão android.permission.SCENE_UNDERSTANDING_COARSE no momento da execução.

Consulte Noções básicas sobre permissões para XR para mais detalhes sobre as permissões do Android XR. Se o app usa o bloqueio de piso ou a compreensão de cena, declare e solicite android.permission.SCENE_UNDERSTANDING_COARSE:

  1. Em Projeto > Exportar... > Android, acesse Permissions > Custom Permissions e adicione android.permission.SCENE_UNDERSTANDING_COARSE.

  2. Quando você seleciona Automatically Request Runtime Permissions em Project Settings > General > XR > OpenXR > Extensions, o app solicita automaticamente a permissão quando o OpenXR é iniciado. Se você precisar solicitar a permissão manualmente no GDScript, chame OS.request_permission():

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

Configurar o Modo de Espaço Ampliado

Os contêineres espaciais no Android XR só oferecem suporte ao modo de espaço ampliado (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED). Verifique se a atividade do Android declara XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED no modelo de build personalizado (android/build/AndroidManifest.xml, instalado usando 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>

Trabalhar com contêineres espaciais no GDScript

O singleton OpenXRSpatialContainerExtension e a classe OpenXRSpatialContainerState expõem as extensões XR_EXT_spatial_container e XR_EXT_spatial_container_self_rendering ao GDScript. No momento da execução, use OpenXRSpatialContainerExtension para inspecionar o estado e os limites do contêiner espacial principal, detectar sinais do contêiner e solicitar transições entre o modo BOUNDED (uma caixa delimitadora 3D) e o modo IMMERSIVE (uma visualização sem limites em tela cheia).

Conectar-se aos indicadores do Spatial Container

Verifique OpenXRSpatialContainerExtension.is_enabled() para conferir se a extensão de contêiner espacial é compatível e está ativa no dispositivo atual e se conecte aos limites do contêiner e aos indicadores de estado em _ready().

OpenXRSpatialContainerExtension emite os seguintes indicadores de estado para o contêiner espacial:

  • spatial_container_visibility_changed: emitido com (spatial_container, is_visible) quando o contêiner é mostrado (true) ou ocultado (false). Pause animações, áudio ou atualizações de simulação quando is_visible for false.
  • spatial_container_interactability_changed: emitido com (spatial_container, is_interactive) quando o contêiner ganha (true) ou perde (false) o foco de entrada do usuário. Ativar ou desativar destaques interativos e processamento de entrada quando o foco muda.
  • spatial_container_bounds_mode_changed: emitido com (spatial_container, bounds_mode) quando o contêiner alterna entre OpenXRSpatialContainerState.BOUNDED e OpenXRSpatialContainerState.IMMERSIVE. Alternar os recursos visuais do ambiente (como skyboxes ou transmissão) e os controles de UI específicos do 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

Dimensionar o conteúdo 3D para os limites do contêiner

No modo BOUNDED, dimensione o conteúdo 3D de maneira uniforme pela menor dimensão de bounds para que ele preserve a proporção e sempre caiba no menor lado do contêiner. Ao fazer a transição para o modo IMMERSIVE, restaure a cena para a 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

Alternar entre os modos limitado e imersivo

Chame request_main_spatial_container_bounds_mode com OpenXRSpatialContainerState.BOUNDED ou OpenXRSpatialContainerState.IMMERSIVE para alternar entre um volume 3D limitado e uma visualização imersiva em tela cheia:

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

Consulte também

OpenXR™ e o logotipo do OpenXR são marcas registradas do The Khronos Group Inc. e são registradas como marcas na China, na União Europeia, no Japão e no Reino Unido.