核心概念

了解 Convai Unreal Engine 插件的组件模型、每个组件的归属方式，以及它们在运行时如何协同工作。

Convai Unreal Engine 插件围绕一组较小的运行时类型构建，每种类型各自承担单一职责。了解每种类型的作用，以及它们之间如何关联，有助于你配置角色、处理事件，并为你的项目扩展插件。

先从 运行时架构 如果你刚接触插件内部结构。需要了解特定系统——会话管理、对话状态或 Blueprint 事件——时，再阅读其余页面。

运行时模型

大多数 Convai 在关卡中的交互都涉及一个聊天机器人组件和一个玩家组件。二者都继承自共享的抽象基类 UConvaiConversationComponent，这为它们提供了通用的对话事件接口。对象同步和面部同步行为使用不同的组件类型，而 UConvaiSubsystem 是一个 UGameInstanceSubsystem，而不是一个 Actor 组件。

运行时类型	Blueprint 显示名称	职责
UConvaiChatbotComponent	Convai 聊天机器人	表示一个由 AI 驱动的角色。拥有角色 ID、会话状态、情绪状态、环境数据以及动作队列。
UConvaiPlayerComponent	Convai Player	表示玩家侧参与者。拥有麦克风采集、音频流传输、按键通话状态以及注视注意力。
UConvaiObjectComponent	Convai 对象组件	注册场景中的对象或道具，使所有聊天机器人都能在动作和上下文中按名称引用它。
UConvaiFaceSyncComponent	Convai 面部同步	根据角色传入的音频驱动混合形状或口型素动画。
UConvaiSubsystem	Convai 子系统	游戏实例子系统。管理底层 WebRTC 连接、组件注册表和全局连接状态。

该子系统是单例——它会随游戏实例自动启动，并且始终可通过 Blueprint 的 获取 Game Instance → 获取 Subsystem（Convai Subsystem） 链。

各部分如何协同

聊天机器人组件和玩家组件不会在 Blueprint 中直接彼此通信。它们都依赖于子系统，而子系统拥有实际的传输层。当玩家说话时，音频会从 UConvaiPlayerComponent 通过子系统传到 Convai。角色的音频响应到达子系统后，会被转发到当前角色会话。

上图展示了运行时数据流。对象组件会在 BeginPlay 注册到子系统，这样每个聊天机器人都能在会话开始时发现它，而无需显式连线。

对话状态

一次对话依赖于聊天机器人会话以及玩家侧音频路径已初始化。该会话通过子系统建立 WebRTC 通道，并保持打开状态，直到 StopSession 被调用，或者游戏实例结束。

聊天机器人提供诸如以下的语音状态辅助函数： GetIsTalking, IsListening, IsProcessing （显示为 正在思考），以及 IsInConversation. GetIsTalking 是可靠的播放状态辅助函数；请参见 对话流程 了解其确切行为。

本节页面

运行时架构 每个组件与子系统之间的角色、归属关系以及相互关系。

会话生命周期 会话如何启动、停止并报告连接状态——以及子系统的 Blueprint 接口。

对话流程 监听、处理和说话状态；转写；以及打断。

事件系统 聊天机器人和玩家组件上所有可由 Blueprint 绑定的委托，按类别组织。