Der Android Dev Summit ist zurück – mit einem speziellen Track für Android XR. Seht euch die Videos an, probiert die Funktionen aus und gebt uns Feedback.

Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Räumliche Container in Godot verwenden

XR‑Geräte, für die der Leitfaden gilt

Dieser Leitfaden hilft Ihnen dabei, Erlebnisse für die folgenden Arten von XR-Geräten zu entwickeln.

Informationen zu XR-Gerätetypen →

XR-Headsets

Kabelgebundene XR-Datenbrille

Informationen zu XR-Gerätetypen →

Mit Spatial Containers kann Ihre App 3D-OpenXR-Inhalte in einem vom System verwalteten 3D-Volumenbegrenzungsrahmen im Full Space-Modus rendern oder zur Laufzeit in eine unbegrenzte Vollbildansicht wechseln.

Folgen Sie dieser Anleitung, um räumliche Container in Ihrem Projekt zu konfigurieren und zu verwenden.

Mehrere räumliche Container, die im Full Space-Modus unter Android XR ausgeführt werden. — **Abbildung 1.** Räumliche Container im Modus „Gesamter Bereich“, einschließlich eines am Boden fixierten 3D-Geländecontainers und eines 3D-Modells, das mit einer 2D-Benutzeroberfläche kombiniert ist.

Funktionsweise von räumlichen Containern

Wenn Sie Spatial Container in Ihren Projekteinstellungen aktivieren, geschieht Folgendes:

Die gesamte aktive 3D-Szene wird in einem einzigen primären räumlichen Container platziert, der sich am Ursprung der Szene (0, 0, 0) befindet. Sie müssen einzelne Node3D-Knoten nicht taggen oder zuweisen, um sie im Container zu platzieren.
Ihre App wird im verwalteten Full Space-Modus gestartet. Dabei werden der Bounds Mode (Bounded oder Immersive) und die anfänglichen Bounds-Dimensionen verwendet, die in Ihren Projekteinstellungen konfiguriert sind. Im eingeschränkten Modus werden alle 3D-Geometrien in Ihrer Szene, die über die Abmessungen des Begrenzungsrahmens hinausgehen, automatisch abgeschnitten.
Standardmäßig bietet das Android XR-System Fenstersteuerelemente, mit denen der Nutzer den begrenzten Container im 3D-Raum greifen, verschieben und neu positionieren oder minimieren und schließen kann. Zur Laufzeit kann Ihre App die Größe des Containers ändern, zwischen dem begrenzten Modus (OpenXRSpatialContainerState.BOUNDED) und dem immersiven Vollbildmodus (OpenXRSpatialContainerState.IMMERSIVE) wechseln und mit dem Singleton OpenXRSpatialContainerExtension auf Änderungen der Grenzen und des Status reagieren.

Vorbereitung

Prüfe vorab, ob deine Entwicklungsumgebung und dein Zielgerät die folgenden Anforderungen erfüllen:

Godot-Version: Godot 4.8-dev oder höher.
Projekteinrichtung: Führen Sie alle Schritte im Leitfaden Godot Engine-Projekt einrichten aus.
Godot OpenXR Vendors-Plug-in: Installieren Sie Version 5.2 oder höher des Godot OpenXR Vendors-Plug-ins, um Unterstützung für Android XR-spezifische Erweiterungen zu aktivieren.
Zielgerät: Ein Android XR-Gerät, das Spatial API Level 4 oder höher unterstützt. Rufe zur Laufzeit OpenXRSpatialContainerExtension.is_enabled() auf, um zu prüfen, ob die Erweiterung auf dem Gerät verfügbar ist.

Räumliche Container in den Projekteinstellungen aktivieren

Konfigurieren Sie Ihre Projekteinstellungen, um OpenXR, räumliche Container, automatische Laufzeitberechtigungen und Alpha-Blended-Passthrough zu aktivieren:

Öffnen Sie Project > Project Settings (Projekt > Projekteinstellungen).
Aktivieren Sie die Option Erweiterte Einstellungen rechts oben im Fenster Projekteinstellungen.
Gehen Sie zu Allgemein > XR > Shader und wählen Sie Aktiviert aus.
Gehen Sie zu General > XR > OpenXR und konfigurieren Sie die folgenden Einstellungen:
- Wählen Sie Aktiviert aus, um OpenXR für das Projekt zu aktivieren.
- Setzen Sie Environment Blend Mode (Umgebungsmischmodus) auf Alpha Blend (Alphablending).
Gehen Sie ebenfalls unter OpenXR zum Bereich Erweiterungen und konfigurieren Sie die folgenden Einstellungen:
- Wählen Sie Laufzeitberechtigungen automatisch anfordern aus, damit Ihre App den Nutzer beim Start automatisch nach allen XR-Berechtigungen fragt, die in Ihrem Android-Manifest deklariert sind.
- Wählen Sie im Unterabschnitt Spatial Container die Option Aktiviert aus.
- Setzen Sie Bounds Mode auf Bounded, um die App in einem 3D-Begrenzungsrahmen zu starten, oder auf Immersive, um sie im immersiven Vollbildmodus zu starten.
- Legen Sie für Bounds die anfänglichen Dimensionen für Breite, Höhe und Tiefe in Metern fest, z. B. Vector3(1.0, 1.0, 1.0).
Gehen Sie zu Allgemein > Rendering > Darstellungsbereich und wählen Sie Transparenter Hintergrund aus.

Android-Export, Berechtigungen und Full Space Mode konfigurieren

Konfiguriere als Nächstes die Android-Exportvoreinstellung, die Berechtigungen und den Startmodus für Aktivitäten, damit deine App im Full Space-Modus mit aktivierten räumlichen Containern ausgeführt wird.

Android-Exportvoreinstellung konfigurieren

Gehen Sie zu Project > Export… und wählen Sie die Exportvoreinstellung Android aus.
Wählen Sie unter Gradle Build die Option Use Gradle Build aus und legen Sie für Min SDK den Wert 34 oder höher fest.
Legen Sie unter XR-Funktionen den XR-Modus auf OpenXR fest und wählen Sie AndroidXR-Plug-in aktivieren aus.
Wählen Sie unter Android XR-Funktionen die Option Experimentelle Funktionen verwenden aus.

Hinweis: Das Godot OpenXR Vendors-Plug-in prüft, ob Experimentelle Funktionen verwenden aktiviert ist, wenn Spatial Container aktiviert ist, und fügt <meta-data android:name="com.android.extensions.xr.uses_experimental_openxr_feature" android:value="true" /> und <uses-permission android:name="android.permission.HEAD_TRACKING" /> in die AndroidManifest.xml Ihrer App ein.

Berechtigungen für die Szenenerkennung für die Bodenfixierung hinzufügen

Für das Erstellen und Rendern eines einfachen räumlichen Containers sind keine gefährlichen Laufzeitberechtigungen erforderlich. android.permission.HEAD_TRACKING wird dem Manifest automatisch hinzugefügt, wenn Experimentelle Funktionen verwenden aktiviert ist. Wenn Ihre App jedoch Funktionen zur Szenenerkennung verwendet, z. B. das Sperren und Verankern eines räumlichen Containers am physischen Boden, muss sie die Berechtigung android.permission.SCENE_UNDERSTANDING_COARSE zur Laufzeit deklarieren und anfordern.

Weitere Informationen zu Android XR-Berechtigungen finden Sie unter Berechtigungen für XR. Wenn Ihre App die Bodenfixierung oder die Szenenerkennung verwendet, deklarieren und fordern Sie android.permission.SCENE_UNDERSTANDING_COARSE an:

Unter Projekt > Exportieren… > Android, rufen Sie Berechtigungen > Benutzerdefinierte Berechtigungen auf und fügen Sie android.permission.SCENE_UNDERSTANDING_COARSE hinzu.

Hinweis: Wenn in Ihrem Projekt bereits Spatial Entities oder Light Estimation unter Projekteinstellungen > Allgemein > XR > OpenXR > Erweiterungen aktiviert ist, fügt das Godot OpenXR Vendors-Plug-in automatisch android.permission.SCENE_UNDERSTANDING_COARSE in das Manifest ein.
Wenn Sie unter Projekteinstellungen > Allgemein > XR > OpenXR > Erweiterungen die Option Laufzeitberechtigungen automatisch anfordern auswählen, fordert Ihre App die Berechtigung automatisch an, wenn OpenXR gestartet wird. Wenn Sie die Berechtigung stattdessen manuell in GDScript anfordern müssen, rufen Sie OS.request_permission() auf:
```
if not OS.get_granted_permissions().has("android.permission.SCENE_UNDERSTANDING_COARSE"):
    OS.request_permission("android.permission.SCENE_UNDERSTANDING_COARSE")
```

Full Space-Modus konfigurieren

Spatial Container unter Android XR unterstützen nur den Full Space-Modus (XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED). Achten Sie darauf, dass Ihre Android-Aktivität XR_ACTIVITY_START_MODE_FULL_SPACE_MANAGED in Ihrer benutzerdefinierten Build-Vorlage (android/build/AndroidManifest.xml, installiert über Projekt > Android-Build-Vorlage installieren…) deklariert:

<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>

Mit räumlichen Containern in GDScript arbeiten

Das Singleton OpenXRSpatialContainerExtension und die Klasse OpenXRSpatialContainerState stellen die Erweiterungen XR_EXT_spatial_container und XR_EXT_spatial_container_self_rendering für GDScript bereit. Verwenden Sie zur Laufzeit OpenXRSpatialContainerExtension, um den Status und die Grenzen des Haupt-Spatial-Containers zu prüfen, auf Containersignale zu warten und Übergänge zwischen dem BOUNDED-Modus (einem 3D-Begrenzungsrahmen) und dem IMMERSIVE-Modus (einer unbegrenzten Vollbildansicht) anzufordern.

Verbindung zu Spatial Container-Signalen herstellen

Prüfen Sie OpenXRSpatialContainerExtension.is_enabled(), um festzustellen, ob die Spatial Container-Erweiterung auf dem aktuellen Gerät unterstützt wird und aktiv ist, und stellen Sie eine Verbindung zu den Containergrenzen und Zustandssignalen in _ready() her.

OpenXRSpatialContainerExtension gibt die folgenden Statussignale für den räumlichen Container aus:

spatial_container_visibility_changed: Wird mit (spatial_container, is_visible) ausgegeben, wenn der Container angezeigt (true) oder ausgeblendet (false) wird. Pausieren Sie Animationen, Audio oder Simulationsaktualisierungen, wenn is_visible den Wert false hat.
spatial_container_interactability_changed: Wird mit (spatial_container, is_interactive) ausgegeben, wenn der Container den Fokus für Nutzereingaben erhält (true) oder verliert (false). Aktivieren oder deaktivieren Sie interaktive Hervorhebungen und die Eingabeverarbeitung, wenn sich der Fokus ändert.
spatial_container_bounds_mode_changed: Wird mit (spatial_container, bounds_mode) ausgegeben, wenn der Container zwischen OpenXRSpatialContainerState.BOUNDED und OpenXRSpatialContainerState.IMMERSIVE wechselt. Umgebungsvisualisierungen (z. B. Skyboxen oder Passthrough) und modusspezifische UI-Steuerelemente ein- oder ausschalten.

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

3D-Inhalte an Containergrenzen anpassen

Skaliere deine 3D-Inhalte im Modus BOUNDED einheitlich nach der kleinsten Dimension von bounds, damit das Seitenverhältnis beibehalten wird und die Inhalte immer in die kleinste Seite des Containers passen. Wenn Sie in den IMMERSIVE-Modus wechseln, stellen Sie den Maßstab 1:1 für die Szene wieder her:

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

Zwischen dem begrenzten und dem immersiven Modus wechseln

Rufen Sie request_main_spatial_container_bounds_mode mit OpenXRSpatialContainerState.BOUNDED oder OpenXRSpatialContainerState.IMMERSIVE auf, um zwischen einem begrenzten 3D-Volumen und einer immersiven Vollbildansicht zu wechseln:

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

Weitere Informationen

OpenXR™ und das OpenXR-Logo sind Marken von The Khronos Group Inc. und in China, der Europäischen Union, Japan und dem Vereinigten Königreich als Marken eingetragen.