/hz-unity-meta-interaction-sdk

name: hz-unity-meta-interaction-sdk
license: Apache-2.0
description: Meta XR Interaction SDK (com.meta.xr.sdk.interaction.ovr) in Unity. Use when adding ANY interaction to a Meta VR or Horizon OS scene - grab (hand, distance, ray, touch), poke, teleport/locomotion, gaze, interactable UI canvases - when making an object grabbable, adding interactors to hands or controllers, creating an interaction rig, or baking interaction into a prefab or a scene whose rig loads elsewhere (dynamically, DontDestroyOnLoad, additively). Use the OVR backend unless the user explicitly asks for cross-platform. Covers QuickActionsAPI and OVRQuickActionsAPI as the default way to wire interactions, running them via unity-cli, an Editor script, or MCP, installation, and the undocumented behavior that source-reading or a Play-mode run is otherwise needed to discover.

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.

| Target | What to do | |---|---| | Meta VR / Horizon OS, or platform not stated | **OVR backend** (`com.meta.xr.sdk.interaction.ovr`) - the rest of this skill | | 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.** `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](https://developers.meta.com/horizon/documentation/unity/unity-isdk-add-comprehensive-interaction-rig)).

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

| Feature | Call | |---|---| | Interaction rig (+ camera rig) | `OVRQuickActionsAPI.AddOVRInteractionRig()` | | Hand grab (near) | `QuickActionsAPI.AddGrabInteraction(go)` | | Distance grab | `QuickActionsAPI.AddDistanceGrabInteraction(go, mode)` | | Ray grab | `QuickActionsAPI.AddRayGrabInteraction(go)` | | Gaze grab (eye tracking) | `QuickActionsAPI.AddGazeInteraction(go)` | | Teleport surface | `QuickActionsAPI.AddTeleportInteraction(go, surfaceType)` | | Poke / ray / gaze a Canvas | `QuickActionsAPI.AddPokeCanvasInteraction(go)` · `AddRayCanvasInteraction` · `AddGazeCanvasInteraction` | | Interactors on a hand / controller | `QuickActionsAPI.AddHandInteractors(go, types)` · `AddControllerInteractors` · `AddControllerHandInteractors` | | Touch hand grab, plain poke, plain ray | *no API - menu item only* |

**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](references/quick-actions-api.md) · [ovr-quick-actions-api.md](references/ovr-quick-actions-api.md). Per-feature Meta docs: [documentation.md](references/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.

| 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 (`AddHandInteractors` and siblings) | **Yes** - `target` must carry the `Hand` / `Controller` | | `AddOVRInteractionRig()` | It *creates* the rig |

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 lo