Hz Unity Meta Interaction SDK

Meta XR Interaction SDK (com.meta.xr.sdk.interaction.ovr)

Use ISDK for interaction on Meta VR

The Core SDK (com.meta.xr.sdk.core) gives you the headset - camera rig, tracking, OVRManager. It does not give you interaction. ISDK is the interaction layer. Don't hand-roll grabbing on OVRInput, 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.

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. OVRQuickActionsAPI builds the rig; QuickActionsAPI makes objects interactive and equips interactors. Reach for manual prefab assembly only when a Quick Action cannot express what you need - and say so.

Meta's own guidance too: Quick Actions are "the fastest and recommended way" to add the rig (docs).

Quick start

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.

Which call for which interaction

Every one of these takes a GameObject target - never a component. Passing a Canvas to a Canvas call is a compile error (cannot convert from 'UnityEngine.Canvas' to 'UnityEngine.GameObject'); pass canvas.gameObject or the result of GameObject.Find. Likewise the interactor calls take the GameObject that carries the Hand/Controller, not the component.

Signatures, 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 - AddOVRInteractionRig() already ships every interactor, so after it they are redundant.

When the rig isn't in your scene

An interaction needs a matching interactor at runtime, in the loaded scene set. It does not need the rig present at author time.

So all of these are fine: the rig is instantiated at runtime, lives in a bootstrap scene under DontDestroyOnLoad, arrives from an additive scene, or you are authoring a prefab.

The 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 DistanceHandGrabInteractable with no DistanceHandGrabInteractor 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.

Baking interaction into a prefab

Verified: run the interactable call on a scene instance, then save. The wiring is self-contained - the interactable's _pointableElement resolves to the Grabbable inside the prefab, with no leaked scene reference.

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 interactable.PointableElement - it is assigned in Awake(), which never runs on an asset, so it is always null there even when the prefab is correct. Read the serialized field: new SerializedObject(interactable).FindProperty("_pointableElement").objectReferenceValue.
• Canvas calls: pass fixPointableCanvasModule: false when the PointableCanvasModule comes from a prefab or an unloaded additive scene, or you get a second one in the open scene.

Running the calls - both APIs are Editor-only

They live in Editor assemblies and cannot run from a MonoBehaviour or anything in a build.

1. Live Editor via unity-cli (preferred when one is open - drive it instead of editing scene 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

Use run_script with a .cs file rather than eval: shell quoting mangles C# char literals (' '), the file is re-runnable, it can live outside Assets/, and --timeout_ms awaits async entry points.

2. A project Editor script under Assets/Editor/ (or an Editor-only asmdef referencing Oculus.Interaction.Editor and Oculus.Interaction.OVR.Editor), exposed as a [MenuItem] - when a human should be able to repeat the setup.

3. MCP, if a Unity MCP server is connected. Its harness constraints (no using System.Reflection;, no BindingFlags overloads, package Editor assemblies not referenced) apply there and not to unity-cli's Roslyn run_script — see unity-mcp-fallback.md.

Finish by saving the scene (EditorSceneManager.MarkSceneDirty + SaveScene), then verify.

Installing

Install com.meta.xr.sdk.interaction.ovr - it pulls in Essentials and the Core SDK. Check Packages/manifest.json first; if it is listed, do not re-add. Installing only com.meta.xr.sdk.interaction is the classic misinstall: interaction model, no OVR binding, no rig, no OVRQuickActionsAPI.

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

Or against a live Editor: unity command package_add --identifier com.meta.xr.sdk.interaction.ovr --confirm true --wait true.

A successful add forces a recompile and domain reload - never install a package and use its API in the same script. Details: installation.md.