Wie man EasyAR-Funktionen auf Apple Vision Pro verwendet

Dieser Leitfaden fuehrt Sie durch die Unity- und Xcode-Projektkonfiguration, um fuer Apple-Vision-Pro-Anwendungen alle EasyAR-Kernfaehigkeiten, einschliesslich Mega-Cloud-Localization, freizuschalten.

Vor dem Start

• Lernen Sie, wie Sie Headset-Beispiele verwenden.
• Stellen Sie sicher, dass Ihre Entwicklungsumgebung die folgenden Anforderungen erfuellt:
  • visionOS 2.0 oder neuer
  • Xcode 16.0 oder neuer fuer die jeweilige visionOS-Version, mit installiertem visionOS-Simulator
  • Empfohlene Unity-Version: LTS 6000.0.23 oder neuer

Beantragen Sie eine Enterprise-API-Lizenz bei Apple Inc.

Da das Abrufen von Kamerabildern und -parametern auf Apple Vision Pro eine Entitlement-basierte Enterprise-API erfordert, muessen Sie bei Apple Inc. eine Lizenzdatei mit diesem Entitlement beantragen. Hinweise zum Beantragen und Verwenden dieser Lizenz finden Sie in Building spatial experiences for business apps with enterprise APIs for visionOS.

Wichtig

Die Bundle ID im von Apple erhaltenen Entitlement muss genau mit der beim Erstellen des EasyAR Sense License Key eingegebenen Bundle ID uebereinstimmen.

Wie man den visionOS App Mode auswaehlt

Eine App auf visionOS kann ARKit-Daten nur in der Immersive Space abrufen. Von Unity erzeugte Apps in der Immersive Space muessen je nach Rendering-Pfad und APIs zwischen RealityKit with PolySpatial und Metal Rendering with Compositor Services waehlen.

Zur Definition der Immersive Space lesen Sie Apples offizielle Dokumentation.

Eine ausfuehrliche Einfuehrung in den Unity-App-Modus finden Sie in der Unity-PolySpatial-Dokumentation unter visionOS Platform Overview.

Tipp

Empfehlung zur App-Mode-Auswahl

• Erste Empfehlung: RealityKit with PolySpatial

  Wenn Sie zum ersten Mal mit visionOS arbeiten, sollten Sie diesen Modus bevorzugen. Der Vorteil liegt in der tiefen Integration in die systemweiten Rendering-Funktionen von visionOS, mit hoher Stabilitaet und guter Renderqualitaet. Dieser Modus unterstuetzt keine eigenen Code-Shader (HLSL/ShaderLab). Es muss Shader Graph verwendet werden, und nur Funktionen, die den PolySpatial-Kompatibilitaetspruefungen standhalten, werden unterstuetzt (sie werden nach MaterialX konvertiert).

  Die integrierten Shader Standard (Built-in) und Lit (URP) wurden offiziell vorab angepasst und koennen direkt verwendet werden.

• Erweiterte / spezielle Anforderungen: Metal Rendering with Compositor Services

  Geeignet fuer Projekte mit vielen bestehenden 3D-Assets oder Projekten, die eigene Shader benoetigen. Da Unity in diesem Modus die gesamte Rendering-Logik uebernimmt und den RealityKit-Pfad des Systems umgeht, ist die Renderqualitaet in der Regel schlechter als bei RealityKit, und es koennen unerwartete Rendering-Probleme auftreten.

Empfehlung fuer die EasyAR-Einbindung:

Wenn Sie EasyAR einbinden, beginnen Sie immer mit RealityKit with PolySpatial, um den grundlegenden Ablauf sauber zu pruefen. So lassen sich Variablen besser isolieren und Schwierigkeiten bei der Fehlersuche durch vermischte Metal-Anpassungsprobleme und AR-Probleme vermeiden.

Konfiguration im Unity-Projekt

Im Unity-Projekt sind die folgenden Konfigurationen erforderlich:

Erforderliche Pakete fuer das Unity-Projekt importieren

Unity 6 (empfohlen):

• RealityKit/Hybrid
• Metal

• com.unity.xr.visionos (2.0.4+)
• com.unity.polyspatial (2.0.4+)
• com.unity.polyspatial.visionos (2.0.4+)

Wichtig

Die Versionsnummern aller Pakete muessen exakt gleich sein.

Verwenden Sie moeglichst Unity 6, da einige fruehere Unity-2023.x-Versionen visionOS noch nicht unterstuetzen.

Unity 2022.3:

• RealityKit/Hybrid
• Metal

• com.unity.xr.visionos (1.2.3)
• com.unity.polyspatial (1.2.3)
• com.unity.polyspatial.visionos (1.2.3)

Wichtig

Die Versionsnummern aller Pakete muessen exakt gleich sein.

Versionen 1.3.x werden nicht unterstuetzt; bleiben Sie unbedingt bei 1.2.3.

Build-Plattform waehlen

Wechseln Sie in der Menueleiste ueber File > Build Profiles die Plattform auf visionOS.

Input System konfigurieren

Stellen Sie sicher, dass Sie das neuere Input System Package verwenden:

Waehlen Sie Edit > Project Settings > Player und setzen Sie Active Input Handling auf Input System Package(New).

Unity fordert moeglicherweise einen Neustart des Projekts an; klicken Sie auf Apply, damit die Aenderungen wirksam werden.

XR Plug-in Management konfigurieren

Waehlen Sie Edit > Project Settings > XR Plug-in Management und aktivieren Sie im visionOS-Tab unter Plug-in Providers Apple visionOS.

Apple visionOS Plugin konfigurieren

Waehlen Sie Edit > Project Settings > XR Plug-in Management > Apple visionOS.

Waehlen Sie den passenden App Mode basierend auf der vorigen Beschreibung.

Anmerkung

Der Modus Windowed kann keine AR-Funktionen verwenden, da er nicht in der Immersive Space laeuft.

Der Modus Hybrid erfordert das manuelle Umschalten zwischen Metal und RealityKit. Wegen der Komplexitaet wird er nicht empfohlen; Details finden Sie in der offiziellen Unity-Beschreibung dieses Modus.

Nehmen Sie anschliessend auf derselben Seite folgende Aenderungen vor:

• Tragen Sie im Feld World Sensing Usage Description eine Beschreibung ein.
• Setzen Sie Metal Immersion Style auf Mixed.
• Setzen Sie Reality Kit Immersion Style auf Mixed.
• Aktivieren Sie IL2CPP Large Exe Workaround.

[Nur fuer RealityKit-Modus] TextMesh Pro Essentials importieren

Waehlen Sie Edit > Project Settings > TextMesh Pro > Import TMP Essentials.

Anmerkung

Derzeit unterstuetzt der Modus RealityKit with PolySpatial nur TextMesh Pro-Text. Ohne den Import kann Text nicht gerendert werden.

[Nur fuer RealityKit-Modus] PolySpatial-Einstellungen

Waehlen Sie Edit > Project Settings > PolySpatial und nehmen Sie auf dieser Seite folgende Aenderungen vor:

• Setzen Sie Default Volume Camera Window Config auf Default Unbounded Configuration.
• Aktivieren Sie Auto-Create Volume Camera.

Wenn Sie einen anderen Wert fuer Default Volume Camera Window Config angeben muessen, stellen Sie sicher, dass der Mode Unbounded ist.

Wenn in der Szene eine Volume Camera vorhanden ist, loeschen Sie sie.

Warnung

• Volume Camera-Objekte mit World Transform ungleich identity werden nicht unterstuetzt.
• Wenn Sie aus besonderen Gruenden eine einzige benutzerdefinierte Volume Camera hinzufuegen muessen, stellen Sie unbedingt sicher:
  • Setzen Sie World Transform auf identity.
  • Stellen Sie sicher, dass der Mode der Volume Camera Window Configuration auf Unbounded gesetzt ist.
  • Verwenden Sie sie erst dann, wenn Sie die Bedeutung und den Zweck in der offiziellen Unity-Dokumentation vollstaendig verstanden haben.

[Bei Verwendung von Mega] Location Usage Description hinzufuegen

Vorsicht

Wenn in der EasyAR-Konfiguration die Berechtigung Location aktiviert ist (bei Verwendung von Mega), muss eine Berechtigungsbeschreibung hinzugefuegt werden; andernfalls schlaegt der Build fehl.

Da das Feld Location Usage Description im Unity-Tab Project Settings > Player > visionOS derzeit nicht angezeigt wird, gehen Sie wie folgt vor:

1. Plattform-Tab wechseln: Wechseln Sie den Tab voruebergehend zu iOS.
2. Beschreibung eintragen: Tragen Sie die notwendige Beschreibung fuer die Berechtigung im Feld Location Usage Description ein.
3. Zurueck zu visionOS wechseln: Wechseln Sie den Tab wieder zu visionOS; die gerade eingetragene Konfiguration bleibt erhalten und wird wirksam.

Konfiguration im Xcode-Projekt

Im durch Unity erzeugten Xcode-Projekt sind die folgenden Konfigurationen erforderlich:

Camera-Data-Entitlement konfigurieren

• Kopieren Sie die erhaltene Datei Enterprise.license in das Verzeichnis des Xcode-Projekts.

  

• Ziehen Sie Enterprise.license aus dem Xcode-Projektverzeichnis in das Xcode-Projekt.

  

info.plist aendern, damit Dateien gespeichert und weitergegeben werden koennen

Wenn Sie im App-Projekt EIF aufnehmen und diese ueber die Files-App von visionOS auf Computer oder andere Geraete uebertragen moechten, fuegen Sie in Info.plist die folgenden Felder hinzu und passen Sie sie an:

• Fuegen Sie LSSupportsOpeningDocumentsInPlace hinzu und setzen Sie den Wert auf true.
• Fuegen Sie UIFileSharingEnabled hinzu und setzen Sie den Wert auf true.

Tipp

Nach dem Hinzufuegen der Felder kann der in Xcode angezeigte Key vom manuell eingegebenen String abweichen (zum Beispiel wird LSSupportsOpeningDocumentsInPlace als Supports opening documents in place angezeigt; das ist normal).