Convai Unity SDK 架构

了解 Convai Unity SDK 的四层架构——运行时、房间、代理和模块——以及每一层的职责。

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

系统图

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

运行时层

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

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

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

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

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

房间层

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

它负责：

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

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

代理层

代理层包含你放置在场景 GameObject 上的组件。

ConvaiCharacter

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

• 角色 ID — 来自你的 Convai 仪表板的唯一 ID
• 会话状态 — 已断开, 连接中, 已连接, 正在重新连接, 正在断开连接, 错误
• 对话生命周期 — 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 相同 GameObject 上的可选 Unity 组件（例如 Vision）。每个模块都是独立的——只添加项目需要的部分。

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

对话流程 在 ConvaiCharacter 初始化时，会在运行时自动配置。所有其他模块—— LipSync, 情绪, 视觉, Narrative, 对话动画, 面部动画, 注视, 注意力，以及 实体化 ——都是按需启用的。

配置模型

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

内联

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

资源

值来自可复用的 ConvaiCharacterProfile 或 ConvaiRoomManagerProfile ScriptableObject。当你想在多个场景或预制体变体之间共享默认值，或者需要在不修改单个预制体的情况下切换角色行为时使用。

下一步

功能地图快速开始