Einem vorhandenen Godot XR-Projekt Unterstützung für Android XR hinzufügen

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‑Datenbrillen
Informationen zu XR‑Gerätetypen

Wenn Sie bereits ein XR‑Projekt in Godot haben, können Sie Unterstützung für Android XR hinzufügen, ohne ein neues, separates Projekt zu starten. Einige Schritte sind für alle Projekte erforderlich, andere sind optional und hängen von den XR‑Funktionen ab, die in Ihrem Projekt verwendet werden. In den Schritten haben wir Links zu mehreren Open-Source-Godot-XR‑Projekten eingefügt, die Unterstützung für Android XR hinzugefügt haben, sowie relevante Pull-Requests, die die Änderungen zeigen, die zum Aktivieren bestimmter Funktionen erforderlich sind.

Erforderliche Schritte für alle Projekte

Führen Sie die Schritte in den folgenden Themen aus, unabhängig davon, welche Arten von XR‑Funktionen Ihr Projekt unterstützt. Sehen Sie sich anschließend die Funktionen in der Liste der optionalen Schritte an, um festzustellen, ob für Ihr Projekt zusätzliche Arbeit erforderlich ist.

Godot und das Godot OpenXR Vendors-Plug-in aktualisieren

Führen Sie die folgenden Schritte aus, um Ihr Projekt auf die neuesten erforderlichen Versionen zu aktualisieren und die Einstellungen Ihres Projekts für Android XR zu konfigurieren:

  1. Aktualisieren Sie Ihre Godot-Version auf 4.6.2 oder höher. In der Dokumentation zu r Migration zu einer neuen Version finden Sie weitere Informationen, falls Sie zusätzliche Hilfe für Ihr Projekt benötigen.

  2. Laden Sie das Godot OpenXR Vendors-Plug-in Version 5.1 oder höher aus dem Asset Store, der Asset Library oder dem Repository auf GitHub herunter.

  3. Konfigurieren Sie die Einstellungen Ihres Projekts für Android XR:

    1. Fügen Sie eine Exportvoreinstellung für Android XR hinzu.
    2. Aktivieren Sie Gradle-Build verwenden.

    Aktivieren Sie die

    1. Wählen Sie im Bereich XR‑Funktionen für XR‑Modus die Option OpenXR aus, und wählen Sie AndroidXR-Plug-in aktivieren aus.

    Konfigurieren Sie die Optionen im

Unterstützung für Hand-Tracking hinzufügen

Controller sind zwar möglicherweise verfügbar, die primäre Eingabemethode auf Android XR‑Headsets und XR‑Datenbrillen ist jedoch das Hand-Tracking. Wenn möglich, sollten Sie Ihrem Godot-Projekt Unterstützung für Hand-Tracking hinzufügen.

Unterstützung für Hand-Tracking hinzufügen: Projekteinstellungen konfigurieren

Führen Sie zuerst die folgenden Schritte aus, um die Projekteinstellungen so zu konfigurieren, dass Hand-Tracking und die zugehörigen OpenXR-Erweiterungen aktiviert werden.

  1. Öffnen Sie die Einstellungen Ihres Projekts und gehen Sie zu Allgemein > XR > OpenXR.

  2. Wählen Sie im Bereich Erweiterungen die Optionen Hand-Tracking und Hand-Interaktionsprofil aus.

    Konfigurieren Sie die Optionen im

  3. Suchen Sie im Bereich Erweiterungen den Unterbereich Meta und wählen Sie Handtracking-Mesh und Handtracking-Ziel aus.

    Konfigurieren Sie die Optionen im

Unterstützung für Hand-Tracking hinzufügen: Controllerknoten hinzufügen und konfigurieren

Anstatt die vorhandenen XRController3D-Knoten für das Hand-Tracking dynamisch zu ändern, fügen Sie Controllerknoten für das Tracking und die Anzeige der Handmodelle sowie für die Verarbeitung von Eingaben aus der Erweiterung „Hand-Tracking-Ziel“ hinzu:

  1. Fügen Sie Ihrem XROrigin3D-Knoten drei weitere XRController3D-Knoten hinzu.

    1. Nennen Sie einen „HandTrackingLeft“ und legen Sie die Tracker-Property auf /user/hand_tracker/left fest.
    2. Nennen Sie einen weiteren „HandTrackingRight“ und legen Sie die Tracker-Property auf /user/hand_tracker/right fest.
    3. Nennen Sie den letzten „HandTrackingAimLeft“ und legen Sie die Tracker-Property auf /user/fbhandaim/left fest.

    Wenn die ursprünglichen XRController3D Knoten Ihres Projekts „XRController3D_left“ und „XRController3D_right“ hießen, sieht Ihre Szene ungefähr so aus:

    So könnte Ihre Szene aussehen, nachdem Sie die Controller-Knoten hinzugefügt haben.

  2. Verbinden Sie das Signal tracking_changed für HandTrackingLeft und HandTrackingRight mit einzelnen Funktionen, die die Sichtbarkeit der entsprechenden Controller-Tracker aktualisieren (XRController3D_left und XRController3D_right im vorherigen Beispiel).

    Die mit dem Signal für HandTrackingLeft verbundene Funktion könnte beispielsweise so aussehen:

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

  3. Aktivieren Sie die Property Bei Tracking anzeigen für die Controllerknoten für das Hand-Tracking.

    Jetzt kann Ihr Projekt je nachdem, ob der Nutzer Hand-Tracking oder Controller verwendet, visuell zwischen Controller- und Hand-Tracking-Modellen wechseln.

  4. Fügen Sie einige OpenXRFbHandTrackingMesh-Knoten als untergeordnete Knoten zu den Controllerknoten für das Hand-Tracking hinzu.

  5. Fügen Sie XRHandModifier3D-Knoten als untergeordnete Knoten zu diesen OpenXRFbHandTrackingMesh-Knoten hinzu und legen Sie die richtige Property Hand-Tracker fest, um Echtzeit-Hand-Tracking-Daten auf die Modelle anzuwenden.

    So könnte Ihre Szene aussehen, nachdem Sie die untergeordneten Knoten zu den Controllerknoten hinzugefügt haben.

Unterstützung für Hand-Tracking hinzufügen: Hand-Interaktionsprofil auf der OpenXR-Aktionszuordnung einrichten

Als Nächstes richten Sie das Profil Hand-Interaktion auf der OpenXR-Aktions zuordnung ein:

  1. Öffnen Sie das Menü OpenXR-Aktionszuordnung unten im Editor.
  2. Löschen Sie das Profil Einfacher Controller , um Kompatibilitätsprobleme mit Galaxy XR‑Controllern zu vermeiden.
  3. Klicken Sie auf Profil hinzufügen, wählen Sie Hand-Interaktion aus und klicken Sie dann auf OK.

  4. Ordnen Sie dieses Profil beliebig vielen Aktionssätzen zu.

Je nach den Anforderungen Ihrer App müssen Sie möglicherweise auch anpassen, wie Ihre App Nutzereingaben mit Hand-Tracking verarbeitet.

Unterstützung für Hand-Tracking hinzufügen: Menügeste für Android XR einrichten

Schließlich können Sie eine Menügeste für Android XR implementieren. Dabei wird ein Symbol angezeigt, wenn sich die linke Hand des Spielers in der richtigen Position befindet, um die Menügeste auszuführen. Außerdem wird das Menü angezeigt oder ausgeblendet, wenn der Nutzer die Geste ausführt. Dazu verwenden Sie den Knoten HandTrackingAimLeft , den Sie zuvor hinzugefügt haben , um dies zu verarbeiten.

  1. Fügen Sie dem linken Handtracking-Knoten ein Billboard-Quad hinzu, auf dem ein von Ihnen ausgewähltes Symbol angezeigt wird (siehe den Knoten MenuIcon in der folgenden Abbildung der zuvor hinzugefügten Controllerknoten).

    So könnte Ihre Szene aussehen, nachdem Sie die untergeordneten Knoten zu den Controllerknoten hinzugefügt haben.

  2. Verbinden Sie die Signale button_pressed und button_released für HandTrackingAimLeft mit Funktionen wie dieser:

    @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

Optionale Schritte für bestimmte Funktionen

Nachdem Sie die erforderlichen Schritte für Ihr Projekt ausgeführt haben, entscheiden Sie, ob für bestimmte Funktionen zusätzliche Arbeit erforderlich ist. Das hängt von den Anforderungen und Möglichkeiten Ihrer App ab. Weitere Informationen zu den einzelnen optionalen Funktionen finden Sie in den folgenden Abschnitten.

Pinch-Gesten als Tastendrücke registrieren

In Android XR werden Pinch-Gesten für viele grundlegende Systemaktionen verwendet, z. B. zum Auswählen von Elementen, Scrollen, Verschieben oder Ändern der Größe von Fenstern und zum Verschieben von UI ‑Elementen oder Objekten im 2D- und 3D‑Raum. Um diese Muster zu berücksichtigen und eine einheitliche Nutzererfahrung zu fördern, sollte Ihre App Pinch-Gesten ähnlich wie Tastendrücke auf einem Controller registrieren, wenn Hand-Tracking verwendet wird.

Verwenden Sie dazu die Gleitkommawerte, die vom erstellten Hand-Interaktionsprofil bereitgestellt werden, um eine virtuelle Aktion zu erstellen:

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)

Wichtige Punkte zum Code

  • Überprüft, ob der float Wert größer oder kleiner als bestimmte Grenzwerte ist in den XRController3D input_float_changed Signalen.
  • Erstellt eine virtuelle Aktion namens pinch_pressed.

XR‑Tools-Funktionen zusammen mit Hand-Tracking verwenden

Viele Godot-XR‑Projekte verwenden Godot XR Tools, darunter einige der Open-Source-Projekte, auf die auf dieser Seite verlinkt wird. Damit einige XR‑Tools-Funktionen funktionieren, z. B. FunctionPointer für Menüinteraktionen, benötigen Sie zusätzlichen Code, um die gesuchte Aktion zu ändern, wenn der Nutzer zu Hand-Tracking wechselt.

Wenn Sie beispielsweise FunctionPointer für Menüinteraktionen verwenden, aktualisieren Sie die active_button_action Property auf die Hand-Tracking-Aktion, basierend auf dem tracking_changed Signal der XRController3D Knoten für das Hand-Tracking. Diese Knoten waren in den vorherigen Hand Tracking-Einrichtungsschritten HandTrackingLeft und HandTrackingRight.

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

Wichtige Punkte zum Code

Hand-Tracking zusammen mit künstlicher Fortbewegung verwenden

Wenn Ihr Projekt künstliche Fortbewegung verwendet, ist Hand-Tracking weiterhin möglich. Sie können beispielsweise ein Bewegungssystem erstellen, mit dem Spieler Pfade zeichnen können, um sich mit einer Geste fortzubewegen. Oder Sie können Spielern erlauben, ihre Hände auf und ab zu bewegen, um zu beschleunigen, mit zusätzlichen Gesten zum Springen, Klettern und Gleiten.

Im Museum of All Things wird künstliche Fortbewegung mit den Thumbsticks auf den Controllern verwendet. Die Fortbewegung per Hand-Tracking wurde implementiert, indem „virtuelle Thumbsticks“ hinzugefügt wurden, die der Spieler durch Pinch-Gesten in der Luft auslöst und seine Hand in die Richtung bewegt, in die sich der Thumbstick bewegen soll.

Hier sind einige der wichtigsten Erkenntnisse aus der Pull-Anfrage, mit der diese Unterstützung implementiert wurde:

  • Eine XRVirtualThumbstick-Szene wird instanziiert, wenn eine Pinch-Geste erkannt wird.
  • Während die Pinch-Geste gehalten wird, werden die relative Entfernung und Richtung vom ursprünglichen Pinch-Ort in einen Vector2 umgewandelt und virtuell der normalen Thumbstick-Eingabe zugeordnet.
  • Der Spieler erhält auch visuelles Feedback zu dieser Eingabe in Form von zwei Billboard-Quad-Meshes, die die Position des Thumbsticks darstellen.

Sie können einen ähnlichen Ansatz verwenden, um Ihren vorhandenen Code für die Thumbstick-gesteuerte Fortbewegung mit minimalen Änderungen zum Laufen zu bringen. Für Ihr Projekt ist jedoch möglicherweise eine benutzerdefinierte Lösung für die Fortbewegung per Hand-Tracking erforderlich.

Passthrough-Unterstützung hinzufügen

Sie können Ihrer App Passthrough-Unterstützung hinzufügen, damit Ihre Nutzer ihre reale Umgebung sehen können.

Nehmen Sie dazu die folgenden Codeänderungen vor:

  • Legen Sie für environment_blend_mode des OpenXR XRInterface den Wert XR_ENV_BLEND_MODE_ALPHA_BLEND fest.
  • Legen Sie für background_mode des Knotens WorldEnvironment den Wert BG_COLOR fest.
  • Legen Sie für background_color des Knotens WorldEnvironment eine beliebige Farbe fest, die vollständig transparent ist.
  • Legen Sie für die Property Viewport transparent_bg den Wert true fest.

Erweiterung für die Lichterkennung verwenden

Wenn Sie Passthrough aktivieren, sollten Sie die OpenXR-Erweiterung für die Lichterkennung von Android XR verwenden. Mit dieser Erweiterung werden die Properties von WorldEnvironment und DirectionalLight3D angepasst, um die Beleuchtung der realen Umgebung eines Nutzers besser zu simulieren. So fügen sich virtuelle Objekte besser in die realen Lichtverhältnisse ein. Sie können diese Erweiterung in den Einstellungen Ihres Projekts aktivieren.

  1. Öffnen Sie die Einstellungen Ihres Projekts und gehen Sie zu Allgemein > XR > OpenXR.

  2. Wählen Sie im Bereich Androidxr die Option Lichterkennung aus.

    Konfigurieren Sie die Optionen im

  3. Fügen Sie dem Szenenbaum einen OpenXRAndroidLightEstimation-Knoten hinzu und verbinden Sie ihn mit WorldEnvironment und DirectionalLight3D Ihrer Szene.

    Optionen für

Beispiel: Passthrough und Lichterkennung aktivieren oder deaktivieren

Mit dem folgenden Code können Sie Passthrough und Lichterkennung aktivieren oder deaktivieren:

@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
Wichtige Punkte zum Code
  • Wenn Sie die Lichterkennung deaktivieren, muss die ursprüngliche Richtung von DirectionalLight3D manuell wiederhergestellt werden.
  • Ein vollständiges Beispiel für ein Projekt, das Passthrough und Lichterkennung verwendet, finden Sie unter Expedition to Blobotopia auf GitLab.