hz-unity-meta-core-sdk

Meta XR Core SDK（com.meta.xr.sdk.core）

Meta XR Core SDK 是用于开发面向 Meta VR 设备的 VR 和 MR 应用的基础 Unity 包。它提供核心 XR rig、设备管理、输入处理，以及对透视、手部追踪、空间锚点和场景理解等平台功能的访问。

包：com.meta.xr.sdk.core

运行 SDK 代码 — 使用 unity-cli 驱动正在运行的 Editor

这里的所有内容都是仅限 Editor 的 C#。请对已打开的 Editor 运行代码，而不是手动编辑场景、清单或设置文件。连接、--project-path 和安全模式恢复说明见 unity-cli 技能。

unity status --format json          # look for state "ready"
unity command run_script --project-path <proj> --file AgentScripts/Setup.cs --entry Setup.Run --format json

优先使用 run_script，而不是 eval — 将 .cs 文件放在 Assets/ 之外（路径相对于项目根目录解析），这样写入文件不会触发导入或域重新加载，shell 引号也不会破坏 C# 字面量。

SDK 特定注意事项：

• 无需通过反射发现类型。 run_script 会引用所有已加载的程序集，因此 OVRProjectSetup、OVRManifestPreprocessor 等类型可以直接编译；内部部分（_principalRegistry、GetTasks）也可使用 using System.Reflection; 和 BindingFlags。
• 对可能打开 EditorUtility.DisplayDialog 的操作，传入 silentMode: true — 模态对话框会阻塞请求，直到超时。
• 异步工作会在脚本返回后完成（FixAllAsync、Client.Add）— 请通过单独的后续 run_script 验证；切勿在主线程调用 Task.Wait()。
• 场景编辑：MarkSceneDirty + SaveScene（+ AssetDatabase.SaveAssets()），然后读回该值。
• 想要使用 Unity MCP 而非 CLI 驱动 Unity？其限制会导致上述做法无法使用：references/unity-mcp-fallback.md。

查找 SDK 源码

根据项目设置，com.meta.xr.sdk.core 包可能位于不同位置：

• Library/PackageCache/com.meta.xr.sdk.core@<hash>/（从注册表缓存）
• Packages/com.meta.xr.sdk.core/（本地包引用）
• 自定义磁盘路径（嵌入式或本地文件夹）

搜索 SDK 源码之前，先按文件名模式搜索一个已知文件，以定位包根目录：

**/com.meta.xr.sdk.core*/Scripts/OVRManager.cs

然后在后续所有搜索操作中使用解析出的父路径。

重要：每次更改 OVRProjectConfig 或 OVRManager 功能后

**每当修改 OVRProjectConfig 或 OVRManager 功能设置（手部追踪、透视、无边界、目标设备等）时，都必须调用 GenerateOrUpdateAndroidManifest() 并验证结果。**完整工作流程见 references/android-manifest.md。

快速参考

组件	用途
OVRCameraRig	替代 Unity Main Camera 的主要 XR rig 预制件
OVRManager	管理设备状态、功能和配置的单例
OVRInput	控制器输入和追踪的统一 API
OVROverlay	用于呈现更清晰文字、UI 和视频的合成器图层
OVRPassthroughLayer	启用透视可视化
OVRSpatialAnchor	锁定在世界空间中的空间锚点
OVRBoundary	Guardian 边界系统访问接口
OVRProjectSetup	用于配置任务的项目设置工具

OVRCameraRig：主要 XR Rig

OVRCameraRig 预制件是创建 VR/MR 场景时要添加的主要 GameObject。它会替代 Unity 的传统 Main Camera，并提供：

• 左右眼立体渲染
• 通过 TrackingSpace 层级进行头部和位置追踪
• 眼睛锚点（CenterEyeAnchor、LeftEyeAnchor、RightEyeAnchor）
• 手部/控制器锚点（LeftHandAnchor、RightHandAnchor）

层级结构

OVRCameraRig 层级包含眼睛锚点、手部/控制器锚点和多模态锚点。要查看当前结构，请检查 OVRCameraRig 预制件，或在场景中实例化该预制件并检查 TrackingSpace 子对象。

将 OVRCameraRig 添加到场景

处理需要支持 XR 的场景时：

1. 检查当前场景中是否存在 OVRCameraRig
2. 如果未找到，Agent 应：
   • 选项 A：询问用户哪个场景包含 OVRCameraRig（它是 OVRCameraRig 预制体实例的一部分）
   • 选项 B：打开 Agent 知道存在 OVRCameraRig 的场景
   • 选项 C：询问用户是否要将 OVRCameraRig 预制体添加到当前场景
3. 添加 OVRCameraRig 时，请按照 references/ovr-camera-rig.md 中的设置步骤操作。

OVRManager：功能配置

OVRManager（OVRManager.cs）是 VR 硬件的主要接口。它是附加到 OVRCameraRig 预制体上的单例，可将 Meta XR SDK 暴露给 Unity。它控制：

• 目标设备 - 要适配的 Meta VR 设备
• 性能与画质 - MSAA、自适应分辨率、动态分辨率
• 追踪 - 追踪原点类型（眼睛高度、地面高度、舞台、静止）
• 显示 - 色域设置
• Quest 功能 - 手部追踪、透视、键盘、焦点感知、安全性、实验性功能
• 混合现实采集 - 与真实世界画面合成

分析 OVRManager 以了解功能

要了解有哪些可用功能以及如何配置，请分析场景中 OVRCameraRig 上的 OVRManager 组件。OVRManager 检视面板会按类别列出所有可配置的 XR 功能。

完整设置参考（追踪原点、透视、边界、OVRProjectConfig 上的手部追踪等），请参阅 references/ovr-manager.md。

关键：更改序列化字段时使用 SerializedObject，而非反射

要更改任何组件上的序列化字段，请通过 SerializedObject + FindProperty(name) + ApplyModifiedProperties() 进行编辑，切勿使用反射（FieldInfo/PropertyInfo.SetValue）。反射会修改内存中的对象，但会绕过序列化：对于预制体实例上的组件（例如 OVRCameraRig 上的 OVRManager），更改不会记录为预制体覆盖，并且保存时会被静默丢弃（SaveScene 返回 true，但字段会恢复为预制体默认值）。

• 将组件作为 UnityEngine.Object 获取（FindObjectOfType / GetComponent）；SerializedObject/FindProperty 按名称操作，因此无需 asmref。
• 序列化名称是 [SerializeField] 的后备字段（通常为 _camelCase），而非公共属性。如果 FindProperty 返回 null，可通过遍历 so.GetIterator()（Next(true) → 记录 propertyPath）来查找名称。
• 调用 ApplyModifiedProperties() 后，依次调用 MarkSceneDirty → SaveScene → SaveAssets，然后重新读取字段以确认其已持久化。

// component obtained as UnityEngine.Object (e.g. FindObjectOfType(type) as Object)
var so = new SerializedObject(component);
so.FindProperty("_SERIALIZED_FIELD_NAME").boolValue = true;   // typed accessor: boolValue/floatValue/intValue/...
so.ApplyModifiedProperties();                                 // records the prefab-instance override + marks dirty

var scene = EditorSceneManager.GetActiveScene();
EditorSceneManager.MarkSceneDirty(scene);
EditorSceneManager.SaveScene(scene);
AssetDatabase.SaveAssets();

// verify before declaring success
var check = new SerializedObject(component).FindProperty("_SERIALIZED_FIELD_NAME").boolValue;

OVRProjectSetup（UPST）：列出并修复项目问题

Unity 项目设置工具（UPST）（OVRProjectSetup）是 Unity 编辑器扩展，用于验证 Meta VR 项目配置。它维护一个配置任务注册表，每个任务都会检查特定设置，并报告该设置是否满足要求。

主要用途：列出当前平台的所有未解决问题，然后进行修复。

• 列出问题 — 查询所有任务，按平台和有效性筛选，并报告 IsDone 为 false 的任务。每个问题都有一个级别（Required、Recommended、Optional）、一个分组（Compatibility、Rendering、Features 等）和一种修复类型（Auto-fix 或 Manual）。
• 修复问题 — 使用 FixAllAsync(BuildTargetGroup) 自动修复所有可修复的问题，或直接调用各个 FixAction 委托。

通过 unity-cli 对运行中的 Editor 以编程方式调用 UPST（完整 API、任务注册表访问、属性读取和修复调用模式，请参阅 references/project-setup-tool.md）。

通过 UI 访问：Meta > Tools > Project Setup Tool。

UPST 全部显示为绿色后，在硬件上验证：构建 APK，运行 metavr app install <apk>，并确认预期功能已在 metavr log --tag Unity 快照中初始化。

重要：AndroidManifest 更新

对于由 OVRProjectConfig 管理的功能，绝不要直接编辑 AndroidManifest.xml。 完整的 Manifest 更新工作流和规则，请参阅 references/android-manifest.md。

核心功能

Passthrough（混合现实）

Passthrough 可在头显中实时呈现物理世界，支持混合现实体验。设置步骤和配置请参阅 references/passthrough.md。

手部追踪

手部追踪无需控制器即可实现自然的手部交互。设置和配置请参阅 references/hand-tracking.md。

空间锚点

空间锚点可将虚拟内容锚定到现实世界中的位置，并在不同会话间保持不变。

空间锚点详情请参阅 references/spatial-anchors.md。

Scene API

Scene 可访问用户物理环境模型（墙壁、地板、家具），用于具备场景感知能力的 MR 体验。

Scene API 详情请参阅 references/scene-api.md。

无边界模式

无边界模式会在可见物理世界的 MR 体验中禁用 Guardian 边界。

无边界模式的设置方法请参阅 references/boundaryless.md。

合成器图层（OVROverlay）

OVROverlay 通过 VR 合成器直接渲染纹理，绕过眼缓冲区重采样，使文本、UI 和视频更加清晰。每个场景最多支持 15 个叠加图层，形状包括四边形、圆柱体、立方体贴图、等距柱状和鱼眼。

合成器图层详情请参阅 references/ovr-overlay.md。

控制器输入（OVRInput）

OVRInput 提供统一接口，用于访问控制器按钮、扳机、摇杆和追踪数据。

控制器输入详情请参阅 references/controller-input.md。

项目设置工作流

完整的项目设置工作流（安装 SDK、设置构建平台、配置 XR 提供程序、添加 OVRCameraRig、配置 OVRManager、生成 AndroidManifest），请参阅 references/project-setup-workflow.md。

文档链接

所有文档引用均指向 developers.meta.com 上 Meta 官方开发者文档：

• Meta XR Core SDK 概览
• OVRCameraRig 配置
• 项目设置工具
• Android 清单生成
• Passthrough API
• 手部追踪概览
• 空间锚点概览
• 场景概览
• 合成器层（OVROverlay）
• 控制器输入
• 项目配置

使用 metavr 工具获取最新文档

如果 metavr MCP 服务可用，请使用 mcp__metavr__vr_docs_search 和 mcp__metavr__vr_docs_get_page 工具核实当前 API 详情，因为 Meta SDK 文档会频繁更新。使用 mcp__metavr__vr_api_search 并设置 engine='unity'，查找 OVRManager、OVRCameraRig、OVRInput 和其他类的确切方法签名。

相关技能

• unity-cli — 操作正在运行的 Editor、安装编辑器、构建／测试
• hz-unity-meta-interaction-sdk — 交互层（抓取、戳碰、传送、交互 rig）
• hz-xr-simulator-install-and-configure / hz-vr-debug — 在 Play 模式之外运行和调试