Convai 聊天机器人组件

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

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

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

身份和角色数据

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

属性	类型	访问	类别	描述
CharacterID	FString	EditAnywhere, Replicated	Convai	来自以下位置的角色 ID： Convai 仪表板。通过 Blueprint 设置器设置此项会调用 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 （Blueprint 原生事件）	Convai|Session	在 Blueprint 中重写，以便在以下操作之前追加额外的动作、对象或角色： /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 Blueprint 参考 用于特定于 LTM 的节点。

对话状态查询

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

函数	返回	类别	描述
IsInConversation	bool	Convai	返回 true 当 IsProcessing(), IsListening()，或 GetIsTalking() 为 true。在当前插件源代码中，这最终简化为 GetIsTalking() 仅仅因为另外两个查询是占位实现。
IsProcessing （显示名称 正在思考)	bool	Convai	预期返回 true ，当角色正在等待 Convai 的完整回复时。 当前源码： 始终返回 false （待 session-proxy 接线的占位实现）。
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 并且可以在 Blueprint 中的 chatbot 组件上访问。

函数	返回	类别	描述
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。将当前 blendshape 分数作为扁平 float 数组返回。
GetFacialDataNames()	TArray<FString>	Convai|LipSync	BlueprintPure。按与 GetFacialData.
ConvaiGetFaceBlendshapes()	TMap<FName, float>	Convai|LipSync	BlueprintPure。返回当前 blendshape 的名称到分数映射。
GeneratesFacialDataAsBlendshapes()	bool	Convai|LipSync	BlueprintPure. true 当输出为 blendshape 格式（而非 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	向角色发送任意触发消息，使其像接收到该输入一样作出响应。

参见 叙事设计 Blueprint 参考 用于完整的叙事接口。

叙事设计模板键

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

上下文（静态和动态）

属性	类型	访问	类别	描述
DynamicEnvironmentInfo	FString	BlueprintReadWrite, EditAnywhere	Convai	在连接时注入的自由文本上下文。适用于角色在会话开始时需要的静态事实（物品栏、玩家生命值、一天中的时间）。通过 Blueprint 设置器设置会调用 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	追加一个按时间顺序记录的事件（例如 "Player approached the merchant").
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.

参见 动态上下文 Blueprint 参考 用于完整的动态上下文接口和任务流程。

环境和角色动作

环境会跟踪聊天机器人已知的对象、角色和动作。 EnvironmentData 属性（FConvaiEnvironmentData，类别 Convai|Actions，显示名称 环境）在以下位置的编辑时设置： 详情 面板。其 bEnableActions 切换项决定是否在 /connect 时发送动作数据。

环境变更函数（对象）

函数	输入	类别	描述
AddObject	Object (FConvaiObjectEntry), bFlushImmediately (bool)	Convai|Actions	向环境中添加一个对象，并安排一次 update-scene-metadata 发送。同名条目会原地替换。
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	角色（FConvaiObjectEntry）, bFlushImmediately (bool)	Convai|Actions	向环境中添加一个角色并安排同步。同名条目会在原位替换。
AddCharacters	角色（TArray<FConvaiObjectEntry>）, bFlushImmediately (bool)	Convai|Actions	以一次批量调用添加多个角色。
RemoveCharacter	InCharacterName（FString）, bFlushImmediately (bool)	Convai|Actions	移除与以下名称匹配的角色 InCharacterName。当未找到名称时不执行任何操作。
RemoveCharacters	InCharacterNames（TArray<FString>）, bFlushImmediately (bool)	Convai|Actions	按名称移除多个角色。
ClearCharacters	bFlushImmediately (bool)	Convai|Actions	从环境中移除所有已跟踪角色。
SetConversationPartner	伙伴（FConvaiObjectEntry）, bFlushImmediately (bool)	Convai|Actions	设置此聊天机器人当前正在与之对话的角色。若尚未存在，则自动添加到 EnvironmentData.Characters 。传入一个空条目即可清除伙伴，而不会从列表中移除任何人。

环境变更函数（动作）

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

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

注意力

属性	类型	访问	类别	描述
ConversationPartner	FConvaiObjectEntry	EditAnywhere, Replicated	Convai|Actions	此聊天机器人当前正在与之对话的角色或玩家。若尚未存在，则自动添加到 EnvironmentData.Characters 。
AttentionSource	EConvaiAttentionSource	BlueprintReadOnly, 临时	Convai|Actions	最后设置注意对象的是： 无, 目光，或 显式。一个 显式 设置会锁定该槽位，直到通过向 SetObjectInAttention.

函数	输入	返回	类别	描述
SetObjectInAttention	AttentionObject（FConvaiObjectEntry）, Text (FString), ShouldRespond (EC_RunLLMOption), Delivery（EConvaiContextDelivery）, bAddAttentionEvent（bool）, bFlushImmediately (bool)	—	Convai|Actions	设置聊天机器人正在关注的对象。 bAddAttentionEvent 默认开启，并发出一次刷新通告事件；关闭后可静默设置该槽位。 传递方式 可以将该提示延后，直到对话暂停时再处理。当 EnvironmentData.bEnableActions 为 false，对象不在环境列表中，或者在连接时未发送该对象时，会记录警告且不产生效果。
TrySetObjectInAttentionFromGaze	与以下相同 SetObjectInAttention	bool	Convai|Actions	仅在 AttentionSource 为 无 或 目光。当组件未实现该接口时返回 false 当槽位为 显式所有，并记录警告说明为何调用未生效。
TryClearObjectInAttentionFromGaze	ExpectedObject（FConvaiObjectEntry）	bool	Convai|Actions	仅当其仍与 ExpectedObject。当组件未实现该接口时返回 false 匹配时，才清除由目光占有的注意力槽位。
为环境对象确保对象组件	—	int32 （已生成组件）	Convai|Actions	自动生成 UConvaiObjectComponent 在每个 EnvironmentData.Objects 尚未拥有该组件的 actor 上。幂等。

动作队列

函数	返回	类别	描述
IsActionsQueueEmpty	bool	Convai|Actions	true 当 ActionsQueue 没有待处理项。
FetchFirstAction	bool, ConvaiResultAction（FConvaiResultAction） 输出	Convai|Actions	返回队列中的第一个动作，但不将其移除。若队列为空则返回 false 当队列为空时。
ClearActionQueue	—	Convai|Actions	清除 ActionsQueue ，且不会向 LLM 发送任何事件。

属性	类型	访问	类别	描述
ActionsQueue	TArray<FConvaiResultAction>	BlueprintReadOnly	Convai|Actions	待执行的有序动作列表。由 OnActionReceivedEvent_V2.

HandleActionCompletion

报告当前动作的结果。成功时，出队并推进到下一个动作。失败时，清除剩余队列。可选地向 LLM 发送自动生成的结果事件。

参数	类型	默认	描述
IsSuccessful	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 交互之前等待的秒数。成功时，延后开始下一个动作。失败时，延后发送外发事件。

AbortActionSequence

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

参数	类型	默认	描述
EventText	FString	""	高级显示。可选消息，用于描述失败内容。为空时，终止是静默的——队列会被清空，但不会向 LLM 发送任何事件。
ShouldRespond	EC_RunLLMOption	自动	高级显示。当 EventText 为空时忽略。

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

动画目标

这些属性驱动 AnimBP 中的注视和指向 IK。它们对对话或音频流程没有影响。

属性	类型	访问	类别	描述
LookAtTarget	AActor*	BlueprintReadWrite, Replicated	Convai|Animation	角色应注视的 actor。由 AnimBP 读取，用于头部/眼部 IK。
PointAtTarget	AActor*	BlueprintReadWrite, Replicated	Convai|Animation	角色应指向的 actor。由 AnimBP 读取，用于手臂 IK 或手势。

情绪

属性	类型	默认	类别	描述
LockEmotionState	bool	false	Convai|Emotion	当 true，来自 Convai 的传入情绪更新会被忽略，并且 EmotionState 保持固定。
EmotionOffset	float	0.0	Convai	应用于情绪强度的标量偏置。高于 0 会放大；低于 0 会减弱。有效范围： -1 为 1.

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

函数	输入	返回	类别	描述
ForceSetEmotion	BasicEmotion（EBasicEmotions）, Intensity（EEmotionIntensity）, ResetOtherEmotions（bool）	—	Convai|Emotion	用特定的情绪和强度覆盖当前情绪状态。
GetEmotionScore	Emotion（EBasicEmotions）	float	Convai|Emotion	返回某个特定情绪的当前分数（0.0–1.0）。
GetEmotionBlendshapes	—	TMap<FName, float>	Convai|Emotion	返回当前情绪 blendshape 映射，可直接应用到骨骼网格。
ResetEmotionState	—	—	Convai|Emotion	将所有情绪分数清零并恢复中性。

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

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

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

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

继承自 UConvaiConversationComponent

事件	显示名称	类别	在以下情况下触发
OnTranscriptionReceivedDelegate	—	Convai|Transcription	转录更新到达。每次发言会触发多次：每个中间部分一次，最终结果一次。参数： 说话者, 听者, Transcription（FString）, IsTranscriptionReady（bool）, IsFinal（bool）.
OnAttendeeConnectionStateChangedEvent	—	Convai|Connection	某个参与者的连接状态发生变化。参数： ConvaiConversationComponent, AttendeeID（FString）, ConnectionState（EC_ConnectionState）.

聊天机器人特定事件

事件	显示名称	类别	在以下情况下触发
OnStartedTalkingDelegate	—	Convai	角色的音频播放在新的回复轮次开始。无参数。
OnFinishedTalkingDelegate	—	Convai	角色的音频播放完全结束，包括任何剩余的缓冲音频。无参数。
OnFacialDataReadyDelegate	—	Convai|LipSync	唇形同步流程中有新的 blendshape 帧可用。无参数。
OnActionReceivedEvent_V2	收到动作	Convai	Convai 会发送一个或多个角色动作。 ActionsQueue 触发时此项已填充。参数： ChatbotComponent, InteractingPlayerComponent, SequenceOfActions（TArray<FConvaiResultAction>）.
OnEmotionStateChangedEvent	情绪状态已更改	Convai	Convai 返回更新后的情绪状态。 EmotionState 触发时此项已更新。参数： ChatbotComponent, InteractingPlayerComponent.
OnCharacterDataLoadEvent_V2	角色数据已加载	Convai	插件完成从 Convai 获取角色详情。在以下之后触发 LoadCharacter 或一个 CharacterID 变更。参数： ChatbotComponent, Success（bool）.
OnNarrativeSectionReceivedEvent	收到叙事段落	Convai	AI 进入新的叙事设计部分。参数： ChatbotComponent, NarrativeSectionID（FString）.
OnInteractionIDReceivedEvent	收到交互 ID	Convai	新的交互轮次开始。参数： ChatbotComponent, InteractingPlayerComponent, InteractionID（FString）.
OnInterruptedEvent	已中断	Convai	InterruptSpeech 在角色说话且音频淡出开始时调用。参数： ChatbotComponent, InteractingPlayerComponent.
OnFailureEvent	失败	Convai	会话遇到无法恢复的错误。无参数。

参见 事件系统 用于绑定模式和时序细节。

相关参考

Convai 玩家组件