运行时架构

了解 Convai Chatbot、Player、Object、Face Sync 组件与 Convai Subsystem 之间的角色、归属和关系。

Convai Unreal Engine 插件将职责划分为五种不同类型：聊天机器人组件、玩家组件、对象组件、面部同步组件和游戏实例子系统。每种类型只负责系统中的一小部分；没有一种会重复另一种的职责。

组件层级

所有具备对话能力的组件都共享一个两层基类：

• UConvaiAudioStreamer ——最底层。它管理来自程序化声音波形的音频播放，并将每帧的 blendshape 面部数据传递给任何实现 IConvaiLipSyncInterface。它还提供一个视觉槽位（IConvaiVisionInterface）用于摄像头或渲染目标输入。两个接口都是扩展点： IConvaiLipSyncInterface 是……如何 UConvaiFaceSyncComponent （以及任何自定义口型同步驱动）接收面部数据，且 IConvaiVisionInterface 是摄像头画面或渲染目标组件向 AI 提供视觉上下文的方式。聊天机器人和玩家都从该类继承音频和面部能力。
• UConvaiConversationComponent ——扩展 UConvaiAudioStreamer。它增加了共享的对话名称辅助函数（GetConversationalName）以及聊天机器人和玩家共同继承的两个委托： OnTranscriptionReceivedDelegate 是位于 OnAttendeeConnectionStateChangedEvent.

Convai 聊天机器人组件

UConvaiChatbotComponent （Blueprint 显示名称 Convai 聊天机器人）是 AI 驱动角色的核心组件。它负责：

• 身份。 CharacterID 用于标识要加载的角色，而 CharacterName 存储已加载的角色名称。更广泛的角色配置在本运行时架构页面之外进行管理。
• 会话。 该 bAutoInitializeSession 标志和 StartSession / StopSession 函数通过子系统管理 WebRTC 通道。详情请参见 会话生命周期 。
• 对话状态。 只读状态函数，例如 GetIsTalking, IsListening, IsProcessing，以及 IsInConversation ，公开了当前的辅助功能表面。在当前 SDK 中， GetIsTalking 反映的是音频播放；请参见 对话流程 以了解每个辅助函数的确切行为。
• 动作队列。 当 Convai 发送一系列动作时，它们会进入 ActionsQueue 作为 FConvaiResultAction 条目。Blueprint 通过调用 FetchFirstAction来读取当前队首条目，执行该动作，然后调用 HandleActionCompletion。成功完成后会将当前动作出队并推进队列。若某个动作发生不可恢复的失败，请调用 AbortActionSequence 来清空队列。
• 情绪状态。 EmotionState （类型 FConvaiEmotionState）会被复制。 LockEmotionState 可防止传入更新覆盖手动设置的情绪。
• 环境。 EnvironmentData （类型 FConvaiEnvironmentData）保存 AI 可引用的动作模板、对象和角色。可在运行时通过细粒度方法修改它： AddObject, RemoveObject, AddCharacter，以及 SetObjectInAttention ——而不是直接写入该属性。 EnvironmentData.Actions 中的动作模板在 /connect 时固定；只有对象和角色可以在会话中途更新。
• 动态上下文。 UpdateContext, SetContextState, SetContextStates, AddContextEvent，以及 ResetDynamicContext 在实时会话中将实时世界状态推送给 AI。更新会通过由 ContextDebounceWindow 是位于 ContextMaxDebounceWindow.
• 会话值重置。 SessionID 默认为 "-1"，以及 ResetConversation 将其重置为 "-1"。当前 WebRTC 连接路径未将其作为恢复参数公开。 SessionID 作为恢复参数。
• 注意力目标定位。 ConversationPartner, LookAtTarget，以及 PointAtTarget 这些都是复制属性，用于跟踪角色正在与哪个玩家对话，以及它正在看向或指向什么。

聊天机器人组件还实现了 IConvaiConnectionInterface，这是子系统将传入音频、动作、情绪数据和面部数据路由到正确组件的方式。

Convai 玩家组件

UConvaiPlayerComponent （Blueprint 显示名称 Convai 玩家）代表对话中的人类一侧。它负责：

• 身份。 PlayerName 通过 SetPlayerName 及其服务器 RPC 对应项进行复制。 EndUserID 是位于 EndUserMetadata 具有 setter 函数和服务器 RPC 对应项，但在当前 SDK 构建中未注册为复制。
• 会话。 同样的 bAutoInitializeSession, StartSession, StopSession，以及 IsPlayerConnected 与聊天机器人相同的接口，但用于玩家端的 WebRTC 通道。
• 麦克风。 UnmuteStreamingAudio / MuteStreamingAudio 控制实时流式传输。 StartRecording / FinishRecording 将完整语句捕获为 USoundWave。可通过以下方式选择设备： SetCaptureDeviceByIndex, SetCaptureDeviceByName，以及相关查询函数。
• 注视注意力。 当 bEnableGazeAttention 为 true时，组件会在每个 tick 从玩家摄像机进行射线追踪。对 UConvaiObjectComponent 的持续注视会通过对象组件转发给符合条件的已注册聊天机器人，而每个聊天机器人都可以将其接受为当前注意对象。
• 按住说话和 VAD。 bMute 会使麦克风提交静音。 UpdateVadBP 用于切换语音活动检测。

玩家组件实现了两个接口： IConvaiConnectionInterface （与聊天机器人相同——由子系统用于会话路由和事件分发）以及 IConvaiProcessedAudioReceiver。音频处理中的中间件实现 IConvaiAudioProcessingInterface；玩家组件是处理后音频的接收器，在处理后的帧被转发给子系统之前接收它们。

Convai 对象组件

UConvaiObjectComponent 会将关卡中的任何 Actor 注册为所有聊天机器人都可以引用的命名对象。把它放在门、拉杆、房间或道具上，并填写 ObjectEntry （名称和描述）。该组件会在 BeginPlay时向子系统注册自己。之后启动会话的每个聊天机器人都会自动在其环境中获得该对象；已连接的聊天机器人会通过 AddOrUpdateObjectFromComponent.

可选地， TrackedProperties 允许设计师将拥有者 Actor 上的 UPROPERTY 字段绑定到 AI 上下文。所有对象组件共享一个轮询时钟（大约每 0.25 秒）。每次轮询时，子系统都会评估每个被跟踪的属性，并仅在值发生变化时将一个 SetContextState 更新推送给已注册的聊天机器人，而不是在每个 tick 都推送。启用 bAutoGenerateProximityState （默认）时，组件还会为每个聊天机器人合成一段接近度描述——例如“附近、前方偏右”——并将其作为状态键维护，在聊天机器人或对象移动时更新。

该组件公开四个注视事件（OnGazedIn, OnGazedOut, OnAttentionGained, OnAttentionLost），这样 Blueprint 就能独立于聊天机器人响应玩家的关注。

Convai 面部同步组件

UConvaiFaceSyncComponent （Blueprint 显示名称 Convai 面部同步）是一个 USceneComponent ，实现了 IConvaiLipSyncInterfaceIConvaiLipSyncInterface

该 LipSyncMode 属性（EC_LipSyncMode）选择目标 blendshape 格式：

值	显示名称	用于
关闭	关闭	禁用口型同步
Auto	Auto	让插件选择
VisemeBased	基于 Viseme	通用 viseme 目标
BS_MHA	MetaHuman Blendshapes	MetaHuman 绑定（默认）
BS_ARKit	ARKit Blendshapes	兼容 ARKit 的绑定
BS_CC4_Extended	CC4 Extended Blendshapes	Reallusion CC4 绑定

面部同步组件是被动的——它不会发起任何网络活动。面部数据通过聊天机器人的音频流管线路由到实现 IConvaiLipSyncInterface的组件，而面部同步组件会在每个 tick 将生成的 blendshape 值暴露给角色的 Anim Blueprint。

要从 Anim Blueprint 应用 blendshape，请添加 Convai 面部同步 AnimGraph 节点（FAnimNode_ConvaiFaceSync）到角色的动画图中。该节点带有一个 UConvaiChatbotComponent 引脚（默认显示），并在每次动画 tick 时采样 blendshape 数据。它支持基于 blendshape 名称列表的上/下半脸 alpha 控制，以及通过 BlendshapeMapping 表进行 blendshape 名称重映射、全局乘数和偏移，以及在近期没有面部数据到达时可配置的数据饥饿混入/混出。

Convai 子系统

UConvaiSubsystem 是一个 UGameInstanceSubsystem ——它随游戏实例启动和停止。它是插件的 Unreal 层与底层 WebRTC 传输（convai::ConvaiClient).

该子系统负责：

• 连接管理。 ConnectSession 是位于 DisconnectSession 由组件会话代理调用；无需 Blueprint 交互。
• 组件注册表。 子系统维护已注册的聊天机器人、玩家和对象组件列表，以便将运行时数据转发到当前会话及相关组件回调。
• 跟踪属性轮询。 子系统运行一个共享轮询时钟（大约每 0.25 秒一次），用于评估所有已注册的 UConvaiObjectComponent 跟踪属性同步更新。只有当值发生变化时，才会将其推送给已注册的聊天机器人，从而避免不必要的上下文流量。
• 全局连接状态。 GetServerConnectionState 返回当前的 EC_ConnectionState 值。该枚举包括 已断开, 连接中, 已连接，以及 重新连接中，但当前运行时路径驱动 已断开, 连接中，以及 已连接. OnServerConnectionStateChangedEvent 在驱动状态发生变化时触发。
• 空闲管理。 ResetIdleTimer 是位于 InvalidateOrphanedConnection 当子系统检测到空闲或失效连接时，可让 Blueprint 介入。 OnUserIdleWarning 会在空闲超时到期前触发，为游戏提供阻止断开的机会。

子系统完整的 Blueprint 接口在 会话生命周期.

所有权与生命周期

组件	拥有者	生命周期
UConvaiChatbotComponent	NPC Actor	与 Actor 相同
UConvaiPlayerComponent	玩家 Actor （Pawn 或 Controller）	与 Actor 相同
UConvaiObjectComponent	场景中的任意对象 Actor	与 Actor 相同
UConvaiFaceSyncComponent	NPC Actor （与聊天机器人组件一起）	与 Actor 相同
UConvaiSubsystem	该 UGameInstance	整个游戏会话

聊天机器人、玩家和对象组件在 BeginPlay 中向子系统注册，并在 EndPlay中注销，因此在游戏中途被销毁的组件（例如被击杀的角色）会从子系统注册表中干净地移除自己。面部同步组件附加到角色上，但不会向子系统注册。

相关概念

当你需要控制连接时序时，请接着阅读生命周期页面；当你需要回合级行为时，请阅读流程页面；当你需要 Blueprint 委托细节时，请阅读事件页面。

会话生命周期对话流程事件系统