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，這是正常的）。