运行时架构
了解 Convai Chatbot、Player、Object、Face Sync 组件与 Convai Subsystem 之间的角色、所有权和关系。
Convai Unreal Engine 插件将职责分为五种不同类型:聊天机器人组件、玩家组件、对象组件、面部同步组件,以及游戏实例子系统。每种类型只负责系统中的一小部分;彼此之间没有重复职责。
组件层级
所有具备对话能力的组件都共享一个两层基础:
UConvaiAudioStreamer——最底层。它负责管理来自程序化声音波形的音频播放,并向任何实现了IConvaiLipSyncInterface的组件传递逐帧混合形状面部数据。它还提供一个视觉插槽(IConvaiVisionInterface)用于摄像头或渲染目标输入。这两个接口都是扩展点:IConvaiLipSyncInterface是UConvaiFaceSyncComponent(以及任何自定义口型同步驱动)接收面部数据的方式,而IConvaiVisionInterface是摄像头视频流或渲染目标组件向 AI 提供视觉上下文的方式。聊天机器人和玩家都从该类继承音频和面部能力。UConvaiConversationComponent——扩展自UConvaiAudioStreamer。它添加了共享的对话名称辅助函数(GetConversationalName)以及聊天机器人和玩家都继承的两个委托:OnTranscriptionReceivedDelegate和参与者连接状态变化事件.
Convai Chatbot 组件
UConvaiChatbotComponent (Blueprint 显示名称 Convai 聊天机器人)是面向 AI 驱动角色的核心组件。它负责:
身份。
CharacterID用于标识要加载的角色,而CharacterName保存已加载的角色名称。更广泛的角色配置管理不在本运行时架构页面中处理。会话。 该
bAutoInitializeSession标志位和StartSession/StopSession函数通过子系统管理 WebRTC 通道。详见 会话生命周期 了解详情。对话状态。 诸如
GetIsTalking,IsListening,IsProcessing,以及IsInConversation之类的只读状态函数会暴露当前的辅助函数集合。在当前 SDK 中,GetIsTalking反映音频播放;请参见 对话流程 了解每个辅助函数的确切行为。动作队列。 当 Convai 发送一系列动作时,它们会进入
动作队列为FConvaiResultAction条目中。Blueprint 通过调用获取第一个动作读取当前队首条目,执行该动作,然后调用处理动作完成。成功完成后会将当前动作出队,并推进队列。当某个动作发生无法恢复的失败时,请调用中止动作序列来清空队列。情感状态。
情绪状态(类型FConvaiEmotionState)会被复制。锁定情绪状态可防止传入更新覆盖手动设置的情感。环境。
EnvironmentData(类型FConvaiEnvironmentData)保存 AI 可引用的动作模板、对象和角色。请在运行时通过更细粒度的方法修改它AddObject,RemoveObject,AddCharacter,以及设置注意对象——而不是直接写入该属性。动作模板位于EnvironmentData.Actions在/connect创建时固定;只有对象和角色可以在会话中途更新。动态上下文。
UpdateContext,SetContextState,SetContextStates,AddContextEvent,以及ResetDynamicContext在实时会话期间将实时世界状态推送给 AI。更新会使用由ContextDebounceWindow和ContextMaxDebounceWindow.会话值重置。
SessionID默认为"-1",以及ResetConversation将其重置为"-1"。当前的 WebRTC 连接路径不提供SessionID作为恢复参数。注意目标。
ConversationPartner,注视目标,以及指向目标是已复制的属性,用于跟踪角色正在与哪位玩家交谈,以及它正在注视或指向什么。
聊天机器人组件还实现了 IConvaiConnectionInterface,子系统正是通过它将传入的音频、动作、情感数据和面部数据路由到正确的组件。
Convai Player 组件
UConvaiPlayerComponent (Blueprint 显示名称 Convai Player)代表对话中的人类一侧。它负责:
身份。
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 使设计者能够绑定 UPROPERTY 字段到拥有者 Actor 的 AI 上下文中。所有对象组件共享一个轮询时钟(大约每 0.25 秒一次)。每次轮询时,子系统都会评估每个被跟踪的属性,并推送一个 SetContextState 更新,仅在值发生变化时才发给已注册的聊天机器人——而不是每个 tick 都发。该组件不再自行生成针对每个聊天机器人的邻近描述;自从 4.0.0-beta.22,每个已注册对象的距离和方向——例如“附近、前方并偏右”——都由 空间感知 子系统集中计算,并连同其他上下文一起交付给每个聊天机器人。
该组件暴露四个凝视事件(OnGazedIn, OnGazedOut, OnAttentionGained, OnAttentionLost),这样 Blueprint 就可以独立于聊天机器人响应玩家焦点。
Convai 面部同步组件
UConvaiFaceSyncComponent (Blueprint 显示名称 Convai Face Sync)是一个 USceneComponent 实现了 IConvaiLipSyncInterface。它接收来自聊天机器人音频管线的预计算面部数据,并在每个 tick 驱动混合形状。
该 LipSyncMode 属性(EC_LipSyncMode)用于选择目标混合形状格式:
关闭
关闭
禁用口型同步
自动
自动
让插件选择
基于视素
基于音素口型
通用视素目标
BS_MHA
MetaHuman 混合变形
MetaHuman 骨骼绑定(默认)
BS_ARKit
ARKit 混合变形
兼容 ARKit 的骨骼绑定
BS_CC4_Extended
CC4 扩展混合变形
Reallusion CC4 骨骼绑定
面部同步组件是被动的——它不会发起任何网络活动。面部数据通过聊天机器人的音频流管线路由到实现 IConvaiLipSyncInterface的组件,而面部同步组件会在每个 tick 将得到的混合形状值暴露给角色的 Anim Blueprint。
若要从 Anim Blueprint 应用混合形状,请添加 Convai Face Sync AnimGraph 节点(FAnimNode_ConvaiFaceSync)到角色的动画图中。该节点接收一个 UConvaiChatbotComponent 引脚(默认显示),并在每个动画 tick 采样混合形状数据。它支持基于混合形状名称列表的上/下面部 alpha 控制,以及通过一个 BlendshapeMapping 表进行混合形状名称重映射、全局乘数和偏移,以及在最近没有面部数据到达时可配置的饥饿淡入/淡出。
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 委托详情时,请阅读事件页面。
最后更新于
这有帮助吗?