> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/mixed-reality-ai-characters-with-vision-meta-quest.md).

# 使用 Vision 的混合现实 AI 角色（Meta Quest）

构建一个由 Convai 驱动的 AI 角色，它运行在 Meta Quest 透视混合现实应用中，并能通过 Quest 摄像头看到并描述用户周围的现实世界。

{% hint style="info" %}
**前置条件：**

* 已转换为 Android 构建目标的 Unity URP 项目
* 已安装并验证可正常工作的 Convai Unity SDK
* 用于部署的 Meta Quest 3 或 Pro 设备

如果您还没有设置 Convai SDK，请先从 [Unity SDK 安装指南](https://docs.convai.com/api-docs/plugins-and-integrations/unity-plugin-beta-overview/getting-started) 再继续。
{% endhint %}

### 所需包

此设置需要三个包：

| 包                   | Git URL                              |
| ------------------- | ------------------------------------ |
| Convai Unity SDK    | `com.convai.convai-sdk-for-unity`    |
| Meta MR Utility Kit | `com.meta.xr.mrutilitykit@85`        |
| OVR Interaction     | `com.meta.xr.sdk.interaction.ovr@85` |

Meta MR Utility Kit 会自动将 XR Core SDK 作为依赖安装，无需单独安装。

### 第 1 步 — 安装 MR 包

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FRo88ecF7qbd901zD5pmq%2Fimage.png?alt=media&amp;token=79d8bb59-e7b9-4384-bb72-21da2294b52d" alt=""><figcaption></figcaption></figure>

1. 前往 **窗口 > 包管理器**.
2. 点击 **+** 图标并选择 **从 Git URL 安装包**.
3. 将 **Meta MR Utility Kit** 包名粘贴进去并让其安装。这也会自动安装 XR Core SDK。
4. 重复此过程以安装 **OVR Interaction** 包。

安装后您可能会看到一些警告。可以放心忽略。

***

### 第 2 步 — 将项目转换为 XR

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fn3ZGkdYuGdaFiSrE3IBg%2FScreenshot%202026-04-28%20152845.png?alt=media&amp;token=036b9ed0-c37a-491a-ad2f-36dc8233d751" alt=""><figcaption></figcaption></figure>

1. 前往 **文件 > 构建配置文件 > 玩家设置 > XR 插件管理** 并点击 **安装**.
2. 当提示选择插件提供程序时，选择 **OpenXR**.
3. 当被要求启用 **Meta XR 功能集**时，选择 **是**.
4. 点击 **修复方法** 针对出现的任何警告消息。
5. 在 OpenXR 设置下，添加以下交互配置文件：
   * Meta Quest Touch Pro
   * Meta Quest Touch Plus
6. 启用 **Meta Quest 支持**.
7. 移除 **Quest** 和 **Quest 2** 从目标设备列表中。

***

### 第 3 步 — 为透视配置场景

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FqPDewzzGKT3a154A1gII%2FScreenshot%202026-04-28%20152934.png?alt=media&amp;token=124a8a4c-7404-4965-8600-b5ff64f16c73" alt=""><figcaption></figcaption></figure>

默认的 Convai 示例场景使用 Unity 相机和环境对象，这与 Meta 的透视相机装置冲突。在添加 MR 构建块之前，请禁用二者。

1. 在层级视图中，导航到 **Convai > Camera** 并取消勾选相机组件 **Inspector**.
2. 对 **Environment** Convai 下的对象也执行同样操作。
3. 前往 **Meta Quest Tools > Building Blocks**.
4. 在 **Core** 筛选器下，添加 **Camera Rig** 和 **Passthrough**.
5. 在 **Passthrough** 筛选器下，添加 **透视摄像头访问** — 这是必需的，因为视觉馈流必须发送到 Convai 服务器。
6. 当提示时，点击 **覆盖**.

{% hint style="info" %}
如果添加相机装置后仍看不到您的 Convai 角色，请在层级视图中选中它，并手动更新 **Transform 位置** 数值，直到它在场景视图中正确显示。
{% endhint %}

***

### 第 4 步 — 启用视觉

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FOqOiyu9b2L2GNn575nIa%2FScreenshot%202026-04-28%20153013.png?alt=media&amp;token=443d7617-39d2-4251-b213-6a1d7cb33efe" alt=""><figcaption></figcaption></figure>

此步骤将 Meta Quest 透视相机连接到 Convai 角色，使其能够看到并响应用户周围的真实世界。

1. 选择 **Convai Manager** 在层级视图中。
2. 更改 **连接类型** 为 **视频**.
3. 当提示时，点击 **添加组件** 以添加 **Convai Vision Publisher** 和 **Camera Frame Source**。这些会作为 Convai Manager 下的子组件出现在层级视图中。
4. 默认情况下，Camera Frame Source 使用 Unity 相机。请将其替换为 **Quest Vision Frame Source**:
   * 将 **透视摄像头访问** 层级视图中的对象拖到帧源字段中。
5. 点击 **自动查找** 在 **Convai Vision Publisher**.
6. 在 **Camera Rig**中，找到 **Passthrough** 和 **Camera Access** 切换开关，并确保二者都已启用。

**工作原理：** Convai Vision Publisher 会将来自 Quest 相机的实时画面发送到 Convai 服务器。角色接收该画面后，可以实时描述、推理并响应物理对象和空间布局。

***

### 第 5 步 — 为混合现实设置聊天 UI

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fzf3Qfph4KwHSxFTz3r44%2FScreenshot%202026-04-28%20153056.png?alt=media&amp;token=c9140a71-b433-4410-b4fc-3c9af17a3a1f" alt=""><figcaption></figcaption></figure>

默认的 Convai 画布 UI 是为平面屏幕构建的。在 MR 场景中，需要将其转换为世界空间并缩小，以便在头显中自然地位于角色旁边。

1. 选中 **画布** 在层级视图中。
2. 更改 **渲染模式** 为 **世界空间**.
3. 将 **位置** 数值为 `0, 0, 0` 使其显示在玩家前方。
4. 如果 UI 不可见，请将其 **Alpha** 值设为 `1`.
5. 更改画布的 **缩放** 来自 `1` 为 `0.001` —— 这会使其在头显内达到可读大小。
6. 重新定位 **状态容器**, **Recording 预制件**，以及 **Settings 预制件** 到角色左侧。
7. 添加轻微倾斜，以匹配头显中的自然观看角度。
8. 在场景视图中微调位置数值，直到布局与角色并排时看起来合适。

{% hint style="info" %}
您也可以使用 Unity 画布组件和 Meta SDK 中的模块，以获得更集成的 UI。以上数值只是让默认 Convai UI 在头显中运行起来的快速基准。
{% endhint %}

***

### 第 6 步 — 构建并部署到 Meta Quest

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FiktoSLOasYmmSO2utRrf%2FScreenshot%202026-04-28%20153230.png?alt=media&amp;token=f0893302-8d9e-4d7e-8b76-355f91f45752" alt=""><figcaption></figcaption></figure>

1. 前往 **文件 > 构建配置文件**.
2. 点击 **打开场景列表** 并添加 **Lip Sync 场景**.
3. 点击 **构建**，选择目标文件夹，然后点击 **保存**.
4. 通过 USB 连接您的 Meta Quest 设备。
5. 构建好的应用会显示在 **未知来源** 中。请从那里启动它。

{% hint style="info" %}
添加一个 **平行光** 在构建前添加到场景中。现实世界的光照条件差异很大，平行光有助于让角色在不同环境下看起来一致
{% endhint %}

#### 测试视觉

进入头显后，通过询问角色它能看到什么来测试视觉连接：

* *“你看到我周围有什么？”*
* *“这个房间里有几把椅子？”*
* *“你能描述一下我桌上有什么吗？”*

角色将使用 Quest 透视相机画面实时描述物理环境。

### 组件参考

| 组件                          | 作用                                  |
| --------------------------- | ----------------------------------- |
| `Convai Vision Publisher`   | 将相机帧画面发送到 Convai 服务器进行处理            |
| `Quest Vision Frame Source` | Meta Quest 专用输入，将默认 Unity 相机替换为透视画面 |
| `透视摄像头访问`                   | Meta 构建块，授予应用访问 Quest 透视相机的权限       |
| `Camera Rig`                | Meta 构建块，在 XR 中替换标准 Unity 相机        |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/mixed-reality-ai-characters-with-vision-meta-quest.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.