Używanie kontenerów przestrzennych w Godot

Odpowiednie urządzenia z XR

Te wskazówki pomogą Ci tworzyć treści na te typy urządzeń z XR.

Więcej informacji o typach urządzeń XR →

Więcej informacji o typach urządzeń XR →

Kontenery przestrzenne umożliwiają aplikacji renderowanie treści 3D OpenXR w ramach zarządzanej przez system trójwymiarowej ramki ograniczającej w trybie pełnej przestrzeni lub przechodzenie w czasie działania do nieograniczonego trybu pełnoekranowego.

Z tego przewodnika dowiesz się, jak skonfigurować kontenery przestrzenne i używać ich w projekcie.

Jak działają kontenery przestrzenne

Gdy włączysz kontener przestrzenny w ustawieniach projektu:

• Cała aktywna scena 3D jest umieszczona w jednym głównym kontenerze przestrzennym wyśrodkowanym w punkcie początkowym sceny (0, 0, 0). Nie musisz oznaczać tagami ani przypisywać poszczególnych węzłów Node3D, aby umieścić je w kontenerze.
• Aplikacja uruchamia się w zarządzanym trybie pełnej przestrzeni przy użyciu trybu granic (Bounded lub Immersive) i początkowych wymiarów granic skonfigurowanych w ustawieniach projektu. W trybie ograniczonym system automatycznie przycina wszystkie elementy geometrii 3D w scenie, które wykraczają poza wymiary ramki ograniczającej.
• Domyślnie system Android XR udostępnia elementy sterujące oknem, dzięki którym użytkownik może chwytać, przenosić i zmieniać położenie kontenera ograniczonego w przestrzeni 3D, a także minimalizować go i zamykać. W czasie działania aplikacja może zmieniać rozmiar kontenera, przełączać się między trybem ograniczonym (OpenXRSpatialContainerState.BOUNDED) a trybem imersji na pełnym ekranie (OpenXRSpatialContainerState.IMMERSIVE) oraz reagować na zmiany granic i stanu za pomocą obiektu singleton OpenXRSpatialContainerExtension.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że środowisko programistyczne i urządzenie docelowe spełniają te wymagania:

• Wersja Godot: Godot 4.8-dev lub nowsza.
• Konfiguracja projektu: wykonaj wszystkie czynności opisane w przewodniku Konfigurowanie projektu w silniku Godot.
• Wtyczka Godot OpenXR Vendors: zainstaluj wtyczkę Godot OpenXR Vendors w wersji 5.2 lub nowszej, która obsługuje rozszerzenia na Androida XR.
• Urządzenie docelowe: urządzenie z Androidem XR obsługujące interfejs Spatial API na poziomie 4 lub wyższym. W czasie działania wywołaj OpenXRSpatialContainerExtension.is_enabled(), aby sprawdzić, czy rozszerzenie jest dostępne na urządzeniu.

Włącz kontenery przestrzenne w ustawieniach projektu

Skonfiguruj ustawienia projektu, aby włączyć OpenXR, kontenery przestrzenne, automatyczne uprawnienia w czasie działania i tryb passthrough z mieszaniem alfa:

1. Kliknij Project > Project Settings (Projekt > Ustawienia projektu).
2. Włącz przełącznik Ustawienia zaawansowane w prawym górnym rogu okna Ustawienia projektu.
3. Kliknij General > XR > Shaders (Ogólne > XR > Shadery) i wybierz Enabled (Włączone).
4. Kliknij General > XR > OpenXR (Ogólne > XR > OpenXR) i skonfiguruj te ustawienia:
   • Wybierz Włączone, aby włączyć OpenXR w projekcie.
   • Ustaw Environment Blend Mode (Tryb mieszania środowiska) na Alpha Blend (Mieszanie alfa).
5. W sekcji OpenXR przejdź do sekcji Rozszerzenia i skonfiguruj te ustawienia:
   • Wybierz Automatically Request Runtime Permissions (Automatycznie proś o uprawnienia w czasie działania), aby aplikacja automatycznie prosiła użytkownika przy uruchamianiu o uprawnienia XR zadeklarowane w pliku manifestu Androida.
   • W podsekcji Kontener przestrzenny wybierz Włączone.
   • Ustaw Tryb granic na Ograniczony, aby uruchomić aplikację w ramce ograniczającej 3D, lub Imersyjny, aby uruchomić ją w trybie imersyjnym na pełnym ekranie.
   • Ustaw Granice na początkowe wymiary szerokości, wysokości i głębokości w metrach, np. Vector3(1.0, 1.0, 1.0).
6. Kliknij General > Rendering > Viewport (Ogólne > Renderowanie > Widoczny obszar) i wybierz Transparent Background (Przezroczyste tło).

Konfigurowanie eksportu na Androida, uprawnień i trybu pełnej przestrzeni

Następnie skonfiguruj gotowe ustawienia eksportu na Androida, uprawnienia i tryb uruchamiania aktywności, aby aplikacja działała w trybie pełnej przestrzeni z włączonymi kontenerami przestrzennymi.

Konfigurowanie gotowych ustawień eksportu na Androida

1. Kliknij Project > Export… (Projekt > Eksportuj…) i wybierz gotowe ustawienia eksportu na Androida.

2. W sekcji Gradle Build (Kompilacja Gradle) wybierz Use Gradle Build (Użyj kompilacji Gradle) i ustaw Min SDK (Minimalna wersja pakietu SDK) na 34 lub nowszą.

   

3. W sekcji Funkcje XR ustaw Tryb XR na OpenXR i wybierz Włącz wtyczkę AndroidXR.

   

4. W sekcji Funkcje Androida XR wybierz Używaj funkcji eksperymentalnych.

Dodawanie uprawnień do rozpoznawania sceny na potrzeby blokowania podłogi

Tworzenie i renderowanie podstawowego kontenera przestrzennego nie wymaga niebezpiecznych uprawnień w czasie działania aplikacji (a uprawnienie android.permission.HEAD_TRACKING jest dodawane do pliku manifestu automatycznie, gdy włączona jest opcja Używaj funkcji eksperymentalnych). Jeśli jednak aplikacja korzysta z funkcji rozpoznawania sceny, takich jak blokowanie i kotwiczenie kontenera przestrzennego na fizycznej podłodze, musi zadeklarować uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE i poprosić o nie w czasie działania.

Szczegółowe informacje o uprawnieniach Androida XR znajdziesz w artykule Informacje o uprawnieniach XR. Jeśli aplikacja korzysta z blokowania podłogi lub rozpoznawania sceny, zadeklaruj i poproś o uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE:

1. Wybierz Projekt > Eksportuj… > Android, otwórz Uprawnienia > Uprawnienia niestandardowe i dodaj android.permission.SCENE_UNDERSTANDING_COARSE.

2. Gdy w sekcji Project Settings > General > XR > OpenXR > Extensions (Ustawienia projektu > Ogólne > XR > OpenXR > Rozszerzenia) wybierzesz Automatically Request Runtime Permissions (Automatycznie proś o uprawnienia w czasie działania), aplikacja będzie automatycznie prosić o uprawnienia po uruchomieniu OpenXR. Jeśli musisz ręcznie poprosić o uprawnienia w GDScript, wywołaj OS.request_permission():

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

Konfigurowanie trybu pełnej przestrzeni

Kontenery przestrzenne na Androidzie XR obsługują tylko tryb pełnej przestrzeni (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED). Upewnij się, że aktywność na Androidzie deklaruje XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED w niestandardowym szablonie kompilacji (android/build/AndroidManifest.xml, zainstalowanym za pomocą opcji 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>

Praca z kontenerami przestrzennymi w GDScript

Klasa pojedyncza OpenXRSpatialContainerExtension i klasa OpenXRSpatialContainerState udostępniają rozszerzenia XR_EXT_spatial_container i XR_EXT_spatial_container_self_rendering dla GDScript. W czasie działania używaj OpenXRSpatialContainerExtension, aby sprawdzać stan i granice głównego kontenera przestrzennego, nasłuchiwać sygnałów kontenera i żądać przejść między trybem BOUNDED (ramka ograniczająca 3D) a trybem IMMERSIVE (nieograniczony widok pełnoekranowy).

Łączenie z sygnałami kontenera przestrzennego

Sprawdź OpenXRSpatialContainerExtension.is_enabled(), aby upewnić się, że rozszerzenie Spatial Container jest obsługiwane i aktywne na bieżącym urządzeniu, i połącz się z sygnałami granic i stanu kontenera w _ready().

OpenXRSpatialContainerExtension emituje te sygnały stanu dotyczące kontenera przestrzennego:

• spatial_container_visibility_changed: emitowane z (spatial_container, is_visible), gdy kontener jest wyświetlany (true) lub ukryty (false). Wstrzymaj animacje, dźwięk lub aktualizacje symulacji, gdy is_visible ma wartość false.
• spatial_container_interactability_changed: emitowane z (spatial_container, is_interactive), gdy kontener uzyskuje (true) lub traci (false) fokus danych wejściowych użytkownika. Włącz lub wyłącz interaktywne wyróżnienia i obsługę danych wejściowych, gdy zmienia się zaznaczenie.
• spatial_container_bounds_mode_changed: emitowane z (spatial_container, bounds_mode), gdy kontener przełącza się między OpenXRSpatialContainerState.BOUNDED a OpenXRSpatialContainerState.IMMERSIVE. Przełączaj elementy wizualne środowiska (takie jak skyboxy lub tryb passthrough) i elementy sterujące interfejsu dla konkretnego trybu.

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

Skaluj treści 3D do granic kontenera

W trybie BOUNDED przeskaluj treści 3D jednolicie według najmniejszego wymiaru bounds, aby zachować format obrazu i zawsze dopasować je do najmniejszego boku kontenera. Podczas przechodzenia do trybu IMMERSIVE przywróć scenę do skali 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

Przełączanie się między trybem ograniczonym a trybem imersji

Wywołaj request_main_spatial_container_bounds_mode za pomocą OpenXRSpatialContainerState.BOUNDED lub OpenXRSpatialContainerState.IMMERSIVE, aby przełączać się między ograniczonym widokiem 3D a pełnoekranowym widokiem immersyjnym:

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

Zobacz też

• Tworzenie za pomocą kontenerów przestrzennych
• Informacje o uprawnieniach XR
• Dodawanie obsługi Androida XR do istniejącego projektu Godot XR

OpenXR™ i logo OpenXR są znakami towarowymi należącymi do firmy The Khronos Group Inc. i są zarejestrowane jako znaki towarowe w Chinach, Japonii, Unii Europejskiej i Wielkiej Brytanii.