hz-unity-meta-interaction-sdk
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMeta XR Interaction SDK (com.meta.xr.sdk.interaction.ovr)
Meta XR Interaction SDK (com.meta.xr.sdk.interaction.ovr)
Use ISDK for interaction on Meta VR
在 Meta VR 上使用 ISDK 进行交互
The Core SDK () gives you the headset - camera rig, tracking, .
It does not give you interaction. ISDK is the interaction layer. Don't hand-roll grabbing on
, raycasts, or trigger colliders: ISDK already models hover/select state, pose
conforming, throw velocity, and interactor arbitration, and a hand-rolled version drifts from
platform behavior.
com.meta.xr.sdk.coreOVRManagerOVRInput| Target | What to do |
|---|---|
| Meta VR / Horizon OS, or platform not stated | OVR backend ( |
| Cross-platform, still on ISDK | UnityXR backend (Essentials + Unity XR Hands). Same model, different entry points - look them up, don't assume the OVR ones |
| Cross-platform not using ISDK | Stop. This skill does not apply. |
Do not infer cross-platform intent - default to OVR, switch only if the user says so, and
state which backend you used.
Set interactions up through the Quick Actions APIs, not by hand.builds the rig;OVRQuickActionsAPImakes objects interactive and equips interactors. Reach for manual prefab assembly only when a Quick Action cannot express what you need - and say so.QuickActionsAPI
Meta's own guidance too: Quick Actions are "the fastest and recommended way" to add the rig
(docs).
Core SDK()负责提供 headset——camera rig、tracking 和 ,但不提供交互。**ISDK 才是交互层。**不要基于 、raycast 或 trigger collider 自行实现抓取:ISDK 已经对 hover/select 状态、pose conforming、throw velocity 和 interactor arbitration 进行了建模,手工实现会逐渐偏离平台行为。
com.meta.xr.sdk.coreOVRManagerOVRInput| 目标 | 应执行的操作 |
|---|---|
| Meta VR / Horizon OS,或未说明平台 | OVR backend( |
| 跨平台,但仍使用 ISDK | UnityXR backend(Essentials + Unity XR Hands)。模型相同,但入口不同——请查阅对应 API,不要假设它们与 OVR API 相同 |
| 跨平台且不使用 ISDK | 停止。本 skill 不适用。 |
不要推断用户有跨平台意图——默认使用 OVR,只有用户明确提出时才切换,并说明使用了哪个 backend。
通过 Quick Actions API 设置交互,不要手工完成。用于构建 rig;OVRQuickActionsAPI让对象可交互并装备 interactor。只有当某个 Quick Action 无法表达需求时,才手动组装 prefab——并明确说明这一点。QuickActionsAPI
Meta 官方指南也指出:Quick Actions 是添加 rig“最快且推荐的方式”
(文档)。
Quick start
快速开始
csharp
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);Every method returns the root GameObjects it created - not the target you passed. Use that
to find what to configure or rename.
csharp
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,而不是传入的 target。请使用返回值来查找需要配置或重命名的对象。
Which call for which interaction
各交互功能对应的调用
| Feature | Call |
|---|---|
| Interaction rig (+ camera rig) | |
| Hand grab (near) | |
| Distance grab | |
| Ray grab | |
| Gaze grab (eye tracking) | |
| Teleport surface | |
| Poke / ray / gaze a Canvas | |
| Interactors on a hand / controller | |
| Touch hand grab, plain poke, plain ray | no API - menu item only |
Every one of these takes a - never a component. Passing a to a
Canvas call is a compile error ();
pass or the result of . Likewise the interactor calls take the
GameObject that carries the /, not the component.
GameObject targetCanvascannot convert from 'UnityEngine.Canvas' to 'UnityEngine.GameObject'canvas.gameObjectGameObject.FindHandControllerSignatures, parameters, and what each call builds:
quick-actions-api.md ·
ovr-quick-actions-api.md.
Per-feature Meta docs: documentation.md.
The interactor calls are only for a hand-built rig - already ships every
interactor, so after it they are redundant.
AddOVRInteractionRig()| 功能 | 调用 |
|---|---|
| Interaction rig(+ camera rig) | |
| 手部抓取(近距离) | |
| 距离抓取 | |
| 射线抓取 | |
| 凝视抓取(眼动追踪) | |
| 表面传送 | |
| 对 Canvas 执行 poke / ray / gaze | |
| 手部/控制器上的 interactor | |
| 触摸式手部抓取、普通 poke、普通 ray | 无 API——只能使用菜单项 |
**所有这些调用都接收一个 ,绝不能传入 component。**将 传给 Canvas 调用会引发编译错误();应传入 或 的结果。同样,interactor 调用要接收承载 / 的 GameObject,而不是 component。
GameObject targetCanvascannot convert from 'UnityEngine.Canvas' to 'UnityEngine.GameObject'canvas.gameObjectGameObject.FindHandController方法签名、参数以及每个调用所构建的内容:
quick-actions-api.md ·
ovr-quick-actions-api.md。
各功能的 Meta 文档:documentation.md。
Interactor 调用仅用于手工构建的 rig—— 已自带全部 interactor,因此调用它后再使用这些方法是冗余的。
AddOVRInteractionRig()When the rig isn't in your scene
当 scene 中没有 rig 时
An interaction needs a matching interactor at runtime, in the loaded scene set. It does not
need the rig present at author time.
| Quick Action | Needs a rig in the scene? |
|---|---|
| Interactables (grab, distance grab, ray grab, gaze, canvas, teleport) | No - everything they require is on the target itself |
Interactors ( | Yes - |
| It creates the rig |
So all of these are fine: the rig is instantiated at runtime, lives in a bootstrap scene under
, arrives from an additive scene, or you are authoring a prefab.
DontDestroyOnLoadThe consequence. An interactable Quick Action also tops up the rig with matching interactors
when it finds one - silently skipped when there is no rig. Nothing breaks, but nobody added
those interactors, so the rig that eventually loads must already carry the types your interactable
needs. A with no on the runtime rig is
inert and logs nothing. When you author against an absent rig, say which interactor types the
runtime rig must provide.
DistanceHandGrabInteractableDistanceHandGrabInteractor每项交互在运行时都需要匹配的 interactor,并且必须位于已加载的 scene 集合中。编辑时,scene 中无需存在 rig。
| Quick Action | scene 中需要 rig 吗? |
|---|---|
| Interactable(grab、distance grab、ray grab、gaze、canvas、teleport) | 否——所需的一切都挂在 target 本身 |
Interactor( | 是—— |
| 它会创建 rig |
因此,以下情况都没有问题:rig 在运行时实例化、存放在 下的 bootstrap scene 中、从 additive scene 加载进来,或者你正在编写 prefab。
DontDestroyOnLoad**由此带来的影响。**当 interactable Quick Action 找到 rig 时,它还会向 rig 补充匹配的 interactor;如果没有 rig,则会静默跳过。不会直接破坏任何功能,但也没有人添加这些 interactor,因此最终加载的 rig 必须已经包含 interactable 所需的类型。运行时 rig 中没有 时, 将完全失效,而且不会记录任何日志。针对编辑时不存在 rig 的情况编写代码时,请说明运行时 rig 必须提供哪些 interactor 类型。
DistanceHandGrabInteractorDistanceHandGrabInteractableBaking interaction into a prefab
将交互烘焙到 prefab 中
Verified: run the interactable call on a scene instance, then save. The wiring is self-contained -
the interactable's resolves to the inside the prefab, with no
leaked scene reference.
_pointableElementGrabbablecsharp
var go = GameObject.CreatePrimitive(PrimitiveType.Cube);
QuickActionsAPI.AddGrabInteraction(go); // no rig needed
PrefabUtility.SaveAsPrefabAsset(go, "Assets/Grabbable.prefab", out bool ok);
Object.DestroyImmediate(go);- Don't verify a prefab asset via - it is assigned in
interactable.PointableElement, which never runs on an asset, so it is always null there even when the prefab is correct. Read the serialized field:Awake().new SerializedObject(interactable).FindProperty("_pointableElement").objectReferenceValue - Canvas calls: pass when the
fixPointableCanvasModule: falsecomes from a prefab or an unloaded additive scene, or you get a second one in the open scene.PointableCanvasModule
已验证:先在 scene instance 上运行 interactable 调用,然后保存。接线是自包含的——interactable 的 会解析到 prefab 内的 ,不会泄漏 scene 引用。
_pointableElementGrabbablecsharp
var go = GameObject.CreatePrimitive(PrimitiveType.Cube);
QuickActionsAPI.AddGrabInteraction(go); // no rig needed
PrefabUtility.SaveAsPrefabAsset(go, "Assets/Grabbable.prefab", out bool ok);
Object.DestroyImmediate(go);- 不要通过 验证 prefab asset——该字段在
interactable.PointableElement中赋值,而 asset 上永远不会运行Awake(),因此即使 prefab 正确,它也始终为 null。请读取序列化字段:Awake()。new SerializedObject(interactable).FindProperty("_pointableElement").objectReferenceValue - **Canvas 调用:**当 来自 prefab 或尚未加载的 additive scene 时,请传入
PointableCanvasModule,否则当前 scene 中会出现第二个fixPointableCanvasModule: false。PointableCanvasModule
Running the calls - both APIs are Editor-only
运行这些调用——两个 API 都仅限 Editor 使用
They live in Editor assemblies and cannot run from a or anything in a build.
MonoBehaviour1. Live Editor via (preferred when one is open - drive it instead of editing
scene YAML):
unity-clibash
unity status --format json # look for state "ready"
unity command run_script --project-path <proj> --file /abs/path/DoTheThing.cs --entry MyClass.Run --format jsonUse with a file rather than : shell quoting mangles C# char literals
(), the file is re-runnable, it can live outside , and awaits async
entry points.
run_script.cseval' 'Assets/--timeout_ms2. A project Editor script under (or an Editor-only asmdef referencing
and ), exposed as a -
when a human should be able to repeat the setup.
Assets/Editor/Oculus.Interaction.EditorOculus.Interaction.OVR.Editor[MenuItem]3. MCP, if a Unity MCP server is connected. Its harness constraints (no , no overloads, package Editor assemblies not referenced) apply
there and not to 's Roslyn — see
unity-mcp-fallback.md.
using System.Reflection;BindingFlagsunity-clirun_scriptFinish by saving the scene ( + ), then verify.
EditorSceneManager.MarkSceneDirtySaveScene它们位于 Editor assemblies 中,无法在 或构建产物中的任何代码中运行。
MonoBehaviour1. 通过 操作实时 Editor(Editor 已打开时优先采用——直接驱动它,而不是编辑 scene YAML):
unity-clibash
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使用 配合 文件,不要使用 :shell quoting 会破坏 C# 字符字面量(),文件可重复运行,可以放在 之外,而且 可以等待异步入口点。
run_script.cseval' 'Assets/--timeout_ms2. 项目 Editor 脚本:放在 下(或使用引用 和 的 Editor-only asmdef),并公开一个 ,便于人工重复执行设置。
Assets/Editor/Oculus.Interaction.EditorOculus.Interaction.OVR.Editor[MenuItem]3. MCP:如果连接了 Unity MCP server。其 harness 限制(禁止 、禁止 overload、不能引用 package Editor assemblies)仅适用于 MCP,不适用于 的 Roslyn ——参见
unity-mcp-fallback.md。
using System.Reflection;BindingFlagsunity-clirun_script最后保存 scene( + ),然后进行验证。
EditorSceneManager.MarkSceneDirtySaveSceneInstalling
安装
Install - it pulls in Essentials and the Core SDK. Check
first; if it is listed, do not re-add. Installing only
is the classic misinstall: interaction model, no OVR binding, no
rig, no .
com.meta.xr.sdk.interaction.ovrPackages/manifest.jsoncom.meta.xr.sdk.interactionOVRQuickActionsAPIcsharp
using UnityEditor.PackageManager;
var request = Client.Add("com.meta.xr.sdk.interaction.ovr"); // async - poll request.IsCompletedOr against a live Editor: .
unity command package_add --identifier com.meta.xr.sdk.interaction.ovr --confirm true --wait trueA successful add forces a recompile and domain reload - never install a package and use its
API in the same script. Details: installation.md.
安装 ——它会引入 Essentials 和 Core SDK。先检查 ;如果已经列出,则不要重复添加。只安装 是典型的错误安装:这样只有 interaction model,没有 OVR binding、rig 或 。
com.meta.xr.sdk.interaction.ovrPackages/manifest.jsoncom.meta.xr.sdk.interactionOVRQuickActionsAPIcsharp
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成功添加会强制触发 recompile 和 domain reload——绝不要在安装 package 的同一个脚本中继续使用其 API。详情:installation.md。
Finding the truth: source first, docs second
查明真相:源码优先,文档其次
Don't answer ISDK questions from memory. The installed package is authoritative for
behavior; Meta's docs for intent and design guidance.
Search for the API sources by filename pattern - this works regardless of install
form (registry cache, embedded, or local):
**/com.meta.xr.sdk.interaction*/Editor/QuickActions/Scripts/QuickActionsAPI.cs
**/com.meta.xr.sdk.interaction.ovr*/Editor/QuickActions/Scripts/OVRQuickActionsAPI.csThen use the resolved package roots for all subsequent lookups.
Inside Unity, paths work regardless of install form:
.
AssetDatabasePackages/com.meta.xr.sdk.interaction.ovr/Runtime/Prefabs/...For docs, query - for the , then
, and for signatures. Never
hand-construct a doc URL; the namespace varies. Curated map:
documentation.md.
metavrvr_docs_search(query, scope="unity")doc_pathvr_docs_get_pagevr_api_search(query, engine="unity")The two APIs are the supported entry points; the machinery under them is not public API. If
you are reaching for reflection to invoke a wizard, you have probably missed a method - re-read
the two files first. The same actions exist under the menu as
blocking wizard windows; open one when you want to see what a call will create.
GameObject > Interaction SDK**不要凭记忆回答 ISDK 问题。**已安装的 package 对行为具有权威性;Meta 文档用于说明意图和设计指导。
按文件名模式搜索 API 源码——无论安装形式是 registry cache、embedded 还是 local,这一点都适用:
**/com.meta.xr.sdk.interaction*/Editor/QuickActions/Scripts/QuickActionsAPI.cs
**/com.meta.xr.sdk.interaction.ovr*/Editor/QuickActions/Scripts/OVRQuickActionsAPI.cs然后在后续所有查找中使用解析得到的 package roots。
在 Unity 内,无论安装形式如何, 路径都可用:
。
AssetDatabasePackages/com.meta.xr.sdk.interaction.ovr/Runtime/Prefabs/...对于文档,使用 查询——通过 获取 ,再调用 ;使用 查询签名。绝不手动拼接文档 URL;namespace 会发生变化。整理后的映射:
documentation.md。
metavrvr_docs_search(query, scope="unity")doc_pathvr_docs_get_pagevr_api_search(query, engine="unity")**这两个 API 才是受支持的入口;其下的实现机制不是 public API。**如果你试图通过 reflection 调用 wizard,很可能只是漏掉了某个方法——先重新阅读这两个源文件。相同的操作也位于 菜单下,形式是阻塞式 wizard 窗口;当你想查看某个调用会创建什么时,可以打开相应窗口。
GameObject > Interaction SDKWhat the docs don't tell you
文档不会告诉你的内容
Each of these is visible only from the source or from a runtime failure.
- You get the optional components too. A call is equivalent to clicking Fix All and
Add All in the wizard. additionally creates a root
AddDistanceGrabInteractionthat pulls the object back after it goes untouched - delete it to opt out. Detail: quick-actions-api.md.ISDK_SnapZone (<target>) - Grab calls make the Rigidbody kinematic (). Objects float where you put them; that is intended.
useGravity = false; isKinematic = true - Created names come from the wizard - ,
ISDK_HandGrabInteraction. Rename afterwards if it matters; components track by reference, so renaming is safe.ISDK_SnapZone (...) - Interactor calls target the /
Handobject itself.Controller-derived components on child objects logHand; filter withCould not execute HandInteractorWizard..Where(h => h.GetType() == typeof(Hand)) - Enum names don't match the components they select. vs. the Movement Provider in the scene vs. Meta's doc label are three vocabularies - never guess the mapping.
DistanceGrabMode - The wizards expose settings the APIs don't. If you need one that isn't a parameter, use the menu item or post-process the result. Smooth Locomotion on the rig is the common case.
- Building Blocks are another route to the same result, not a better one. Prefer the APIs: no block-tracking components, no project-setup side pass, readable names.
- No API means no API. If there is no method for what you want, use the menu item or build it from components - don't reflect into the wizard.
以下内容只有通过源码或运行时故障才能看到。
- **你也会获得可选组件。**一次调用等同于在 wizard 中点击 Fix All 并点击 Add All。还会额外创建根节点
AddDistanceGrabInteraction,在对象长时间未被触碰后将其拉回——如需退出此行为,请将其删除。详情:quick-actions-api.md。ISDK_SnapZone (<target>) - Grab 调用会将 Rigidbody 设为 kinematic()。对象会悬浮在放置位置;这是预期行为。
useGravity = false; isKinematic = true - 创建的名称来自 wizard——、
ISDK_HandGrabInteraction。之后如有需要可以重命名;组件通过引用进行跟踪,因此重命名是安全的。ISDK_SnapZone (...) - **Interactor 调用以 /
Hand对象本身为目标。**子对象上派生自Controller的组件会记录Hand;请使用Could not execute HandInteractorWizard过滤。.Where(h => h.GetType() == typeof(Hand)) - Enum 名称与它们选择的组件并不一致。、scene 中的 Movement Provider 与 Meta 文档标签是三套不同的词汇——绝不要猜测映射关系。
DistanceGrabMode - **Wizard 暴露的某些设置无法通过 API 访问。**如果所需设置不是参数,请使用菜单项或对结果进行后处理。Rig 上的 Smooth Locomotion 是常见案例。
- **Building Blocks 是达成相同结果的另一种方式,并非更优。**优先使用 API:没有 block-tracking 组件,不需要额外的 project-setup 步骤,名称也更易读。
- **没有 API 就没有 API。**如果不存在满足需求的方法,请使用菜单项或用组件自行构建——不要通过 reflection 进入 wizard。
Always verify in Play mode
始终在 Play mode 中验证
ISDK asserts its wiring in , so a scene that looks correct in the Inspector can still
throw. Edit-time component checks are not sufficient.
Start()- Clear the console, enter Play mode, read the console, exit.
- Zero errors and zero exceptions is the bar. Every names the exact component and field - treat it as a real defect.
AssertionException - only means no headset/XRSIM is attached; OpenXR teardown warnings are benign.
[MetaXRFeature]: ErrorFormFactorUnavailable xrGetSystem - Some failures are silent - see verification.md.
- After Play mode is clean, confirm on a real headset: build an APK, , then stream
metavr app install <apk>while exercising each interaction.metavr adb logcat --follow --tag Unity
ISDK 会在 中对其 wiring 进行断言,因此一个在 Inspector 中看起来正确的 scene 仍可能抛出异常。仅在编辑时检查 component 并不充分。
Start()- 清空 console,进入 Play mode,读取 console,然后退出。
- 零错误且零异常才是标准。每个 都会指出确切的 component 和 field——应将其视为真实缺陷。
AssertionException - 仅表示没有连接 headset/XRSIM;OpenXR teardown warning 无害。
[MetaXRFeature]: ErrorFormFactorUnavailable xrGetSystem - 有些故障是静默的——参见 verification.md。
- Play mode 清理完成后,在真实 headset 上确认:构建 APK,执行 ,然后运行
metavr app install <apk>,同时逐一测试各项交互。metavr adb logcat --follow --tag Unity
References
参考
- quick-actions-api.md - signatures, enums, what each call builds
- ovr-quick-actions-api.md - the rig call and the rig it creates
- interaction-model.md - interactor/interactable model, rig anatomy, placement
- installation.md - install paths, dependency chain, assemblies
- verification.md - Play-mode loop, assertion table, silent failures
- documentation.md - curated Meta doc map and lookup recipe
- unity-mcp-fallback.md - running the calls over Unity MCP instead of
unity-cli
- quick-actions-api.md——方法签名、enum、每个调用所构建的内容
- ovr-quick-actions-api.md——rig 调用及其创建的 rig
- interaction-model.md——interactor/interactable 模型、rig 结构、放置方式
- installation.md——安装路径、依赖链、assemblies
- verification.md——Play mode 循环、断言表、静默故障
- documentation.md——整理后的 Meta 文档映射和查找方法
- unity-mcp-fallback.md——通过 Unity MCP 而不是 运行这些调用
unity-cli
Related skills
相关 skill
- - camera rig,
hz-unity-meta-core-sdk, tracking origin, hand tracking support, Project Setup Tool, AndroidManifestOVRManager - - drive a live Editor
unity-cli - /
hz-xr-simulator-install-and-configure- run and debug beyond Play modehz-vr-debug
- ——camera rig、
hz-unity-meta-core-sdk、tracking origin、手部追踪支持、Project Setup Tool、AndroidManifestOVRManager - ——驱动实时 Editor
unity-cli - /
hz-xr-simulator-install-and-configure——在 Play mode 之外运行和调试hz-vr-debug