Hz Unity Meta Core SDK

Meta XR Core SDK (com.meta.xr.sdk.core)

The Meta XR Core SDK is the foundational Unity package for developing VR and MR applications targeting Meta VR devices. It provides the core XR rig, device management, input handling, and access to platform features like passthrough, hand tracking, spatial anchors, and scene understanding.

Package: com.meta.xr.sdk.core

Running SDK code — drive a live Editor with unity-cli

Everything here is Editor-only C#. Run it against an open Editor instead of hand-editing scene, manifest, or settings files. Connecting, --project-path, and Safe Mode recovery are in the unity-cli skill.

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

Prefer run_script over eval — put the .cs outside Assets/ (path resolves against the project root) so writing it triggers no import or domain reload, and shell quoting can't mangle C# literals.

SDK-specific gotchas:

• No type-discovery reflection needed. run_script references every loaded assembly, so OVRProjectSetup, OVRManifestPreprocessor etc. compile directly; using System.Reflection; and BindingFlags work for the internal bits (_principalRegistry, GetTasks).
• Pass silentMode: true to anything that may open an EditorUtility.DisplayDialog — a modal blocks the request until it times out.
• Async work lands after the script returns (FixAllAsync, Client.Add) — verify in a separate follow-up run_script; never Task.Wait() on the main thread.
• Scene edits: MarkSceneDirty + SaveScene (+ AssetDatabase.SaveAssets()), then read the value back.
• Driving Unity MCP instead of the CLI? Its constraints break the above: references/unity-mcp-fallback.md.

Finding the SDK Source

The package com.meta.xr.sdk.core may be located in different places depending on the project setup:

• Library/PackageCache/com.meta.xr.sdk.core@<hash>/ (cached from registry)
• Packages/com.meta.xr.sdk.core/ (local package reference)
• A custom on-disk path (embedded or local folder)

Before searching for SDK source, first locate the package root by searching for a known file by filename pattern:

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

Then use the resolved parent path for all subsequent search operations.

CRITICAL: After Any OVRProjectConfig or OVRManager Feature Change

Any time you modify OVRProjectConfig or OVRManager feature settings (hand tracking, passthrough, boundaryless, target devices, etc.), you MUST call GenerateOrUpdateAndroidManifest() and verify the result. See references/android-manifest.md for the full workflow.

Quick Reference

OVRCameraRig: The Primary XR Rig

The OVRCameraRig prefab is the primary GameObject to add to create a VR/MR scene. It replaces Unity's conventional Main Camera and provides:

• Stereo rendering for left/right eyes
• Head and positional tracking via the TrackingSpace hierarchy
• Anchors for eyes (CenterEyeAnchor, LeftEyeAnchor, RightEyeAnchor)
• Anchors for hands/controllers (LeftHandAnchor, RightHandAnchor)

Hierarchy Structure

The OVRCameraRig hierarchy includes eye anchors, hand/controller anchors, and multimodal anchors. To see the current structure, inspect the OVRCameraRig prefab or instantiate it in a scene and examine the TrackingSpace children.

Adding OVRCameraRig to a Scene

When working with a scene that needs XR support:

1. Check if OVRCameraRig exists in the current scene
2. If NOT found, the agent should:
   • Option A: Ask the user which scene contains the OVRCameraRig (it is part of the OVRCameraRig prefab instance)
   • Option B: Open a scene where the agent knows the OVRCameraRig exists
   • Option C: Ask the user if they want to add the OVRCameraRig prefab to the current scene
3. When adding OVRCameraRig, follow the setup steps in references/ovr-camera-rig.md.

OVRManager: Feature Configuration

OVRManager (OVRManager.cs) is the main interface to VR hardware. It is a singleton attached to the OVRCameraRig prefab that exposes the Meta XR SDK to Unity. It controls:

• Target Devices - Which Meta VR devices to target
• Performance & Quality - MSAA, adaptive resolution, dynamic resolution
• Tracking - Tracking origin type (Eye Level, Floor Level, Stage, Stationary)
• Display - Color gamut settings
• Quest Features - Hand tracking, passthrough, keyboard, focus awareness, security, experimental features
• Mixed Reality Capture - Real-world compositing

Analyzing OVRManager for Features

To understand what features are available and how they're configured, analyze the OVRManager component on the OVRCameraRig in the scene. The OVRManager Inspector exposes all configurable XR features grouped into sections.

For the full settings reference (tracking origin, passthrough, boundary, hand tracking on OVRProjectConfig, etc.), see references/ovr-manager.md.

CRITICAL: Changing Serialized Fields — Use SerializedObject, Not Reflection

To change a serialized field on any component, edit it via SerializedObject + FindProperty(name) + ApplyModifiedProperties() — never reflection (FieldInfo/PropertyInfo.SetValue). Reflection mutates the in-memory object but bypasses serialization: for a component on a prefab instance (e.g. OVRManager on OVRCameraRig), the change isn't recorded as a prefab override and is silently dropped on save (SaveScene returns true, but the field reverts to the prefab default).

• Get the component as UnityEngine.Object (FindObjectOfType / GetComponent); SerializedObject/FindProperty work by name, so no asmref is needed.
• The serialized name is the [SerializeField] backing field (often _camelCase), not the public property. If FindProperty returns null, discover names by iterating so.GetIterator() (Next(true) → log propertyPath).
• After ApplyModifiedProperties(), call MarkSceneDirty → SaveScene → SaveAssets, then read the field back to confirm it persisted.

// 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;