visionOS 工程配置

向Apple Inc.申请企业API许可

注意

请根据 Building spatial experiences for business apps with enterprise APIs for visionOS 向Apple Inc.申请企业应用相机API的entitlement并获取license 。（注意，这个License是Apple公司分发的文件，与EasyAR的License不是一个事物）。

请注意，申请Enterprise entitlement时使用的Bundle ID应与创建EasyAR Sense License Key时填写的一致。

环境要求

  • visionOS 2.0及以上

  • 对应visionOS版本的Xcode16.0及以上并安装visionOS simulator

  • 推荐的Unity版本： 6000.0.23+

Unity visionOS App Mode

Unity的visionOS有4种App模式，其中

EasyAR支持的App Mode有，

  • Metal Rendering with Compositor Services

  • RealityKit with PolySpatial

  • Hybrid - Switch Between Metal and RealityKit

EasyAR不支持的App Mode有，

  • Windowed - 2D Window

../_images/image_g11_17.png

这些模式的差别和使用差异请阅读Unity官方文档。

安装Unity插件

需要安装的Unity插件:

Unity 6+

App Mode = Metal:

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

App Mode = RealityKit/Hybrid:

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

  • com.unity.polyspatial (2.0.4+)

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

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

上面所有插件的版本号需一致

Unity 2023+

部分早期发布的unity 2023.x并不支持构建visionOS包，请使用Unity 6。

Unity 2022.3.19+

App Mode = Metal:

  • com.unity.xr.visionos (1.2.3)

App Mode = RealityKit/Hybrid:

  • com.unity.xr.visionos (1.2.3)

  • com.unity.polyspatial (1.2.3)

  • com.unity.polyspatial.visionos (1.2.3)

  • com.unity.polyspatial.xr (1.2.3)

上面所有插件的版本号需一致

注意

请勿使用1.3.x版本，该版本经验证不能使用。

构建平台配置

切换并确认Build Platform为 visionOS :

../_images/image_g11_1.png

Input System 配置

Edit > Project Settings > Player

  • 设置 Active Input Handling 为 Input System Package(New)

../_images/image_g11_6.png

此后Unity会要求重启工程，点击 Apply 使改动生效，

../_images/image_g11_5.png

XR Plug-in Management 配置

Edit > Project Settings > XR Plug-in Management

  • Plug-in Providers 勾选 Apple visionOS

../_images/image_g11_3.png

Edit > Project Settings > XR Plug-in Management > Apple visionOS

  • 根据需要选择EasyAR支持的 App Mode

../_images/image_g11_17.png

  • 添加 World Sensing Usage Description

  • 设置 Metal Immersion Style 设置为 Mixed

  • 设置 Reality Kit Immersion Style 设置为 Mixed

  • 勾选 IL2CPP Large Exe Workaround

../_images/image_g11_4.png

PolySpatial 配置

备注

App模式为RealityKit或Hybrid时需要配置。

Edit > Project Settings > PolySpatial

  • 设置 Default Volume Camera Window Config 为 Default Unbounded Configuration

  • 勾选 Auto-Create Volume Camera

../_images/image_g11_2.png

如果 Default Volume Camera Window Config 需要使用其它配置，确保其 Mode 为 Unbounded

../_images/image_g11_19.png

删除场景中的 Volume Camera （如果存在）

../_images/image_g11_20.png

  • 如果场景中存在 Volume Camera ，请先删除

  • （不推荐）若因为一些原因需要添加一个 唯一 的自定义 Volume Camera ，请将其 World Transform 设为 identity ，并确保其 Volume Camera Window Configuration 的 Mode 设置为 Unbounded ，请阅读Unity官方文档，并在完全清楚其含义和用途的前提下使用。

  • 不支持 World Transform 数值不是 identity 的 Volume Camera

注意

请务必确认场景中 不存在 Volume Camera 或已按上述描述设置。

TextMesh Pro 配置

备注

App模式为RealityKit或Hybrid时需要配置。

Edit > ProjectSettings > TextMesh Pro

  • 点击 Import TMP Essentials

../_images/image_g11_7.png

备注

目前RealityKit with PolySpatial仅支持TextMesh Pro文字

Bundle ID

设置visionOS应用的Bundle ID, 注意Bundle ID要与创建License Key时填写的一致，并且与向苹果申请的Enterprise entitlement中的Bundle ID一致 。在Player Settings面板设置如下。

../_images/image_g11_8.png

如果License Key异常（比如Bundle ID不匹配），在打包应用时将会看到如下弹出提示

../_images/image_g11_9.png

这时如果选择继续打包，打包出的应用将无法正常使用，请根据窗体提示仔细检查并修复问题后再继续打包。

在一些特殊情况，如果你使用EasyAR的接口手动初始化，不使用Setttings文件中的License Key，你可以选择 Continue and don't warn me again ，或者关闭 Verify License When Build 选项，这将关闭打包时的检查。

../_images/image_g11_10.png

权限配置

你可以检查 EasyAR 所使用的权限。请确保你所使用的功能所使用的权限是打开的。这些选项用于检查 Usage Description 是否填写，并在必要时让编译失败。如果你需要在XCode中而不是Unity中设置 Usage Description ，可以关闭这些选项。

../_images/image_g11_11.png

  • Camera Device: 取消选中。VisionOS的相机权限并不通过这个接口获取，不用设置，也不用开启检查。

  • Video Recording: 取消选中。VisionOS不支持VideoRecorder。

  • Mega: 使用 MegaTrackerFrameFilter 建议开启的权限。开启这个选项将会使用设备的定位权限（只有当com.easyar.mega package存在时才起作用）。

如果打开了 Mega 选项，且com.easyar.mega package存在，需要添加 Location Usage Description ，否则构建将失败。

备注

Unity目前仅在IOS的PlayerSettings中有Location Usage Description字段，在IOS的PlayerSettings中设置的Location字段在VisionOS中也能生效

../_images/image_g11_12.png ../_images/image_g11_13.png

相机权限配置（XCode工程）

通过Unity生成XCode工程，然后在 Signing & Capabilities 页面中 点击 +Capability ，添加 Main Camera Access

../_images/image_g11_15.png

备注

若之前没有向Apple成功申请相应的enterprise entitlement，这一项不会显示

将申请得到的Enterprise.license文件复制到XCode工程目录，并添加至XCode工程中

../_images/image_g11_16.png

EIF默认文件读取配置（XCode工程）

若需要录制EIF并通过Vision Pro的文件应用投送到电脑或其他设备，需要在 Info.plist 中增加以下字段：

  • 添加 LSSupportsOpeningDocumentsInPlace 并将值设置为 true

  • 添加 UIFileSharingEnabled 并将值设置为 true

备注

添加之后显示的文字与添加的字符串不同，这是正常的。

../_images/image_g11_18.png