unity-xr

用途

此技能可自动化并辅助使用 Unity 开发 XR 应用，重点支持手部追踪、空间音频和面向 Oculus Quest 或 HoloLens 等设备的多平台构建等 AR 和 VR 功能。它利用 Unity 的 XR 生态系统，简化沉浸式交互代码的开发。

适用场景

创建交互式 AR/VR 体验时使用此技能，例如虚拟培训模拟、3D 产品可视化或多人 VR 游戏。对于需要设备无关代码的跨平台项目（如适配 Android ARCore 和 iOS ARKit），或需要针对独立 VR 头显优化性能时，也可使用此技能。

主要功能

• 处理 XR Interaction Toolkit 输入系统：使用 XRBaseInteractable 定义 VR 场景中可抓取的对象。
• 支持 AR Foundation 统一 AR 开发：通过 ARPlaneManager 启用平面检测，以追踪表面。
• 确保跨平台兼容性：使用 Unity 的 Player Settings API 配置多个目标平台的构建设置，例如为特定设备设置 XRSettings.enabled = true;。
• 管理沉浸式交互：通过 XRInteractorLineVisual 为 VR 指针实现射线检测，并使用 2-3 行 C# 代码检查碰撞。
• 优化性能：使用 Unity 的 Profiler 监控帧率，并与 XR 插件集成，将 VR 帧率上限设为 90 FPS。

使用模式

要设置基本的 XR 项目，首先安装 Unity 和 XR 包，并使用 Package Manager 导入 XR Interaction Toolkit，然后创建新场景并添加 XR Rig 预制件。对于 AR，在脚本的 Start() 方法中初始化 AR Session。务必尽早在目标硬件上进行测试。对于 VR 交互，将脚本附加到 GameObject，以处理 OnSelectEntered() 等事件。采用模块化方式组织代码：将输入处理与逻辑分开。构建时使用命令行构建进行自动化，例如运行 Unity -batchmode -projectPath /path/to/project -buildTarget Android -executeMethod BuildScript.PerformBuild。

常用命令/API

• 用于构建的 Unity CLI：使用 Unity -quit -batchmode -projectPath /path/to/project -buildWindows64Player /output/path.exe 编译 VR 构建；添加 -logFile build.log 输出日志。
• XR Interaction API 代码片段：

  using UnityEngine.XR.Interaction.Toolkit;
  public class GrabHandler : XRGrabInteractable { void OnSelectEntered(SelectEnterEventArgs args) { transform.position = args.interactor.transform.position; } }
  

• 用于会话管理的 AR Foundation API：

  using UnityEngine.XR.ARFoundation;
  public class ARManager : MonoBehaviour { private ARSession arSession; void Start() { arSession = FindObjectOfType<ARSession>(); arSession.enabled = true; } }
  

• 配置格式：编辑 Unity 的 ProjectSettings/ProjectSettings.asset 以设置 XR 插件，例如在 XRSettings 下添加 XR Plug-in Management: Oculus。对于 API 密钥（如 AR 服务的密钥），在构建脚本中使用 $ARFOUNDATION_API_KEY 等环境变量。
• 常用端点：集成 Unity 服务时，使用 https://services.unity.com/api/v1/projects 等 REST 端点进行云构建，并通过 $UNITY_ACCESS_TOKEN 进行身份验证。

集成说明

通过 Package Manager CLI 添加 XR 包，将此技能与 Unity 核心引擎集成：Unity -projectPath /path -importPackage path/to/xri.unitypackage。对于外部工具，可通过导出 FBX 模型与 Unreal 或 Blender 集成，然后将模型导入 Unity 并应用 XR 脚本。如果使用版本控制，确保跟踪 .meta 文件；配置 Git hooks 以验证 XR 设置。对于云集成（如 Unity Cloud Build）的身份验证，设置 $UNITY_PROJECT_ID 等环境变量，并在脚本中使用它们：string projectId = System.Environment.GetEnvironmentVariable("UNITY_PROJECT_ID");。务必确保各集成中的 Unity 版本一致，以避免 API 不匹配。

错误处理

检查常见的 XR 错误，例如未找到设备：在启动会话前，在代码中使用 if (!XRSettings.isDeviceActive) { Debug.LogError("XR device inactive"); }。对于 AR 跟踪失败，通过 ARSession.stateChanged 事件进行处理：

ARSession.stateChanged += OnStateChanged; void OnStateChanged(ARSessionStateChangedEventArgs args) { if (args.state == ARSessionState.Error) { Debug.LogError(args.errorCode); } }

在 Editor 设置中使用 Unity 的 ErrorPause 进行调试。对于构建错误，使用脚本解析 CLI 日志，例如检查退出代码：if (process.ExitCode != 0) { throw new Exception("Build failed"); }。始终将 API 调用放在 try-catch 块中，以处理运行时异常，例如 try { arSession.Reset(); } catch (Exception e) { Debug.Log(e.Message); }。

具体使用示例

1. VR 交互场景：要创建一个简单的 VR 抓取器，请启动 Unity 项目，导入 XR Interaction Toolkit，在场景中添加一个 XR Rig，并将此脚本附加到一个对象上：

   using UnityEngine.XR.Interaction.Toolkit;
   public class SimpleGrabber : XRGrabInteractable { protected override void OnSelectEntered(SelectEnterEventArgs args) { rigidbody.isKinematic = true; } }
   

   使用 Unity -batchmode -buildTarget Android -executeMethod BuildPipeline.BuildPlayer 在 Oculus 设备上构建并运行。

2. AR 平面检测：对于 AR 应用，请将 AR Foundation 添加到项目中，并创建一个用于检测平面的脚本：

   using UnityEngine.XR.ARFoundation;
   public class PlaneDetector : MonoBehaviour { private ARPlaneManager planeManager; void Start() { planeManager = gameObject.AddComponent<ARPlaneManager>(); planeManager.planesChanged += OnPlanesChanged; } }
   

   使用 Unity -projectPath /path -buildTarget iOS -customBuildTarget iPhone 构建，并在移动设备上测试。

图关系

• 关联：unity-core（用于通用 Unity 脚本编写和引擎功能）
• 属于：ar-vr 集群（与其他 AR/VR 技能共享依赖项）
• 相关：3d-modeling（用于将资源导入 XR 场景）