Table of Contents

如何在 Apple Vision Pro 上使用 EasyAR 能力

本指南將引導您完成 Unity 與 Xcode 的工程配置，爲 Apple Vision Pro 應用解鎖包括 Mega 雲定位在內的全部 EasyAR 核心能力。

開始之前

  • 學習如何使用頭顯樣例
  • 確保開發環境符合以下要求：
    • visionOS 2.0 及以上
    • 對應 visionOS 版本的 Xcode 16.0 及以上並安裝 visionOS simulator
    • 推薦的 Unity 版本 6000.0.23 以上的 LTS 版本

向 Apple Inc. 申請企業級 API 許可

由於在 Apple Vision Pro 上獲取相機畫面及參數是一個需要 entitlement 的 企業級 API，您需要向 Apple Inc. 申請包含該 entitlement 的 license 文件。該 license 的申請和使用方式請參考 Building spatial experiences for business apps with enterprise APIs for visionOS。

重要事項

向蘋果公司申請得到的 entitlement 中的 Bundle ID 應與創建 EasyAR Sense License Key 時填寫的完全一致。

如何選擇 visionOS App Mode

運行在 visionOS 上的 App 僅在 Immersive Space 下能夠獲取 ARKit 數據。而 Unity 編輯器打包的 App 在 Immersive Space 下基於渲染流程及 API 不同需要選擇使用 RealityKit with PolySpatial 或 Metal Rendering with Compositor Services 模式。

關於 Immersive Space 的定義,可以參考蘋果官方文檔。

關於 Unity 的 App Mode 的詳細介紹，可以參考 Unity PolySpatial 文檔中的 visionOS Platform Overview。

提示

App Mode 選擇建議

  • 首選推薦：RealityKit with PolySpatial

    如果您是首次接觸 visionOS，建議優先選擇此模式。其優勢在於能深度集成 visionOS 的系統級渲染特性，穩定性高，渲染效果好。 此模式不支持自定義代碼着色器（HLSL/ShaderLab），必須使用 Shader Graph，且僅支持經 PolySpatial 兼容性檢查後的特性（會被轉換爲 MaterialX）。

    Unity 內置的 Standard (Built-in) 和 Lit (URP) 着色器已由官方預先適配，可直接使用。

  • 進階/特定需求：Metal Rendering with Compositor Services

    適用於有大量現有 3D 資產遷移需求或必須使用自定義着色器的複雜項目。 由於該模式下 Unity 負責全部渲染邏輯，繞過了系統的 RealityKit 管線，渲染效果一般不如 RealityKit 並且可能會遇到不可預見的渲染問題。

EasyAR 接入建議：

在嘗試接入 EasyAR 時，請務必先使用 RealityKit with PolySpatial 模式跑通基礎流程。這樣可以有效隔離變量，避免因 Metal 底層適配問題與 AR 相關問題交織，從而導致難以定位故障成因。

Unity 工程中的配置

Unity 工程中需要進行以下配置：

爲 Unity 工程導入必要的 Package

Unity 6 （推薦）：

  • com.unity.xr.visionos (2.0.4+)
  • com.unity.polyspatial (2.0.4+)
  • com.unity.polyspatial.visionos (2.0.4+)
重要事項

所有 Package 的版本號必須保持嚴格一致。

建議優先使用 Unity 6，部分早期的 Unity 2023.x 版本對 visionOS 尚不支持。

Unity 2022.3：

  • com.unity.xr.visionos (1.2.3)
  • com.unity.polyspatial (1.2.3)
  • com.unity.polyspatial.visionos (1.2.3)
重要事項

所有 Package 版本號必須保持嚴格一致。

不支持 1.3.x 版本，請務必鎖定在 1.2.3。

選擇 Build Platform

點擊菜單欄中的 File > Build Profiles 將 Platform 切換至 visionOS。

切換Build_Platform

配置 Input System

確保使用新版的 Input System Package：

點擊菜單欄中的 Edit > Project Settings > Player，將 Active Input Handling 槽設置爲 Input System Package(New)。

此後 Unity 可能會要求重啓工程，點擊 Apply 使改動生效。

InputSystem改動生效

配置 XR Plug-in Management

點擊菜單欄中的 Edit > Project Settings > XR Plug-in Management，在 visionOS 選項卡中的 Plug-in Providers 勾選 Apple visionOS。

選擇visionOS插件

配置 Apple visionOS 插件

點擊菜單欄中的 Edit > Project Settings > XR Plug-in Management > Apple visionOS。

根據前文介紹選擇合適的 App Mode。

選擇AppMode

附註

Windowed 模式由於不是運行於 Immersive Space，無法使用 AR 能力。

Hybrid 模式指開發者需要手動在 Metal 和 RealityKit 模式間切換，由於使用方式比較複雜，不推薦使用，具體可以參考 Unity 官方對該模式的說明。

接下來在同頁面中進行以下修改：

  • 在 World Sensing Usage Description 槽中添加一段描述。

  • 將 Metal Immersion Style 設置爲 Mixed。

  • 將 Reality Kit Immersion Style 設置爲 Mixed。

  • 勾選 IL2CPP Large Exe Workaround。

修改visionOS插件配置

[僅 RealityKit 模式需要] 導入 TextMesh Pro Essentials

點擊菜單欄中的 Edit > Project Settings > TextMesh Pro > 點擊 Import TMP Essentials

Import TMP Essentials

附註

目前 RealityKit with PolySpatial 模式僅支持 TextMesh Pro 文字，若不導入則無法渲染文字。

[僅 RealityKit 模式需要] PolySpatial 相關設置

點擊菜單欄中的 Edit > Project Settings > PolySpatial，在該頁面中進行以下修改：

  • 設置 Default Volume Camera Window Config 爲 Default Unbounded Configuration。

  • 勾選 Auto-Create Volume Camera

設置 PolySpatial

如果需要另外指定 Default Volume Camera Window Config，必須確保其 Mode 爲 Unbounded。

確認 Mode 是 Unbounded

場景中如果存在 Volume Camera，將其刪除。

刪除場景中的 Volume Camera

警告
  • 不支持 World Transform 數值不是 identity 的 Volume Camera。
  • 若因特殊原因需要在場景中添加一個唯一的自定義 Volume Camera，請務必：
    • 將其 World Transform 設爲 identity。
    • 確保其 Volume Camera Window Configuration 的 Mode 設置爲 Unbounded。
    • 在完全清楚 Unity 官方文檔中其含義和用途的前提下使用。

[使用 Mega 時]添加 Location Usage Description

注意

若在 EasyAR 配置中啓用了 Location 權限（使用 Mega 功能時），必須添加權限描述信息，否則 Build 將失敗。

由於目前 Unity 的 Project Settings > Player > visionOS 選項卡中未顯示 Location Usage Description 字段，請按照以下步驟配置：

  1. 切換平臺標籤：將選項卡暫時切換至 iOS。
  2. 填入描述：在 Location Usage Description 槽位中填入必要的權限用途說明。
  3. 切回 visionOS：將選項卡切回 visionOS，剛纔填寫的配置會自動保留並生效。

Location Description

Xcode 工程中的配置

通過 Unity 打包得到的 Xcode 工程中需要進行以下配置：

配置相機數據 entitlement

  • 將申請得到的 Enterprise.license 文件複製到 Xcode 工程文件目錄。

    Copy to Xcode project folder

  • 將 Xcode 工程文件目錄中的 Enterprise.license 拖入 Xcode 工程中。

    Move into Xcode project

修改 info.plist 使應用能夠保存和投送文件

若需要在應用中錄製 EIF 並通過 visionOS 的文件應用投送到電腦或其他設備，需要在 Info.plist 中增加以下字段並修改：

  • 添加 LSSupportsOpeningDocumentsInPlace 並將值設置爲 true。

  • 添加 UIFileSharingEnabled 並將值設置爲 true。

Modify Info.plist

提示

添加字段後 Xcode 界面上顯示的 Key 與手動添加的字符串不同（比如輸入了 LSSupportsOpeningDocumentsInPlace 但顯示 Supports opening documents in place，這是正常的）。