Convai Chatbot 组件

AI 角色组件参考——Convai Chatbot Component 暴露的每个 Blueprint 可见属性、函数和事件。

UConvaiChatbotComponent （蓝图显示名称 Convai 聊天机器人）是添加到 AI 角色 Actor的主要组件。它管理角色与 Convai 的会话，接收音频和面部数据，分发动作和情绪更新，并提供用于对话和环境控制的完整蓝图 API。

将其添加到任何 Actor ，通过 添加组件 按钮在 详情 面板中。

身份和角色数据

这些属性用于标识角色以及加载的运行时名称。

属性	类型	访问	类别	说明
CharacterID	FString	EditAnywhere, Replicated	Convai	来自 Convai 控制台的角色 ID。通过蓝图设置器设置它会调用 LoadCharacter，后者会获取角色详情并触发 OnCharacterDataLoadEvent_V2.
CharacterName	FString	BlueprintReadOnly, Replicated	Convai	从 Convai 获取的角色名称。在 OnCharacterDataLoadEvent_V2 触发后填充。

会话

属性 / 函数	类型	默认	类别	说明
bAutoInitializeSession	bool	true	Convai|Session	当 true时，自动调用 StartSession ，在 BeginPlay.
bAutoFillConversationPartnerFromPlayer	bool	true	Convai|Session	当 true, StartSession 会从第一个已注册的 ConversationPartner 填充 UConvaiPlayerComponent。设置为 false 当你显式分配 ConversationPartner 时。
SessionID	FString	"-1"	Convai	对话记忆令牌。 "-1" 表示没有先前对话。请持久化此值以恢复会话。 ResetConversation 会将其重置为 "-1"。已复制。

会话函数

函数	类别	说明
StartSession	Convai|Session	打开到 Convai 的 WebRTC 通道。连接前会调用 GatherEnvironmentExtras 。角色详情会在 BeginPlay 时由 CharacterID 加载，或者在 LoadCharacter 时由 CharacterID 变化时由
StopSession	Convai|Session	关闭通道。再次调用 StartSession 会重新打开它。
ResetConversation	Convai	重置 SessionID 为 "-1"，清除对话记忆。不会停止会话。
GatherEnvironmentExtras （蓝图原生事件）	Convai|Session	在蓝图中重写，以便在 /connect之前附加额外的动作、对象或角色。输出引脚： OutExtraActions (TArray<FConvaiAction>), OutExtraObjects (TArray<FConvaiObjectEntry>), OutExtraCharacters (TArray<FConvaiObjectEntry>)。详情面板中的默认值仍会发送——此钩子只是在其基础上追加，不会替换它们。

参见 会话生命周期 以了解连接状态以及会话开始/停止行为。

长期记忆（LTM）

属性	类型	访问	类别	说明
EndUserID	FString	BlueprintReadWrite, EditAnywhere	Convai	用于长期记忆的终端用户身份令牌。在连接时发送给 Convai。
EndUserMetadata	FString	BlueprintReadWrite, EditAnywhere	Convai	包含用于 LTM 的附加用户元数据的 JSON 字符串。

参见 LTM 蓝图引用 以查看 LTM 专用节点。

对话状态查询

这些是 BlueprintPure 函数，可随时调用以读取角色状态。

函数	返回	类别	说明
IsInConversation	bool	Convai	返回 true 时由 IsProcessing(), IsListening()，或 GetIsTalking() 是 true。在当前插件源码中，这会简化为 GetIsTalking() ，只是因为另外两个查询目前还是占位实现。
IsProcessing （显示名称 正在思考)	bool	Convai	预期在返回 true 时表示角色正在等待来自 Convai 的完整回复。 当前源码： 始终返回 false （等待会话代理接线的占位实现）。
IsListening	bool	Convai	预期在返回 true 时表示角色正在接收玩家音频。 当前源码： 始终返回 false （占位实现）。
GetIsTalking （显示名称 正在说话)	bool	Convai	true 时表示角色正在播放其语音音频。
GetChatbotConnectionState	EC_ConnectionState	Convai|Connection	当前 WebRTC 通道状态： 已断开连接, 连接中, 已连接，或 重新连接中.

语音与说话

属性	类型	默认	类别	说明
InterruptVoiceFadeOutDuration	float	1.0	Convai	当被打断时，角色音频淡出到静音所需的秒数。

函数	返回	类别	说明
GetTalkingTimeElapsed	float	Convai|Voice	BlueprintPure。自当前轮次中角色开始说话以来经过的秒数。
GetTalkingTimeRemaining	float	Convai|Voice	BlueprintPure。当前轮次预计剩余的音频时长。

函数	输入	类别	说明
InterruptSpeech	InVoiceFadeOutDuration (float)	Convai	将调用该函数的组件上角色当前的音频播放淡出并停止。

口型同步

这些函数继承自 UConvaiAudioStreamer ，并可在蓝图中的聊天机器人组件上访问。

函数	返回	类别	说明
SetLipSyncComponent(LipSyncComponent)	bool	Convai|LipSync	附加一个实现了 IConvaiLipSyncInterface的口型同步组件。若组件未实现该接口，则返回 false 。
SupportsLipSync()	bool	Convai|LipSync	BlueprintPure. true 在附加了口型同步组件时返回
GetLipSyncMode()	EC_LipSyncMode	Convai|LipSync	BlueprintPure。返回由附加组件设置的口型同步模式。
HasPlayableFaceFrames()	bool	Convai|LipSync	BlueprintPure. true 当口型同步系统已有可应用的缓冲帧时返回
GetFacialData()	TArray<float>	Convai|LipSync	BlueprintPure。将当前混合形状分数作为扁平 float 数组返回。
GetFacialDataNames()	TArray<FString>	Convai|LipSync	BlueprintPure。按与 GetFacialData.
ConvaiGetFaceBlendshapes()	TMap<FName, float>	Convai|LipSync	BlueprintPure。返回当前混合形状的名称到分数映射。
GeneratesFacialDataAsBlendshapes()	bool	Convai|LipSync	BlueprintPure. true 当输出为混合形状格式（而不是 viseme 索引）时返回

Face Sync 组件参考

视觉

函数	返回	类别	说明
SetVisionComponent(VisionComponent)	bool	Convai|Vision	附加一个实现了 IConvaiVisionInterface的口型同步组件。若组件未实现该接口，则返回 false 。
SupportsVision()	bool	Convai|Vision	BlueprintPure. true 在附加了视觉组件时返回

音频播放计时

这些 BlueprintPure 函数暴露了角色音频管线的计时信息，对于将字幕、动画或 UI 元素与角色语音同步很有用。

函数	返回	类别	说明
GetAudioPlaybackTime()	double	Convai|Audio	自当前说话轮次开始以来经过的秒数。使用字节消耗跟踪和墙钟时间，返回较小者。
GetRemainingContentDuration()	double	Convai|Audio	当前已缓冲或正在播放内容的预计剩余音频时长（秒）。

叙事设计触发器

函数	输入	类别	说明
InvokeNarrativeDesignTrigger （显示名称 调用叙事设计触发器)	TriggerName (FString), InGenerateActions (bool), InReplicateOnNetwork (bool)	Convai	激活在 Convai 控制台中配置的叙事设计图中的一个命名触发器。
ExecuteNarrativeTrigger （显示名称 调用语音)	TriggerMessage (FString), InGenerateActions (bool), InReplicateOnNetwork (bool)	Convai	向角色发送任意触发消息，使其像接收到该输入一样作出响应。

参见 叙事设计蓝图引用 以查看完整的叙事功能面。

叙事设计模板键

属性	类型	访问	类别	说明
NarrativeTemplateKeys	TMap<FString, FString>	BlueprintReadWrite, EditAnywhere	Convai|NarrativeDesign	在运行时替换到叙事模板占位符中的键值对。通过蓝图设置器设置会调用 UpdateNarrativeTemplateKeys.

上下文（静态和动态）

属性	类型	访问	类别	说明
DynamicEnvironmentInfo	FString	BlueprintReadWrite, EditAnywhere	Convai	在连接时注入的自由文本上下文。适用于角色在会话开始时需要了解的静态事实（库存、玩家生命值、一天中的时间）。通过蓝图设置器设置会调用 UpdateDynamicEnvironmentInfo.

对于角色可在会话中途响应的运行时上下文更新，请使用下面的动态上下文函数。

动态上下文函数

这些函数可在不重启会话的情况下更新角色的运行时上下文。位于 ContextDebounceWindow 内的更新会合并为一次发送。

函数	输入	类别	说明
UpdateContext	Text (FString), Mode (EC_ContextUpdateMode), ShouldRespond (EC_RunLLMOption)	Convai	使用追加、替换或重置模式发送上下文更新。
SetContextState （显示名称 设置上下文状态)	Name (FString), Value (FString), ShouldRespond (EC_RunLLMOption), bFlushImmediately (bool)	Convai|DynamicContext	设置或替换单个命名状态属性（例如 “Health” → "80").
SetContextStates （显示名称 设置上下文状态)	States (TMap<FString,FString>), ShouldRespond (EC_RunLLMOption), bFlushImmediately (bool)	Convai|DynamicContext	一次调用设置多个状态属性。
AddContextEvent （显示名称 添加上下文事件)	Text (FString), ShouldRespond (EC_RunLLMOption), bFlushImmediately (bool)	Convai|DynamicContext	附加一个按时间顺序排列的事件（例如 “玩家走近商人”).
RemoveContextState （显示名称 移除上下文状态)	Name (FString), bFlushImmediately (bool)	Convai|DynamicContext	移除一个命名状态属性并重建规范化上下文。
ResetDynamicContext （显示名称 重置动态上下文)	—	Convai|DynamicContext	清除所有已跟踪的状态属性和事件，并重置远程上下文。
GetContextStateValue （显示名称 获取上下文状态值)	Name (FString) → OutValue (FString)，返回 bool	Convai|DynamicContext	返回某个已跟踪状态属性的当前值。若属性不存在，则返回 false 。

模式 中 UpdateContext 接受 EC_ContextUpdateMode 值； ShouldRespond 在所有动态上下文函数中接受 EC_RunLLMOption 值。有关值的说明，请参见 数据类型和枚举.

动态上下文防抖设置

属性	类型	默认	类别	说明
ContextDebounceWindow	float	0.5	Convai|DynamicContext （高级）	在最近一次待处理更新之后等待多少秒后再刷新。此窗口内的每次新更新都会重置计时器。
ContextMaxDebounceWindow	float	3.0	Convai|DynamicContext （高级）	防抖延迟的最大秒数上限。可防止持续不断的更新流无限期地推迟刷新。必须 ≥ ContextDebounceWindow.

参见 动态上下文蓝图引用 以查看完整的动态上下文功能面和任务流。

环境和角色动作

环境会跟踪聊天机器人所知晓的对象、角色和动作。 EnvironmentData 属性（FConvaiEnvironmentData，类别 Convai|Actions，显示名称 Environment）在编辑时于 详情 面板中设置。其 bEnableActions 切换用于控制动作数据是否在 /connect 时发送。

环境变更函数（对象）

函数	输入	类别	说明
AddObject	Object (FConvaiObjectEntry), bFlushImmediately (bool)	Convai|Actions	向环境添加一个对象，并安排一次 更新场景元数据 发送。同名条目会原位替换。
AddObjects	Objects (TArray<FConvaiObjectEntry>), bFlushImmediately (bool)	Convai|Actions	一次批量调用添加多个对象。
RemoveObject	ObjectName (FString), bFlushImmediately (bool)	Convai|Actions	移除与 ObjectName 匹配的对象。若未找到该名称，则不执行任何操作。
RemoveObjects	ObjectNames (TArray<FString>), bFlushImmediately (bool)	Convai|Actions	移除名称出现在 ObjectNames.
ClearObjects	bFlushImmediately (bool)	Convai|Actions	从环境中移除所有已跟踪对象。

bFlushImmediately 会绕过防抖窗口并立即发送。对于高频更新，建议使用默认的批处理行为。

环境变更函数（角色）

函数	输入	类别	说明
AddCharacter	Character (FConvaiObjectEntry), bFlushImmediately (bool)	Convai|Actions	向环境添加一个角色，并安排一次同步。同名条目会原位替换。
AddCharacters	Characters (TArray<FConvaiObjectEntry>), bFlushImmediately (bool)	Convai|Actions	一次批量调用添加多个角色。
RemoveCharacter	InCharacterName (FString), bFlushImmediately (bool)	Convai|Actions	移除与 角色名称。当未找到该名称时不执行任何操作。
移除角色	角色名称列表（TArray<FString>）, bFlushImmediately (bool)	Convai|Actions	按名称移除多个角色。
清空角色	bFlushImmediately (bool)	Convai|Actions	从环境中移除所有已跟踪的角色。
设置对话对象	对话对象（FConvaiObjectEntry）, bFlushImmediately (bool)	Convai|Actions	设置此聊天机器人当前正在与之对话的角色。若尚未存在，则自动添加到 EnvironmentData.Characters 中。若尚未存在则自动添加。传入一个空项可清除对话对象，而不会将列表中的任何人移除。

环境变更函数（动作）

动作变更会在 下一次 会话开始时生效，而不会应用到当前实时会话——动作集在 /connect 时已固定。要让新动作对正在运行的角色可用，请调用 StopSession 然后 StartSession.

函数	输入	类别	说明
添加动作	动作（FConvaiAction）	Convai|Actions	向本地环境添加一个动作模板。名称相同的条目会原地替换。
添加多个动作	动作（TArray<FConvaiAction>）	Convai|Actions	一次调用添加多个动作模板。
按名称添加动作	Name (FString)	Convai|Actions	仅按名称添加一个无描述、无参数的动作。
移除动作	Name (FString)	Convai|Actions	移除与以下项匹配的动作 名称。区分大小写。
移除多个动作	名称（TArray<FString>）	Convai|Actions	按名称移除多个动作。
清空动作	—	Convai|Actions	移除所有已跟踪的动作模板。

注意力

属性	类型	访问	类别	说明
ConversationPartner	FConvaiObjectEntry	EditAnywhere, Replicated	Convai|Actions	此聊天机器人当前正在与之对话的角色或玩家。若尚未存在，则自动添加到 EnvironmentData.Characters 中。
注意力来源	EConvaiAttentionSource	BlueprintReadOnly, 瞬态	Convai|Actions	上一次设置注意力对象的是： 无, 注视，或 显式。一个 显式 设置会锁定该槽位，直到通过向以下项传入空项将其清除： 设置注意力对象.

函数	输入	返回	类别	说明
设置注意力对象	注意力对象（FConvaiObjectEntry）, Text (FString), ShouldRespond (EC_RunLLMOption), bFlushImmediately (bool)	—	Convai|Actions	设置聊天机器人正在关注的对象，并可选地发送上下文事件。若以下情况则无效： EnvironmentData.bEnableActions 是 false.
尝试从注视设置注意力对象	与以下相同： 设置注意力对象	bool	Convai|Actions	仅在以下情况下设置注意力： 注意力来源 是 无 或 注视的口型同步组件。若组件未实现该接口，则返回 false 当槽位为 显式由注视拥有的。
尝试从注视清除注意力对象	预期对象（FConvaiObjectEntry）	bool	Convai|Actions	仅当其仍与以下项匹配时，才清除由注视占用的注意力槽位 预期对象的口型同步组件。若组件未实现该接口，则返回 false 当槽位已更改时。
为环境对象确保对象组件	—	int32 （生成的组件）	Convai|Actions	自动生成 UConvaiObjectComponent 在每个 EnvironmentData.Objects 尚未拥有该组件的 Actor 上。幂等。

动作队列

函数	返回	类别	说明
动作队列是否为空	bool	Convai|Actions	true 时由 动作队列 没有待处理项。
获取首个动作	bool, ConvaiResultAction（FConvaiResultAction） 输出	Convai|Actions	返回队列中的第一个动作，但不将其移除。返回 false 当队列为空时。
清空动作队列	—	Convai|Actions	清除 动作队列 而不向 LLM 发送任何事件。

属性	类型	访问	类别	说明
动作队列	TArray<FConvaiResultAction>	BlueprintReadOnly	Convai|Actions	待执行的有序待办动作列表。由以下项填充： OnActionReceivedEvent_V2.

处理动作完成

报告当前动作的结果。成功时，将其出队并继续下一个动作。失败时，清空剩余队列。还可以选择向 LLM 发送自动生成的结果事件。

参数	类型	默认	说明
是否成功	bool	true	true — 将已完成的动作出队并开始下一个。 false — 清空整个剩余队列。
bAutoReport	bool	true	当 true，向 LLM 发送默认结果消息： “你已成功<action>” ，成功时，或者 “未能<action>，请尝试其他方法或咨询<player name>” ，失败时。设为 false 以抑制默认消息。
ShouldRespond	EC_RunLLMOption	从不	LLM 如何对结果事件作出反应。 从不 — 静默上下文更新；结果会在下一次用户回合时进入 LLM 的视野。 自动 — 由 LLM 决定。 总是 — 强制口头回复。
附加说明	FString	""	高级显示。可选文本，将以下内容作为附加项追加到自动生成的消息中： ，“注：<text>”。当 bAutoReport 是 false 且此项非空时，它会单独发送。
延迟	float	0.0	高级显示。在下一步接触 LLM 之前等待的秒数。成功时，延迟开始下一个动作。失败时，延迟发送外发事件。

中止动作序列

清空整个动作队列，不重试也不推进。用于处理程序遇到无法恢复的问题（目标消失、前置条件失败）并希望 LLM 规划新序列时。

参数	类型	默认	说明
事件文本	FString	""	高级显示。用于描述失败原因的可选消息。为空时，中止为静默——队列会被清空，但不会向 LLM 发送事件。
ShouldRespond	EC_RunLLMOption	自动	高级显示。以下情况下忽略： 事件文本 为空。

参见 动作蓝图参考 用于完整的动作接口，包括 FConvaiAction, FConvaiResultAction以及环境结构体详情。

动画目标

这些属性驱动 AnimBP 中的注视和指向 IK。它们不会影响对话或音频管线。

属性	类型	访问	类别	说明
注视目标	AActor*	BlueprintReadWrite, Replicated	Convai|动画	角色应注视的 Actor。由 AnimBP 读取，用于头部/眼睛 IK。
指向目标	AActor*	BlueprintReadWrite, Replicated	Convai|动画	角色应指向的 Actor。由 AnimBP 读取，用于手臂 IK 或手势。

情绪

属性	类型	默认	类别	说明
锁定情绪状态	bool	false	Convai|情绪	当 true，来自 Convai 的传入情绪更新将被忽略，并且 情绪状态 保持固定。
情绪偏移	float	0.0	Convai	应用于情绪强度的标量偏置。高于 0 的值会增强；低于 0 的值会减弱。有效范围： -1 为 1.

锁定情绪状态 是一个已序列化的 bool。如果保留为空， true 在已保存的场景或预制体中，该组件会静默忽略来自 Convai 的所有实时情绪信号。请在发布前确认该值为 false 。

函数	输入	返回	类别	说明
强制设置情绪	基础情绪（EBasicEmotions）, 强度（EEmotionIntensity）, 重置其他情绪（bool）	—	Convai|情绪	使用指定的情绪和强度覆盖当前情绪状态。
获取情绪分数	情绪（EBasicEmotions）	float	Convai|情绪	返回某个特定情绪的当前分数（0.0–1.0）。
获取情绪 BlendShape	—	TMap<FName, float>	Convai|情绪	返回当前情绪 BlendShape 映射，可直接应用到骨骼网格。
重置情绪状态	—	—	Convai|情绪	将所有情绪分数清空并恢复为中性。

对于 EBasicEmotions 和 EEmotionIntensity 数值说明，请参见 数据类型和枚举.

参见 情绪蓝图参考 以了解情绪任务流程和其他节点。

事件（可在蓝图中绑定的委托）

请在角色蓝图中使用 分配 节点在 Convai 聊天机器人 组件引用上绑定。

继承自 UConvaiConversationComponent

事件	显示名称	类别	触发时机：
OnTranscriptionReceivedDelegate	—	Convai|转录	收到转录更新时触发。每次话语可能触发多次：每个中间部分一次，最终结果一次。参数： 说话者, 监听者, 转录（FString）, 转录是否就绪（bool）, 是否最终结果（bool）.
参与者连接状态变更事件	—	Convai|Connection	某个参与者的连接状态发生变化。参数： ConvaiConversationComponent, 参与者ID（FString）, 连接状态（EC_ConnectionState）.

聊天机器人专属事件

事件	显示名称	类别	触发时机：
OnStartedTalkingDelegate	—	Convai	角色的音频播放在新的回复轮次开始时启动。无参数。
OnFinishedTalkingDelegate	—	Convai	角色的音频播放完全结束，包括任何剩余的缓冲音频。无参数。
OnFacialDataReadyDelegate	—	Convai|LipSync	口型同步管线中有新的 BlendShape 帧可用。无参数。
OnActionReceivedEvent_V2	收到动作时	Convai	Convai 发送一个或多个角色动作。 动作队列 在此触发时已填充。参数： ChatbotComponent, InteractingPlayerComponent, 动作序列（TArray<FConvaiResultAction>）.
情绪状态变更事件	情绪状态已更改	Convai	Convai 返回更新后的情绪状态。 情绪状态 在此触发时已更新。参数： ChatbotComponent, InteractingPlayerComponent.
OnCharacterDataLoadEvent_V2	角色数据已加载	Convai	插件完成从 Convai 获取角色详情。触发于 LoadCharacter 或一个 CharacterID 变更后。参数： ChatbotComponent, 成功（bool）.
收到叙事章节事件	收到叙事章节	Convai	AI 进入新的叙事设计章节。参数： ChatbotComponent, 叙事章节ID（FString）.
收到交互ID事件	收到交互ID	Convai	新的交互轮次开始。参数： ChatbotComponent, InteractingPlayerComponent, 交互ID（FString）.
中断事件	被中断	Convai	InterruptSpeech 在角色说话时调用，且音频淡出开始。参数： ChatbotComponent, InteractingPlayerComponent.
失败事件	失败	Convai	会话遇到无法恢复的错误。无参数。

参见 事件系统 以了解绑定模式和时序细节。

相关参考

Convai Player 组件