视觉

让 Convai 角色能够实时感知并响应您的 Unity 场景。概述 Vision 功能、其组件以及平台支持。

面向 Convai 角色的实时场景视觉

Vision 让 Convai 角色能够看到 Unity 场景中正在发生的事情。启用 Vision 时，会从一个可配置的来源持续捕获视频流——场景摄像机、物理网络摄像头，或 Meta Quest 头显的穿透画面——并将其发布到 Convai，在那里与角色的对话上下文一起处理。随后，角色可以根据它们观察到的内容作出回应、描述物体、标记危险，或基于实时视觉输入引导用户。

Vision 是一种模块级功能，依赖于 ConvaiRoomManager 运行于 视频 连接模式。在原生平台上，视频流来源于 RenderTexture；在 WebGL 中，它通过以下方式从可见的浏览器画布获取： canvas.captureStream().

Vision 如何融入 SDK

在 WebGL 中， ConvaiVisionPublisher 会完全绕过帧源，直接发布浏览器画布。其余管线保持不变。

关键概念

概念	含义
帧源	一个 MonoBehaviour 用于捕获帧并将其作为 Y 轴翻转的 RenderTexture。三个内置实现覆盖摄像头、网络摄像头和 Meta Quest 穿透。
发布策略	控制向后端流式传输时使用的客户端帧率和比特率。不控制后端使用哪个 AI 模型或提供方。
视频轨道	发布到当前 Convai 房间的 WebRTC 视频轨道。由 视频轨道名称 字段标识（默认 "unity-scene").
房间连接	Vision 仅在 ConvaiRoomManager 已使用以下方式连接时才会发布： 连接类型 设为 视频。仅音频连接不承载视频。

各项放在哪里

了解哪个组件应放置在哪个位置，可以避免最常见的配置错误。

组件	放置位置	说明
ConvaiRoomManager	任何持久化场景 GameObject	连接类型 都必须设置为 视频
ConvaiVisionPublisher	任何持久化场景 GameObject	通常放在 NPC 根对象上或其附近
CameraVisionFrameSource	与发布器相同的 GameObject 或其子对象	每个捕获源一个
WebcamVisionFrameSource	与发布器相同的 GameObject 或其子对象	每个捕获源一个
QuestVisionFrameSource	与发布器相同的 GameObject 或其子对象	仅限 Meta Quest；需要 Meta XR SDK
VisionDebugPreview	任何场景 GameObject	仅限编辑器；在播放器构建中自动禁用

前提条件

Vision 需要 ConvaiRoomManager.Connection Type 被设置为 视频。如果它设置为 音频，即使其他所有组件都已正确配置，发布器也会保持空闲。

平台行为

平台	支持的帧源	说明
PC / Mac / 主机	CameraVisionFrameSource, WebcamVisionFrameSource	完整的 RenderTexture 管线
Android / iOS	CameraVisionFrameSource, WebcamVisionFrameSource	网络摄像头源会在启动时请求相机权限
WebGL	（画布，自动）	canvas.captureStream() 路径——无需帧源组件；帧率上限为 15 fps
Meta Quest	QuestVisionFrameSource	需要 Meta XR SDK；绑定到 PassthroughCameraAccess 通过反射

本节内容

快速开始

通过分步 Inspector 演示，让角色接收实时摄像头画面——无需编写代码。

帧源

为每个平台和使用场景配置 CameraVisionFrameSource、WebcamVisionFrameSource 和 QuestVisionFrameSource。

发布与策略

选择发布策略，调整帧率和比特率，并控制视频轨道生命周期。

调试预览

将当前活动帧源可视化为屏幕叠加层，并在编辑器中监控捕获状态。

使用示例

用于安全培训、设备上手、VR 演示和手动触发会话的端到端示例。

高级主题

脚本 API、自定义 IVisionFrameSource、领域事件、WebGL 深入解析以及平台兼容性矩阵。

故障排查与诊断

借助结构化检查清单和决策树，诊断发布失败、空白画面、权限错误和平台特定问题。

结论

Vision 将你的 Unity 场景直接连接到角色的感知能力，使其能够基于角色所见做出回应。先从快速入门开始，获取来自场景摄像机的可用流，然后使用帧源为你的平台和使用场景选择合适的捕获方式。