插件架构

了解 Convai Unreal Engine 插件的四个模块、运行时组件、会话代理和子系统路由模型。

Convai Unreal Engine 插件由四个模块、运行时组件、连接会话代理，以及 UConvaiSubsystem。每个模块都有明确的作用范围和加载阶段；每个组件都只有单一职责，并通过 Unreal 的组件和子系统模型进行通信。

模块

该插件在 ConvAI.uplugin.

模块	类型	平台	用途
Convai	运行时	Win64、Android	核心对话流水线：WebRTC 会话管理、音频流传输、聊天机器人和玩家组件、子系统、动态上下文、环境、动作、视觉。
ConvaiEditor	编辑器	全部（仅编辑器构建）	仅供编辑器使用的工具。编辑器内的配置窗口、API 密钥设置界面以及角色仪表板浏览器需要 UE 5.2 或更高版本；诸如以下内容的 Blueprint 图工具： 创建 Convai 动作处理器 右键菜单项是编辑器功能。
ConvaiAnimGraph	UncookedOnly	全部	从 Convai 组件读取实时 blendshape 值并将其应用到 Animation Blueprint 中的动画图节点。
ConvaiVisionBase	运行时	Win64、Android	视觉功能的基础层：帧捕获和图像编码。 Convai 运行时通过活动会话路径发送捕获的帧。

该 Convai 模块在 PreDefault 阶段加载，因此在游戏玩法系统初始化之前即可用。 ConvaiEditor 在 PostEngineInit 时加载，以便能够访问完全初始化的编辑器环境。

系统图

下图显示了单个玩家-角色对话轮次的运行时流程。

UConvaiSubsystem 它拥有底层 Convai 客户端，并为当前活动的玩家和角色会话代理路由数据。运行时组件会向子系统注册，以便其将音频、响应数据、对象更新和上下文刷新路由到正确的组件。

运行时组件

本页所述架构由四个主要对话组件构成，并像原生 Unreal 组件一样附加到 Actor 上。其他可由 Blueprint 生成的辅助组件支持音频捕获、视觉和诊断工作流。另一个独立的运行时部分， UConvaiSubsystem，是一个 UGameInstanceSubsystem 由 Unreal 自动创建，而不是你手动添加的组件。

每个组件的 显示名称 是显示在 添加组件 Unreal 编辑器中的面板标签。将组件添加到 Blueprint Actor 时，可使用显示名称查找每个组件。Convai Subsystem 不是通过这种方式添加的——引擎会为每个游戏实例自动创建一个。

UConvaiChatbotComponent （显示名称：Convai Chatbot）

AI 角色的核心组件。它保存角色 ID、会话状态、环境契约（动作、对象、场景角色）、动态上下文、情绪状态以及动作队列。每个 AI 角色 Actor 对应一个实例。

UConvaiChatbotComponent 为其角色持有一个连接会话代理。当会话开始时，该组件会将代理注册到 UConvaiSubsystem，由其通过底层 Convai 客户端路由音频和响应数据。聊天机器人接收音频、面部动画数据和动作序列，然后协调音频播放、口型同步处理以及 Blueprint 动作处理器。

UConvaiPlayerComponent （显示名称：Convai Player）

表示对话中的人类玩家。它通过 UConvaiAudioCaptureComponent捕获麦克风音频，将其流式传输到当前活动的聊天机器人会话，并驱动凝视注意力系统，用于跟踪哪些 UConvaiObjectComponent Actor 位于玩家准星下。

UConvaiObjectComponent （显示名称：Convai Object Component）

将一个 Actor 标记为聊天机器人可在其环境契约中引用的场景对象。当该组件注册到 UConvaiSubsystem时，子系统会在共享时钟上轮询其跟踪的属性，并将变更合并为批量的动态上下文更新。多个聊天机器人可以共享同一个对象组件。

UConvaiFaceSyncComponent （显示名称：Convai Face Sync）

将预先计算的面部动画序列应用到骨骼网格体的场景组件。聊天机器人/音频流传输器路径会将面部数据转发到当前活动的口型同步接口，通常是 UConvaiFaceSyncComponent。该组件会对 blendshape 帧进行插值，并公开其结果 TMap<FName, float> 通过 ConvaiAnimGraph 中的 AnimGraph 节点向 Animation Blueprint 提供 关闭, Auto, 基于 Viseme, MetaHuman Blendshapes, ARKit Blendshapes，以及 CC4 Extended Blendshapes 模式。

UConvaiSubsystem （显示名称：Convai Subsystem）

A UGameInstanceSubsystem 充当共享连接管理器和组件注册表的子系统。它维护底层 Convai 客户端，将音频和数据包路由到正确的会话代理，并跟踪路由所需的已注册运行时组件。

插件依赖项

插件在 ConvAI.uplugin:

插件	已启用	角色
AudioCapture	是	麦克风输入流水线
AndroidPermission	是	Android 上的运行时麦克风权限请求
EditorScriptingUtilities	是	供 ConvaiEditor （仅编辑器）
PropertyAccessEditor	是	供 ConvaiEditor （仅编辑器）

下一步

了解模块和组件模型后，请安装插件或浏览完整功能集。

快速开始功能地图什么是 Convai Unreal Engine 插件