> 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/convai-unity-sdk/platform-guides/xr-headsets.md).

# XR 头显

查找在 XR 头显上部署 Convai Unity SDK 的指南，包括 Meta Quest 视觉透视设置和自定义 XR 帧源实现。

Convai Unity SDK 可在基于 Android 的 XR 头显（Meta Quest、Horizon OS、Android XR）和 Windows XR 头显上运行，核心功能无需额外配置。语音对话、口型同步、动作、情绪和长期记忆的表现与其他受支持的平台相同。只有视觉功能需要针对 XR 进行集成，而且仅当你希望 AI 角色通过头显摄像头观察现实世界时才需要。

{% embed url="<https://youtu.be/CGPAG_CWGJw>" %}
Meta Quest 的 Convai Unity VR 设置
{% endembed %}

### 核心功能支持

| 功能     | Android XR（Meta Quest、Horizon OS）            | Windows XR                     |
| ------ | -------------------------------------------- | ------------------------------ |
| 语音对话   | ✅ 完全支持                                       | ✅ 完全支持                         |
| 唇形同步   | ✅ 完全支持                                       | ✅ 完全支持                         |
| 操作     | ✅ 完全支持                                       | ✅ 完全支持                         |
| 情绪     | ✅ 完全支持                                       | ✅ 完全支持                         |
| 长期记忆   | ✅ 完全支持                                       | ✅ 完全支持                         |
| 叙事设计   | ✅ 完全支持                                       | ✅ 完全支持                         |
| 视觉（透视） | ✅ `QuestVisionFrameSource` （仅限 Quest 3 / 3S） | ⚠️ 自定义 `IVisionFrameSource` 必需 |
| 空间音频   | ✅ 完全支持                                       | ✅ 完全支持                         |

对于基于 Android 的 XR 头显，所有核心设置均遵循 Android 平台指南，包括 `RECORD_AUDIO` 清单声明和运行时权限流程。

{% content-ref url="/pages/a05c31e79a2f905396785b4f77b4554fc046528d" %}
[iOS 和 Android](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/ios-and-android.md)
{% endcontent-ref %}

### 在 Meta Quest 上使用按键通话

在 Meta Quest 上，按键通话通过 Unity 的 XR 输入 API 读取控制器的 A、B、X 和 Y 按钮，而不是键盘按键。如果无法读取当前 XR 控制器，或控制器在按住按钮时断开连接，SDK 会采取安全失败策略并停止麦克风采集，而不是让麦克风一直保持开启。键盘和非 XR 摇杆输入不受影响。完整的按键映射请参阅 [配置对话输入模式](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-conversation-input-mode.md) 。

视觉是唯一一个在不同 XR 平台上有所差异的功能。下方决策树说明了何时需要额外设置：

```mermaid
graph TD
    A[XR 部署] --> B{需要视觉功能？}
    B -->|否| C[按照 Android 或 Windows 指南设置权限]
    C --> D[完成 — 所有核心功能均可使用]
    B -->|是| E{Meta Quest 3 或 3S？}
    E -->|是| F[使用 QuestVisionFrameSource]
    F --> G[导入 Meta XR SDK + 声明清单权限]
    E -->|否 — 其他 XR 头显| H[实现自定义 IVisionFrameSource]
    H --> I[参阅下文“其他 XR 平台上的视觉功能”]
```

### Meta Quest 上的视觉功能

`QuestVisionFrameSource` 会将 Meta Quest 3 或 3S 头显的透视摄像头画面流式传输给 Convai，使 AI 角色能够观察并回应学习者所看到的现实世界。该组件通过反射在运行时绑定到 Meta XR SDK 的 `PassthroughCameraAccess` ；Convai SDK 在编译时不会硬性依赖任何 Meta SDK 软件包。

完整的设置指南、Inspector 参考和故障排除步骤，请参阅 Meta Quest 视觉设置页面。

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Meta Quest 视觉设置</strong><br>配置 QuestVisionFrameSource、声明所需的清单权限，并在 Quest 3 和 3S 上验证透视视觉功能。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/meta-quest-vision.md">Meta Quest Vision 设置</a></td></tr></tbody></table>

### 其他 XR 平台上的视觉功能

对于非 Meta XR 头显，不提供内置的帧源，包括仅支持 OpenXR 的设备、Windows Mixed Reality、HoloLens，以及无法通过 Meta XR SDK 提供透视摄像头画面的 Android XR 平台。

要在这些设备上启用视觉功能，请实现 `IVisionFrameSource` 并通过 XR SDK 的摄像头 API 提供帧：

{% code title="CustomXRVisionFrameSource.cs" %}

```csharp
using System;
using Convai.Runtime.Vision.Sources;
using UnityEngine;

public class CustomXRVisionFrameSource : MonoBehaviour, IVisionFrameSource
{
    [SerializeField] private float _targetFrameRate = 15f;
    [SerializeField] private string _sourceId = "custom-xr";

    private RenderTexture _renderTexture;

    public bool IsCapturing { get; private set; }
    public long FrameCount { get; private set; }
    public (int Width, int Height) FrameDimensions => (_renderTexture ? _renderTexture.width : 0,
                                                       _renderTexture ? _renderTexture.height : 0);
    public float TargetFrameRate => _targetFrameRate;
    public string SourceId => _sourceId;
    public RenderTexture CurrentRenderTexture => _renderTexture;
    public bool IsFrameReady { get; private set; }

    public event Action FrameReady;

    public void StartCapture()
    {
        // 在此处初始化 XR SDK 摄像机和 RenderTexture。
        // 每当有新帧可用时，将其传输到 _renderTexture（顶部朝下 / Y 轴翻转），
        // 然后递增 FrameCount，将 IsFrameReady 设为 true，并触发 FrameReady?.Invoke()。
        IsCapturing = true;
    }

    public void StopCapture()
    {
        IsCapturing = false;
        IsFrameReady = false;
    }
}
```

{% endcode %}

通过 Inspector 字段将自定义源 `ConvaiVisionPublisher` 指定给该字段。有关完整的 `IVisionFrameSource` 契约、发布策略和调试预览设置，请参阅 Vision 功能文档。

### 后续步骤

{% content-ref url="/pages/8f003ceeea888b21021a2b6aeef5efbbfe5a03cd" %}
[Meta Quest Vision 设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/meta-quest-vision.md)
{% endcontent-ref %}

{% content-ref url="/pages/a05c31e79a2f905396785b4f77b4554fc046528d" %}
[iOS 和 Android](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/ios-and-android.md)
{% endcontent-ref %}


---

# 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/convai-unity-sdk/platform-guides/xr-headsets.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.
