hz-unity-meta-interaction-sdk

Meta XR Interaction SDK（com.meta.xr.sdk.interaction.ovr）

在 Meta VR 上使用 ISDK 进行交互

Core SDK（com.meta.xr.sdk.core）提供头显所需的内容——摄像机 Rig、追踪和 OVRManager。 它不提供交互功能。ISDK 是交互层。 不要自行基于 OVRInput、射线投射或触发器碰撞体实现抓取：ISDK 已经对悬停／选择状态、姿势 贴合、投掷速度和交互器仲裁进行了建模，自行实现的版本会逐渐偏离 平台行为。

目标	操作
Meta VR / Horizon OS，或未说明平台	OVR 后端（com.meta.xr.sdk.interaction.ovr）——本文其余内容均适用
跨平台，仍使用 ISDK	UnityXR 后端（Essentials + Unity XR Hands）。模型相同，入口不同——请查阅相关内容，不要想当然地使用 OVR 入口
跨平台，不使用 ISDK	请停止。本指南不适用。

不要推断用户有跨平台意图——默认使用 OVR，只有用户明确说明时才切换，并 说明你使用了哪个后端。

通过 Quick Actions API 配置交互，不要手动配置。 OVRQuickActionsAPI 会构建 Rig；QuickActionsAPI 会使对象可交互并配置交互器。只有 Quick Action 无法满足需求时， 才考虑手动组装预制件——并说明原因。

Meta 自己也推荐如此：Quick Actions 是添加 Rig 的“最快且推荐的方式” （文档）。

快速开始

using Oculus.Interaction.Editor.QuickActions;         // QuickActionsAPI
using Oculus.Interaction.OVR.Editor.QuickActions;     // OVRQuickActionsAPI

// Delete the default Main Camera first - ISDK brings its own camera rig.

// 1. Rig: comprehensive interaction rig (hands + controllers + every interactor + visuals),
//    plus an OVRCameraRig if the scene has none.
OVRQuickActionsAPI.AddOVRInteractionRig();

// 2. Interactable: adds Rigidbody + Grabbable + a HandGrab/Grab interactable child.
var cube = GameObject.CreatePrimitive(PrimitiveType.Cube);
cube.transform.localScale = Vector3.one * 0.1f;
cube.transform.position = new Vector3(0f, 1.0f, 0.4f);   // in reach at a FloorLevel origin
QuickActionsAPI.AddGrabInteraction(cube);

每个方法都会返回其创建的根 GameObject，而不是你传入的目标。可以通过它查找需要配置或重命名的对象。

不同交互该调用哪个方法

功能	调用
交互 Rig（+ 摄像机 Rig）	OVRQuickActionsAPI.AddOVRInteractionRig()
手部抓取（近距离）	QuickActionsAPI.AddGrabInteraction(go)
距离抓取	QuickActionsAPI.AddDistanceGrabInteraction(go, mode)
射线抓取	QuickActionsAPI.AddRayGrabInteraction(go)
凝视抓取（眼动追踪）	QuickActionsAPI.AddGazeInteraction(go)
传送表面	QuickActionsAPI.AddTeleportInteraction(go, surfaceType)
对 Canvas 使用戳触／射线／凝视	QuickActionsAPI.AddPokeCanvasInteraction(go) · AddRayCanvasInteraction · AddGazeCanvasInteraction
在手部／控制器上添加交互器	QuickActionsAPI.AddHandInteractors(go, types) · AddControllerInteractors · AddControllerHandInteractors
触摸式手部抓取、普通戳触、普通射线	没有 API——只能通过菜单项添加

这些方法的参数都必须是 GameObject target——不能传入组件。向 Canvas 方法传入 Canvas 会导致编译错误（cannot convert from 'UnityEngine.Canvas' to 'UnityEngine.GameObject'）； 请传入 canvas.gameObject 或 GameObject.Find 的结果。同样，交互器方法需要传入承载 Hand／Controller 的 GameObject，而不是组件。

方法签名、参数及各方法创建的内容： quick-actions-api.md · ovr-quick-actions-api.md。 各功能对应的 Meta 文档：documentation.md。

交互器方法仅适用于手动搭建的 Rig——AddOVRInteractionRig() 已包含所有交互器，因此调用该方法后再调用这些方法是多余的。

场景中没有 Rig 时

交互在运行时、已加载的场景集合中需要匹配的 交互器，但创作时不需要场景中已有 Rig。

快捷操作	场景中需要 Rig 吗？
可交互对象（抓取、距离抓取、射线抓取、凝视、画布、传送）	不需要 - 它们所需的一切都在目标对象本身
交互器（AddHandInteractors 及其同类项）	需要 - target 必须带有 Hand / Controller
AddOVRInteractionRig()	它会创建 Rig

因此，以下情况都没问题：Rig 在运行时实例化、位于 DontDestroyOnLoad 下的引导场景中、从叠加场景加载，或者你正在创作预制件。

后果。 可交互对象快捷操作也会在找到 Rig 时，为其补充匹配的交互器；没有 Rig 时则会静默跳过。不会出错，但没有人添加这些交互器，因此最终加载的 Rig 必须预先带有所需类型的交互器。如果运行时 Rig 上没有 DistanceHandGrabInteractor，那么 DistanceHandGrabInteractable 将无法工作，也不会记录任何日志。针对不存在的 Rig 进行创作时，请说明运行时 Rig 必须提供哪些类型的交互器。

将交互烘焙进预制件

已验证：在场景实例上调用可交互对象方法，然后保存。接线是自包含的 - 可交互对象的 _pointableElement 会解析到预制件内的 Grabbable，不会泄漏场景引用。

var go = GameObject.CreatePrimitive(PrimitiveType.Cube);
QuickActionsAPI.AddGrabInteraction(go);                       // no rig needed
PrefabUtility.SaveAsPrefabAsset(go, "Assets/Grabbable.prefab", out bool ok);
Object.DestroyImmediate(go);

• 不要通过 interactable.PointableElement 验证预制件资源 - 该属性在 Awake() 中赋值，而资源不会运行 Awake()，因此即使预制件正确，它在此处也始终为 null。请读取序列化字段： new SerializedObject(interactable).FindProperty("_pointableElement").objectReferenceValue。
• **画布调用：**当 PointableCanvasModule 来自预制件或尚未加载的叠加场景时，传入 fixPointableCanvasModule: false，否则会在打开的场景中再生成一个。

运行调用 - 两种 API 都仅限 Editor

它们位于 Editor 程序集中，不能从 MonoBehaviour 或构建版本中的任何内容运行。

1. 通过 unity-cli 使用实时 Editor（有已打开的 Editor 时优先 - 应驱动它，而不是编辑场景 YAML）：

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

请使用 run_script 配合 .cs 文件，而不要使用 eval：Shell 引号处理会破坏 C# 字符字面量（' '），文件可重复运行、可放在 Assets/ 目录之外，并且 --timeout_ms 会等待异步入口点完成。

2. 项目中的 Editor 脚本，放在 Assets/Editor/ 下（或使用引用 Oculus.Interaction.Editor 和 Oculus.Interaction.OVR.Editor 的仅 Editor asmdef），并通过 [MenuItem] 暴露 - 适用于需要让用户能够重复执行设置的情况。

3. MCP，前提是已连接 Unity MCP 服务。它的执行环境限制（不允许 using System.Reflection;、不允许使用 BindingFlags 重载、未引用包的 Editor 程序集）适用于该环境，不适用于 unity-cli 的 Roslyn run_script - 请参阅 unity-mcp-fallback.md。

最后保存场景（EditorSceneManager.MarkSceneDirty + SaveScene），然后进行验证。

安装

安装 com.meta.xr.sdk.interaction.ovr - 它会一并安装 Essentials 和 Core SDK。先检查 Packages/manifest.json；如果已列出，就不要重复添加。只安装 com.meta.xr.sdk.interaction 是典型的错误安装：有交互模型，却没有 OVR 绑定、没有 Rig，也没有 OVRQuickActionsAPI。

using UnityEditor.PackageManager;
var request = Client.Add("com.meta.xr.sdk.interaction.ovr");   // async - poll request.IsCompleted

或者对实时 Editor 执行：unity command package_add --identifier com.meta.xr.sdk.interaction.ovr --confirm true --wait true。

成功添加后会强制重新编译并重新加载域 - 切勿在同一脚本中安装包后立即使用其 API。详情请参阅：installation.md。

寻找真相：先看源码，再查文档

回答 ISDK 问题时，切勿凭记忆。 已安装的包是了解行为的权威来源；Meta 的文档则说明意图并提供设计指导。

按文件名模式搜索 API 源码——无论安装方式如何（注册表缓存、嵌入式或本地安装），这种方式都适用：

**/com.meta.xr.sdk.interaction*/Editor/QuickActions/Scripts/QuickActionsAPI.cs
**/com.meta.xr.sdk.interaction.ovr*/Editor/QuickActions/Scripts/OVRQuickActionsAPI.cs

然后，后续查找都使用解析出的包根目录。

在 Unity 中，AssetDatabase 路径不受安装方式影响： Packages/com.meta.xr.sdk.interaction.ovr/Runtime/Prefabs/...。

查阅文档时，使用 metavr：调用 vr_docs_search(query, scope="unity") 获取 doc_path，然后调用 vr_docs_get_page；查找签名则调用 vr_api_search(query, engine="unity")。切勿手动拼接文档 URL；命名空间会有所不同。精选索引： documentation.md。

这两个 API 是受支持的入口；其底层机制并非公共 API。 如果你打算用反射调用向导，很可能是漏看了某个方法——先重新阅读这两个文件。相同的操作也可以通过 GameObject > Interaction SDK 菜单中的阻塞式向导窗口完成；想了解调用会创建什么内容时，可以打开对应窗口。

文档没有说明的内容

以下信息只能从源码或运行时故障中发现。

• 可选组件也会一并创建。 调用相当于在向导中点击 Fix All 和 Add All。AddDistanceGrabInteraction 还会创建一个根对象 ISDK_SnapZone (<target>)；物体在不再被触碰后会被拉回——若不需要，可将其删除。详情：quick-actions-api.md。
• 抓取调用会将 Rigidbody 设为运动学状态（useGravity = false; isKinematic = true）。物体会悬浮在你放置的位置，这是预期行为。
• 创建的对象名称由向导决定——ISDK_HandGrabInteraction、ISDK_SnapZone (...)。 如果名称很重要，可在之后重命名；组件通过引用追踪，因此重命名是安全的。
• 交互器调用的目标是 Hand/Controller 对象本身。 子对象上的 Hand 派生组件会记录 Could not execute HandInteractorWizard；可使用 .Where(h => h.GetType() == typeof(Hand)) 进行筛选。
• 枚举名称与其选择的组件不一致。 DistanceGrabMode、场景中的 Movement Provider 和 Meta 文档中的标签是三套不同的术语——切勿猜测它们之间的对应关系。
• 向导提供了一些 API 不支持的设置。 如果需要的设置不是参数之一，请使用菜单项，或在结果创建后进行处理。Rig 上的 Smooth Locomotion 是最常见的例子。
• Building Blocks 是达成相同结果的另一条途径，并非更好的选择。优先使用 API：不会添加 block-tracking 组件，无需额外执行项目设置流程，名称也更易读。
• 没有 API 就是没有 API。 如果你要实现的功能没有对应方法，请使用菜单项或通过组件构建——不要通过反射调用向导。

始终在 Play 模式下验证

ISDK 会在 Start() 中断言其连接配置，因此 Inspector 中看起来正确的场景仍可能抛出异常。仅在编辑时检查组件并不足够。

1. 清空控制台，进入 Play 模式，查看控制台，然后退出。
2. 标准是零错误且零异常。每个 AssertionException 都会指出具体的组件和字段——请将其视为真实缺陷。
3. [MetaXRFeature]: ErrorFormFactorUnavailable xrGetSystem 仅表示未连接头显/XRSIM；OpenXR teardown 警告无害。
4. 有些故障不会显示出来——请参阅 verification.md。
5. Play 模式下确认无误后，还需在真实头显上验证：构建 APK，运行 metavr app install <apk>，然后在测试每种交互时运行 metavr adb logcat --follow --tag Unity，实时查看日志。

参考资料

• quick-actions-api.md - 调用签名、枚举，以及每个调用构建的内容
• ovr-quick-actions-api.md - rig 调用及其创建的 rig
• interaction-model.md - 交互器/可交互对象模型、rig 结构、放置方式
• installation.md - 安装路径、依赖链、程序集
• verification.md - Play 模式循环、断言表、静默失败
• documentation.md - Meta 文档精选索引和查找方法
• unity-mcp-fallback.md - 使用 Unity MCP 而非 unity-cli 运行调用

相关技能

• hz-unity-meta-core-sdk - 摄像机 rig、OVRManager、追踪原点、手部追踪支持、 Project Setup Tool、AndroidManifest
• unity-cli - 驱动正在运行的 Editor
• hz-xr-simulator-install-and-configure / hz-vr-debug - 在 Play 模式之外运行和调试