> 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 头显

Convai Unity SDK 可在基于 Android 的 XR 头显（Meta Quest、Horizon OS、Android XR）和 Windows XR 头显上运行，核心功能无需额外配置。语音对话、唇形同步、动作、情绪和长期记忆的工作方式与其他任何受支持的平台相同。视觉是唯一需要 XR 特定集成工作的功能——而且只有在你希望 AI 角色通过头显摄像头看到现实世界时才需要。

### 核心功能支持

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

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

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

视觉是唯一会在不同 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 + 声明 manifest 权限]
    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，声明所需的 manifest 权限，并在 Quest 3 和 3S 上验证透视视觉。</td><td><a href="/pages/8f003ceeea888b21021a2b6aeef5efbbfe5a03cd">/pages/8f003ceeea888b21021a2b6aeef5efbbfe5a03cd</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。
        // 每当有新帧可用时，将其 blit 到 _renderTexture 中（自上而下 / Y 翻转），
        // 然后递增 FrameCount，将 IsFrameReady 设为 true，并触发 FrameReady?.Invoke()。
        IsCapturing = true;
    }

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

{% endcode %}

将你的自定义源分配给 `ConvaiVisionPublisher` ，通过其 Inspector 字段。完整的 `IVisionFrameSource` 契约、发布政策和调试预览设置，请参阅视觉功能文档。

### 下一步

{% content-ref url="/pages/8f003ceeea888b21021a2b6aeef5efbbfe5a03cd" %}
[Meta Quest Vision 设置](/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](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/xr-headsets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.