hz-unity-meta-core-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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 Quest headsets. 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

Meta XR Core SDK是面向Meta Quest头显开发VR和MR应用的基础Unity包。它提供核心XR设备框架、设备管理、输入处理，以及对透视显示、手部追踪、空间锚点和场景理解等平台功能的访问权限。

Package:

com.meta.xr.sdk.core

Finding the SDK Source

查找SDK源文件

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.

根据项目设置的不同，

com.meta.xr.sdk.core

包可能位于不同位置：

Library/PackageCache/com.meta.xr.sdk.core@<hash>/

（从注册表缓存）

```
Packages/com.meta.xr.sdk.core/
```
（本地包引用）
自定义磁盘路径（嵌入式或本地文件夹）

在搜索SDK源文件之前，先通过文件名模式搜索已知文件来定位包根目录：

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

随后使用解析得到的父路径进行所有后续搜索操作。

CRITICAL: After Any OVRProjectConfig or OVRManager Feature Change

重要提示：修改OVRProjectConfig或OVRManager功能设置后

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.

任何时候修改
OVRProjectConfig
或OVRManager功能设置（手部追踪、透视显示、无边界模式、目标设备等），都必须调用
GenerateOrUpdateAndroidManifest()
并验证结果。完整流程请参考references/android-manifest.md。

Quick Reference

快速参考

Component	Purpose
OVRCameraRig	Primary XR rig prefab replacing Unity's Main Camera
OVRManager	Singleton managing device state, features, and configuration
OVRInput	Unified API for controller input and tracking
OVROverlay	Compositor layers for sharper text, UI, and video
OVRPassthroughLayer	Enables passthrough visualization
OVRSpatialAnchor	World-locked spatial anchors
OVRBoundary	Guardian boundary system access
OVRProjectSetup	Project Setup Tool for configuration tasks

组件	用途
OVRCameraRig	替代Unity主相机的核心XR设备预制体
OVRManager	管理设备状态、功能和配置的单例类
OVRInput	用于控制器输入和追踪的统一API
OVROverlay	用于更清晰文本、UI和视频的合成器图层
OVRPassthroughLayer	启用透视显示可视化
OVRSpatialAnchor	与世界锁定的空间锚点
OVRBoundary	访问Guardian边界系统
OVRProjectSetup	用于配置任务的项目设置工具

OVRCameraRig: The Primary XR Rig

OVRCameraRig：核心XR设备框架

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)

OVRCameraRig预制体是创建VR/MR场景时需添加的主要GameObject。它替代Unity传统的主相机，并提供：

左右眼的立体渲染
通过TrackingSpace层级实现头部和位置追踪
眼睛锚点（CenterEyeAnchor、LeftEyeAnchor、RightEyeAnchor）
手部/控制器锚点（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.

OVRCameraRig层级包含眼睛锚点、手部/控制器锚点和多模态锚点。如需查看当前结构，可检查OVRCameraRig预制体，或在场景中实例化它并查看TrackingSpace的子对象。

Adding OVRCameraRig to a Scene

向场景添加OVRCameraRig

When working with a scene that needs XR support:

Check if OVRCameraRig exists in the current scene
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
When adding OVRCameraRig, follow the setup steps in references/ovr-camera-rig.md.

当处理需要XR支持的场景时：

检查当前场景中是否存在OVRCameraRig
如果未找到，助手应：
- 选项A：询问用户哪个场景包含OVRCameraRig（它是OVRCameraRig预制体实例的一部分）
- 选项B：打开助手已知包含OVRCameraRig的场景
- 选项C：询问用户是否要将OVRCameraRig预制体添加到当前场景
添加OVRCameraRig时，请遵循references/ovr-camera-rig.md中的设置步骤。

OVRManager: Feature Configuration

OVRManager：功能配置

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 Quest headsets 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

OVRManager (

OVRManager.cs

) 是与VR硬件交互的主要接口。它是附加在OVRCameraRig预制体上的单例类，将Meta XR SDK暴露给Unity。它控制：

目标设备 - 要适配的Quest头显型号
性能与画质 - MSAA、自适应分辨率、动态分辨率
追踪 - 追踪原点类型（眼高、地面高度、舞台、固定）
显示 - 色域设置
Quest功能 - 手部追踪、透视显示、键盘、焦点感知、安全、实验性功能
混合现实捕捉 - 现实世界合成

Analyzing OVRManager for Features

分析OVRManager的功能

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.

要了解可用功能及其配置方式，请分析场景中OVRCameraRig上的OVRManager组件。OVRManager检视面板将所有可配置的XR功能按分组展示。

完整设置参考（追踪原点、透视显示、边界、OVRProjectConfig上的手部追踪等）请查看references/ovr-manager.md。

OVRProjectSetup (UPST): Listing and Fixing Project Issues

OVRProjectSetup (UPST)：列出并修复项目问题

The Unity Project Setup Tool (UPST) (

OVRProjectSetup

) is a Unity Editor extension that validates project configuration for Meta Quest. It maintains a registry of Configuration Tasks — each task checks a specific setting and reports whether it is satisfied or outstanding.

Primary use: list all outstanding issues for the current platform, then fix them.

List issues — Query all tasks, filter by platform/validity, and report those where
```
IsDone
```
is false. Each issue has a level (Required, Recommended, Optional), a group (Compatibility, Rendering, Features, etc.), and a fix type (Auto-fix or Manual).
Fix issues — Use
```
FixAllAsync(BuildTargetGroup)
```
to auto-fix all fixable issues, or invoke individual
```
FixAction
```
delegates directly.

UPST can be driven programmatically via Unity MCP using reflection (see references/project-setup-tool.md for the full API, task registry access, property reading, and fix invocation patterns).

Access via UI: Meta > Tools > Project Setup Tool.

Unity项目设置工具(UPST) (

OVRProjectSetup

) 是Unity编辑器扩展，用于验证Meta Quest项目的配置。它维护一个配置任务注册表——每个任务检查特定设置并报告其是否已完成。

主要用途：列出当前平台的所有未解决问题，然后修复它们。

列出问题 — 查询所有任务，按平台/有效性筛选，报告
```
IsDone
```
为false的任务。每个问题都有级别（必需、推荐、可选）、分组（兼容性、渲染、功能等）和修复类型（自动修复或手动修复）。
修复问题 — 使用
```
FixAllAsync(BuildTargetGroup)
```
自动修复所有可修复的问题，或直接调用单个
```
FixAction
```
委托。

可通过Unity MCP以编程方式驱动UPST，使用反射（完整API、任务注册表访问、属性读取和修复调用模式请参考references/project-setup-tool.md）。

通过UI访问：Meta > Tools > Project Setup Tool。

CRITICAL: AndroidManifest Update

重要提示：AndroidManifest更新

NEVER directly edit AndroidManifest.xml for features managed by OVRProjectConfig. See references/android-manifest.md for the full manifest update workflow and rules.

切勿直接编辑由OVRProjectConfig管理的功能对应的AndroidManifest.xml。 完整的清单更新流程和规则请查看references/android-manifest.md。

Core Features

核心功能

Passthrough (Mixed Reality)

透视显示（混合现实）

Passthrough provides real-time visualization of the physical world inside the headset, enabling mixed reality experiences. See references/passthrough.md for setup steps and configuration.

透视显示可在头显内实时可视化物理世界，实现混合现实体验。设置步骤和配置请参考references/passthrough.md。

Hand Tracking

手部追踪

Hand tracking enables natural hand interaction without controllers. See references/hand-tracking.md for setup and configuration.

手部追踪无需控制器即可实现自然的手部交互。设置和配置请参考references/hand-tracking.md。

Spatial Anchors

空间锚点

Spatial anchors anchor virtual content to real-world locations that persist across sessions.

For spatial anchors details, see references/spatial-anchors.md.

空间锚点可将虚拟内容锚定到现实世界位置，并在不同会话中保持不变。

空间锚点的详细信息请查看references/spatial-anchors.md。

Scene API

Scene provides access to the user's physical environment model (walls, floor, furniture) for scene-aware MR experiences.

For Scene API details, see references/scene-api.md.

Scene API可访问用户的物理环境模型（墙壁、地面、家具），用于场景感知型MR体验。

Scene API的详细信息请查看references/scene-api.md。

Boundaryless Mode

无边界模式

Boundaryless mode disables the Guardian boundary for MR experiences where the physical world is visible.

For boundaryless setup, see references/boundaryless.md.

无边界模式会禁用Guardian边界，适用于可见物理世界的MR体验。

无边界模式的设置请参考references/boundaryless.md。

Compositor Layers (OVROverlay)

合成器图层（OVROverlay）

OVROverlay renders textures directly via the VR compositor, bypassing eye buffer resampling for sharper text, UI, and video. Supports up to 15 overlay layers per scene with quad, cylinder, cubemap, equirect, and fisheye shapes.

For compositor layer details, see references/ovr-overlay.md.

OVROverlay通过VR合成器直接渲染纹理，绕过眼缓冲区重采样，实现更清晰的文本、UI和视频。每个场景最多支持15个覆盖图层，包括四边形、圆柱体、立方体贴图、等矩形和鱼眼形状。

合成器图层的详细信息请查看references/ovr-overlay.md。

Controller Input (OVRInput)

控制器输入（OVRInput）

OVRInput provides unified access to controller buttons, triggers, thumbsticks, and tracking.

For controller input details, see references/controller-input.md.

OVRInput提供统一的控制器按钮、扳机、摇杆和追踪访问方式。

控制器输入的详细信息请查看references/controller-input.md。

Project Setup Workflow

项目设置流程

For the full project setup workflow (install SDK, set build platform, configure XR provider, add OVRCameraRig, configure OVRManager, generate AndroidManifest), see references/project-setup-workflow.md.

完整的项目设置流程（安装SDK、设置构建平台、配置XR提供程序、添加OVRCameraRig、配置OVRManager、生成AndroidManifest）请参考references/project-setup-workflow.md。

Documentation Links

文档链接

All documentation references point to the official Meta developer docs at developers.meta.com:

所有文档参考均指向developers.meta.com上的官方Meta开发者文档：

Calling SDK Methods via Unity MCP

通过Unity MCP调用SDK方法

SDK classes (e.g.

OVRManifestPreprocessor

OVRProjectSetup

) live in assemblies that are not directly referenceable from Unity MCP compiled scripts. You must use runtime reflection to call them. The Unity MCP compilation environment also has specific quirks that will cause silent crashes if not followed.

SDK类（如

OVRManifestPreprocessor

、

OVRProjectSetup

）所在的程序集无法从Unity MCP编译的脚本中直接引用。必须使用运行时反射来调用它们。Unity MCP编译环境还有一些特定的特性，如果不遵循会导致静默崩溃。

Rules

规则

Never add
using System.Reflection;
— it causes
```
UNEXPECTED_ERROR
```
crashes in the MCP framework. Fully qualify reflection types instead (e.g.
```
System.Reflection.TargetInvocationException
```
).
Never use
BindingFlags
overloads of
```
GetMethod
```
/
```
GetProperty
```
— they also trigger MCP crashes. Use the parameterless
```
GetMethod("MethodName")
```
overload (finds public methods by default).
Always pass
silentMode: true
(or equivalent) for any method that may call
```
EditorUtility.DisplayDialog
```
— dialogs block indefinitely in MCP context.

Always catch
System.Reflection.TargetInvocationException
and log

InnerException

— reflection wraps the real error.

切勿添加
using System.Reflection;
— 这会导致MCP框架中出现
```
UNEXPECTED_ERROR
```
崩溃。请改用完全限定的反射类型（例如
```
System.Reflection.TargetInvocationException
```
）。
切勿使用
GetMethod
/
GetProperty
的
BindingFlags
重载 — 它们也会触发MCP崩溃。使用无参数的
```
GetMethod("MethodName")
```
重载（默认查找公共方法）。
始终传递
silentMode: true
（或等效参数）给任何可能调用
```
EditorUtility.DisplayDialog
```
的方法 — 对话框在MCP环境中会无限阻塞。

始终捕获
System.Reflection.TargetInvocationException
并记录
InnerException
— 反射会包装真实错误。

Template

模板

csharp

using UnityEngine;
using UnityEditor;

internal class CommandScript : IRunCommand
{
    public void Execute(ExecutionResult result)
    {
        // 1. Find the type by name across all loaded assemblies
        System.Type t = null;
        foreach (var asm in System.AppDomain.CurrentDomain.GetAssemblies())
        {
            try { t = asm.GetType("CLASS_NAME_HERE"); } catch { }
            if (t != null) break;
        }
        if (t == null) { result.LogError("Type CLASS_NAME_HERE not found."); return; }

        // 2. Get the method (parameterless overload only — no BindingFlags)
        var m = t.GetMethod("METHOD_NAME_HERE");
        if (m == null) { result.LogError("Method METHOD_NAME_HERE not found."); return; }

        // 3. Invoke with error handling
        try
        {
            m.Invoke(null, new object[] { /* args */ });
            result.Log("Done.");
        }
        catch (System.Reflection.TargetInvocationException tie)
        {
            result.LogError("Error: " + tie.InnerException);
        }
    }
}

Replace

CLASS_NAME_HERE

METHOD_NAME_HERE

, and the args array as needed. For instance methods, pass the target object instead of

null

csharp

using UnityEngine;
using UnityEditor;

internal class CommandScript : IRunCommand
{
    public void Execute(ExecutionResult result)
    {
        // 1. 在所有加载的程序集中按名称查找类型
        System.Type t = null;
        foreach (var asm in System.AppDomain.CurrentDomain.GetAssemblies())
        {
            try { t = asm.GetType("CLASS_NAME_HERE"); } catch { }
            if (t != null) break;
        }
        if (t == null) { result.LogError("Type CLASS_NAME_HERE not found."); return; }

        // 2. 获取方法（仅无参数重载 — 不使用BindingFlags）
        var m = t.GetMethod("METHOD_NAME_HERE");
        if (m == null) { result.LogError("Method METHOD_NAME_HERE not found."); return; }

        // 3. 调用并处理错误
        try
        {
            m.Invoke(null, new object[] { /* args */ });
            result.Log("Done.");
        }
        catch (System.Reflection.TargetInvocationException tie)
        {
            result.LogError("Error: " + tie.InnerException);
        }
    }
}

根据需要替换

CLASS_NAME_HERE

、

METHOD_NAME_HERE

和参数数组。对于实例方法，请传递目标对象而非

null

。

Using metavr Tools for Latest Docs

使用metavr工具获取最新文档

If the

metavr

MCP server is available, use the

mcp__metavr__meta_docs_search

and

mcp__metavr__meta_docs_get_page

tools to verify current API details, as Meta SDK documentation updates frequently. Use

mcp__metavr__search_api_reference

with

engine='unity'

to look up exact method signatures for OVRManager, OVRCameraRig, OVRInput, and other classes.

如果

metavr

MCP服务器可用，请使用

mcp__metavr__meta_docs_search

和

mcp__metavr__meta_docs_get_page

工具验证当前API细节，因为Meta SDK文档更新频繁。使用

mcp__metavr__search_api_reference

并设置

engine='unity'

来查找OVRManager、OVRCameraRig、OVRInput等类的精确方法签名。",