Convai Unity SDK 架构

了解 Convai Unity SDK 的四层架构——Runtime、Room、Agent 和 Module——以及每一层的职责。

SDK 组织为四个层级：Runtime、Room、Agent 和 Module。作为开发者，你主要与 Agent 层（角色和玩家组件）以及 Module 层（按需启用的功能模块）交互。Runtime 和 Room 层以最少配置处理连接和服务引导。

系统图

虚线从 ConvaiCharacter 到模块层表示模块是可选组件，你将它们添加到与角色相同的 GameObject 上——基本对话不需要。

运行时层

运行时层在场景加载时启动，并为其下方的一切提供服务。

ConvaiSDK 是一个静态类，公开 SDK 版本（ConvaiSDK.Version）。你很少直接引用它。

ConvaiManager 是组合根。它是一个单例（ConvaiManager.ActiveManager）并标记为 [DefaultExecutionOrder(-1100)] ，因此它会在其他场景对象之前初始化。它拥有：

• 服务访问器 — TryGet 方法，覆盖所有内部服务（麦克风、音频、代理注册表、通知、设置面板等）
• 高层封装 — ConvaiManager.Audio, ConvaiManager.Transcripts, ConvaiManager.Events ，用于最常见的脚本任务
• 连接控制 — ConnectAsync(), DisconnectAsync(), SetConversationInputModeAsync()
• 代理引用 — Characters, 玩家, ActiveConversationCharacter

大多数集成代码只需要 ConvaiManager.ActiveManager 以及角色自身的事件。服务访问器 TryGet 适用于你替换或扩展内部服务的高级用例。

房间层

ConvaiRoomManager 负责与 Convai 的实时连接。每个场景一个，由 ConvaiRoomManager 管理 ConvaiManager.

它负责：

• 房间连接生命周期 —— 连接、断开、重新连接
• 麦克风采集 —— 启动和停止音频输入、静音控制
• 轮流发言模式 —— 免持（ConversationInputMode.HandsFree）或按住说话（ConversationInputMode.PushToTalk)
• 动态上下文传输 —— 在运行时向 Convai 发送状态更新和事件
• 音频播放协调 —— 启用远程角色音频、WebGL 用户手势处理

ConvaiRoomManager 提供用于诊断、音频、所有权和连接管理的协调器。这些可通过 ConvaiManager.ActiveManager.TryGetRoomConnectionService() 访问，用于高级脚本编写。

Agent 层

Agent 层包含你放在场景 GameObject 上的组件。

ConvaiCharacter

添加 ConvaiCharacter 添加到每个 NPC 或代理 GameObject 上。每个角色一个组件。它拥有：

• 角色 ID——来自你 Convai 仪表板的唯一 ID
• 会话状态—— 已断开, 连接中, 已连接, 重新连接中, Disconnecting, 错误
• 对话生命周期—— StartConversationAsync(), StopConversationAsync(), ToggleSpeech()
• 转录和事件回调—— OnTranscriptReceived, OnEmotionChanged, OnActionsReceived, OnSpeechStarted, OnSpeechStopped, OnCharacterReady
• 动作配置——通过 ConvaiActionConfigSource 组件

ConvaiCharacter 可在 Inspector 中直接内联配置，或通过可复用的 ConvaiCharacterProfile ScriptableObject 资源。

ConvaiPlayer

添加 ConvaiPlayer 添加到你的玩家 GameObject 上。每个场景一个是标准做法。它拥有：

• 用于转录归属的玩家显示名称和姓名标签颜色
• 文本消息发送—— SendTextMessage(string message)
• 运行时身份覆盖—— SetRuntimeDisplayName(string displayName)

ConvaiPlayer.PlayerId 是转录 UI 归属用的本地显示标识符。它不是用于长期记忆跟踪的服务器生成说话者 ID。

模块层

模块是你添加到与 ConvaiCharacter （或 ConvaiRoomManager （用于视觉）。每个模块彼此独立——只添加项目所需的部分。

模块	作用
LipSync	由音频播放驱动的实时 blend shape 口型动画；支持 ARKit、MetaHuman 和 CC4 Extended 映射
情绪	接收 Convai 情绪信号，对其进行平滑处理，并分发到 blend shape 或 Animator 参数绑定
视觉	将摄像头、网络摄像头或 Meta Quest 透视画面发布给 Convai，用于多模态感知
叙事	通过与对话流程相关联的基于触发器的事件管理故事章节推进
DialogueAnimation	在对话期间驱动四层 Animator 堆栈（基础待机、遮罩叠加、身体说话、头部说话）
FacialAnimation	在运行时播放面部动画剪辑，并与口型同步和情绪输出进行合成
凝视	将眼睛和头部执行器朝向对话伙伴和注意目标进行混合
Attention	解析加权焦点目标，为 Gaze 模块提供凝视方向
ConversationFlow	将对话事件流桥接到逐帧对话状态（空闲、说话、反应等）
Embodiment	用于物理存在和行为模块的基础行为配置文件与生命周期管理

ConversationFlow 在 ConvaiCharacter 初始化时会在运行时自动提供。所有其他模块—— LipSync, 情绪, 视觉, 叙事, DialogueAnimation, FacialAnimation, 凝视, Attention，以及 Embodiment ——均为按需启用。

配置模型

每个主要组件都支持两种配置模式，可在 Inspector 中选择。

内联

值直接在 Inspector 中设置于组件上。这是默认模式，适用于大多数场景——无需额外资源。

资源

下一步

功能地图快速入门