> 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 头显上运行，核心功能无需额外配置。语音对话、唇形同步、动作、情绪和长期记忆的工作方式与其他任何受支持的平台相同。Vision 是唯一需要进行 XR 特定集成工作的功能——而且只有在你希望 AI 角色通过头显摄像头看到现实世界时才需要。 {% embed url="" %} Meta Quest 的 Convai Unity VR 设置 {% endembed %} ### 核心功能支持 | 功能 | Android XR（Meta Quest、Horizon OS） | Windows XR | | ---------- | -------------------------------------------- | ------------------------------ | | 语音对话 | ✅ 完整 | ✅ 完整 | | 口型同步 | ✅ 完整 | ✅ 完整 | | 动作 | ✅ 完整 | ✅ 完整 | | 情绪 | ✅ 完整 | ✅ 完整 | | 长期记忆 | ✅ 完整 | ✅ 完整 | | 叙事设计 | ✅ 完整 | ✅ 完整 | | Vision（透视） | ✅ `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 %} ### Meta Quest 上的按键通话 在 Meta Quest 上，按键通话通过 Unity 的 XR 输入 API 读取手柄的 A、B、X 和 Y 按钮，而不是键盘按键。如果当前活动的 XR 控制器无法读取，或在按下过程中断开连接，SDK 会采用故障关闭策略并停止麦克风采集，而不会保持麦克风开启。键盘和非 XR 摇杆输入不受影响。请参见 [配置对话输入模式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-conversation-input-mode.md) 完整按键映射。 Vision 是 XR 平台之间唯一会变化的功能。下面的决策树显示何时需要额外设置： ```mermaid graph TD A[XR 部署] --> B{需要 Vision 吗？} 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 平台上的 Vision] ``` ### Meta Quest 上的 Vision `QuestVisionFrameSource` 会将 Meta Quest 3 或 3S 头显的透视摄像头画面流式传输到 Convai，使 AI 角色能够看到并响应学习者所看到的现实世界。该组件使用反射在运行时绑定到 Meta XR SDK 的 `PassthroughCameraAccess` 在运行时——Convai SDK 对任何 Meta SDK 包都没有硬性的编译时依赖。 完整的设置指南、Inspector 参考和故障排除步骤，请参见 Meta Quest Vision 设置页面。
Meta Quest 视觉设置
配置 QuestVisionFrameSource，声明所需的 manifest 权限，并在 Quest 3 和 3S 上验证透视 Vision。		Meta Quest Vision 设置
### 其他 XR 平台上的 Vision 对于非 Meta 的 XR 头显——仅支持 OpenXR 的设备、Windows Mixed Reality、HoloLens，或未通过 Meta XR SDK 暴露透视摄像头的 Android XR 平台——没有内置的帧源。 要在这些设备上启用 Vision，请实现 `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 字段。有关完整内容，请参阅 Vision 功能文档 `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 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=&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.