数据类型和枚举

Convai Unreal Engine 插件中 Blueprint 暴露的结构体和枚举参考，包括对象条目、动作类型、情感和连接状态。

此处记录了在 Convai Blueprint API 中作为参数或返回类型出现的每个结构体和枚举。当某个引脚需要一个 FConvaiObjectEntry，一个 EC_RunLLMOption，或者任何其他共享类型。

对象和环境类型

这些类型表示 Actor世界中的对象、在会话开始时发送给 Convai 的环境契约，以及用于让 Convai 了解运行时状态变化的跟踪属性系统。

FConvaiObjectEntry

一条 Actor 一种携带标识、描述和导航目标数据的引用。在整个环境 API 中使用——包括 FConvaiEnvironmentData.Objects, FConvaiEnvironmentData.Characters，例如 ConversationPartner on UConvaiChatbotComponent，以及作为类型为 Reference 的结果动作参数值。

字段	类型	默认值	说明
Ref	TWeakObjectPtr<AActor>	nullptr	该 Actor 此条目所指向的对象。
OptionalPositionVector	FVector	(0, 0, 0)	已弃用。 已自动写入的已解析目标位置快照。请勿手动设置。请使用 Resolve Goal Location的 Out Goal Location 输出一个实时世界点来代替。
名称	FString	""	发送给 Convai 的显示名称。必须在聊天机器人的环境中对所有对象和角色保持唯一。
说明	FString	""	该项的自然语言描述 Actor ——AI 应该理解它什么。
移动目标模式	EConvaiMoveTarget	Actor	AI 移动动作是否朝向整个 Actor 或其上的某个特定组件或插槽。
接受半径	float （厘米）	150.0	……的距离 AI 移动到 视为移动完成。精确目标（门把手）取较小值，宽大对象（车辆）取较大值。
组件名称	FString	""	不区分大小写的子串匹配，针对 Actor的组件，当 移动目标模式 为 Vector （Blueprint 显示名称 将组件作为目标）。留空则以 Actor的原点为目标。
Socket 或 Bone 名称	FName	无	在匹配到的组件上用作目标点的插槽或骨骼。未找到时回退到组件原点。仅在 移动目标模式 为 Vector (将组件作为目标).
bStepOntoBounds	bool	false	当 true时，目标点会投影到目标包围盒顶部，使 AI 走上平台或表面而不是停在边缘。两种移动目标模式都适用。
ResolvedComponent	TWeakObjectPtr<USceneComponent>	—	仅输出。 Convai 使用以下方式解析的组件 组件名称。当动作到达时由插件填充。请勿手动设置此字段。

ResolvedComponent 在运行时由插件填充；若组件被销毁则清空。在收到动作后可在 Blueprint 中读取它，以直接访问已解析的组件（用于附加特效、读取其变换等）。

EConvaiMoveTarget

控制 AI 移动到 当此条目是移动目标时，动作将其作为导航目标。

值	显示名称	说明
Actor	将 Actor 作为目标	AI 会导航到所引用的 Actor的边界。最适合 “走到汽车旁”, “跟随玩家”.
Vector	将组件作为目标	AI 会导航到一个计算出的世界点—— Actor的原点、一个命名子组件或一个插槽/骨骼，并由 bStepOntoBounds进行细化。最适合 “站在门把手旁”, “走上平台”。在 Blueprint 选择器中，选择 将组件作为目标；底层枚举值为 Vector.

FConvaiEnvironmentData

在会话开始时发送给 Convai 的完整动作可执行契约，形式为 action_config。填充于 UConvaiChatbotComponent.EnvironmentData 在“Details”面板中，或在运行时使用 添加/移除/清空 聊天机器人组件上的方法进行修改。

字段	类型	默认值	说明
bEnableActions	bool	true	主开关。当 false时，不会 action_config 发送内容，且所有其他字段都会被忽略。
动作	TArray<FConvaiAction>	Move To, 跟随, 停止移动, Wait For	角色可执行的物理动作。
Objects	TArray<FConvaiObjectEntry>	[]	角色可以引用或前往的世界对象。
Characters	TArray<FConvaiObjectEntry>	[]	角色可以交互的其他角色或 NPC。
CurrentAttentionObject	FConvaiObjectEntry	—	当前聚焦的对象——Convai 用于解析代词引用（"this", "that", "it").

FConvaiTrackedProperty

所属对象上的一个属性 Actor ，它 UConvaiObjectComponent 会监控并向所有聊天机器人报告。AI 会在会话开始时接收当前值，并在其发生变化时再次接收。

字段	类型	默认值	说明
PropertyPath	FName	—	以点分隔的路径，指向 Actor （例如 "bActive", “Stats.HP”, “GetCurrentRoomName”）。使用“Bind”按钮在 Details 面板中从属性树里选择。
说明	FString	""	该属性的含义，用通俗语言说明给 AI（例如 "玩家是否已激活此开关").
StateValueDescriptions	TArray<FConvaiTrackedPropertyStateValueDesc>	[]	对于具有少量有意义状态（枚举、布尔、命名阶段）的属性，可为每个值提供可选描述。对于自由格式计数器或浮点数可跳过。
ShouldRespond	EC_RunLLMOption	从不	当此值在运行时变化时，聊天机器人应如何处理。会话开始时的初始种子始终是 从不.

FConvaiTrackedPropertyStateValueDesc

一个单值描述条目，位于 FConvaiTrackedProperty.StateValueDescriptions。描述某个跟踪属性的一个特定值的含义。

字段	类型	说明
值	FString	发送给聊天机器人的字面值（例如 "Locked", "true", "0", "Idle"）。必须与该属性在运行时读取到的值一致。
说明	FString	该值的人工语言含义——AI 看到此值时应理解什么。

EConvaiAttentionSource

跟踪是谁设置了聊天机器人当前的 CurrentAttentionObject。由目光驱动的注意力只有在其为 无 或已 凝视。一个 显式 由 Blueprint 或 C++ 设置的对象会获胜并占据该槽位，直到被清除。

值	显示名称	说明
无	无	当前没有对象处于注意中。
显式	Explicit（Blueprint/C++）	通过 SetObjectInAttention 在 Blueprint 或 C++ 中设置。目光无法覆盖它。
凝视	凝视	由目光注意系统设置。可被 显式 或 无 在玩家移开视线时覆盖。

---

动作类型

这些类型定义了动作模板系统：动作如何注册到聊天机器人，以及填充后的结果如何在 OnActionReceivedEvent_V2.

FConvaiAction

一个注册于 FConvaiEnvironmentData.Actions。定义 AI 被允许做什么，以及如何向 LLM 描述每个动作。

字段	类型	默认值	说明
名称	FString	""	不含占位符的规范动作名称（例如 "Move To", "Parse", "Open Door").
说明	FString	""	对动作功能的可选描述。会提供给 LLM 以提高准确性。
Parameters	TArray<FConvaiActionParam>	[]	有序的类型化参数。响应会按位置将填入的值映射回这些名称。
bWaitForBotSpeech	bool	false	当 true 且此动作在序列中最先到达，则分发会延迟，直到角色开始或结束说话后才触发该动作。对序列中的后续动作无影响。
DelayAfterBotSpeechSec	float	0.0	在之后附加的延迟，单位为秒 bWaitForBotSpeech 解析完成后生效。视为 0 当 bWaitForBotSpeech 为 false.

FConvaiActionParam

一个类型化占位参数，位于 FConvaiAction 模板中。

字段	类型	默认值	说明
名称	FString	""	占位符名称，按其在模板中的显示方式（例如 "destination", "time in seconds").
说明	FString	""	参数含义的可选描述。会提供给 LLM 以便更好地选择值。
类型	EConvaiActionParamType	Auto	声明的类型。决定提示词提示以及解析器如何解释响应。
连接器	FString	""	在线格式中于此参数前渲染的可选连接文本（例如 "on" ，用于“Put ball on table”）。
Choices	TArray<FString>	[]	固定选项约束。非空时，LLM 从此列表中选择。以下情况忽略： 类型 为 枚举.
枚举类型	TObjectPtr<UEnum>	nullptr	用于抽取选项的 Blueprint 枚举类型。以下情况必需： 类型 为 枚举.

EConvaiActionParamType

动作参数的声明类型。决定 LLM 在在线格式中如何渲染该参数，以及解析器如何解释响应。

值	显示名称	说明
Auto	Auto	在解析时推断：先尝试 Reference ，然后 Number，然后 布尔，再回退到 字符串。最灵活的选项。
Reference	Actor Reference	该值会根据 Environment.Objects 是位于 Environment.Characters。结果填充到 FConvaiResultParam.RefValue.
字符串	字符串	自由格式文本值。结果填充到 FConvaiResultParam.StringValue.
Number	Number	数值。结果填充到 FConvaiResultParam.NumberValue.
布尔	布尔	布尔值（"true", "yes", "1" → true）。结果填充到 FConvaiResultParam.BoolValue.
枚举	枚举	值受限于 UEnum。选项会自动从 FConvaiActionParam.EnumType。匹配到的枚举项字节值位于 FConvaiResultParam.ByteValue.

FConvaiResultAction

AI 触发并传递的已解析动作，位于 OnActionReceivedEvent_V2。包含动作名称、原始动作字符串，以及参数值的类型化映射。

RelatedObjectOrCharacter 是位于 ConvaiExtraParams 已弃用。请从 Parameters 映射中读取参数值。

字段	类型	说明
Action	FString	与模板匹配的规范动作名称。
ActionString	FString	未经预处理、从 AI 接收到的完整渲染动作字符串。
Parameters	TMap<FString, FConvaiResultParam>	按插入顺序排列的占位符名称到类型化值的映射。键是 FConvaiActionParam.Name.
bWaitForBotSpeech	bool	复制自 FConvaiAction.bWaitForBotSpeech，在解析时复制。仅对新到达序列中的第一个动作生效。
DelayAfterBotSpeechSec	float	复制自 FConvaiAction.DelayAfterBotSpeechSec。视为 0 当 bWaitForBotSpeech 为 false.
RelatedObjectOrCharacter	FConvaiObjectEntry	已弃用。 复制首个 Reference 参数。请 Parameters 代替。
ConvaiExtraParams	FConvaiExtraParams	已弃用。 复制数值、文本和字符串映射值，自 Parameters时。使用 Parameters 代替。

FConvaiResultParam

一个单独的类型化参数值，位于 FConvaiResultAction.Parameters。无论声明类型如何，所有值字段都会尽最大可能填充——请读取最适合你处理逻辑的字段。

字段	类型	说明
类型	EConvaiActionParamType	来自动作模板的声明类型。指示哪个值字段是预期槽位。
StringValue	FString	以字符串形式的原始值。始终会填充。
NumberValue	float	atof(StringValue). 0 若非数值也会尝试转换。始终尝试。
BoolValue	bool	true 当 StringValue 为 "true", "yes"，或 "1"。始终尝试。
RefValue	FConvaiObjectEntry	匹配到的 Actor 条目，当 StringValue 根据…解析时 Environment.Objects 或 Environment.Characters。若无匹配则为空。
ByteValue	uint8	参数类型为时匹配到的枚举项字节值 枚举 是位于 枚举类型 被设置。使用 Byte-to-Enum 转换节点获取类型化值。 0 用于非枚举 参数。

---

情绪类型

这些类型用于 ForceSetEmotion, GetEmotionScore，以及 GetEmotionBlendshapes on UConvaiChatbotComponent.

EBasicEmotions

Plutchik 情绪轮中的八种基本情绪。传递给 ForceSetEmotion 以覆盖角色的情绪状态。

值	Blueprint 显示名称	说明
喜悦	开心
信任	平静
恐惧	害怕
惊讶	惊讶
悲伤	难过
厌恶	无聊
愤怒	生气
期待	—	已标记 隐藏。仅供内部使用。
无	—	已标记 隐藏。当未找到任何情绪时返回。

EEmotionIntensity

在使用以下方式强制设置情绪状态时应用的强度修饰： ForceSetEmotion.

值	显示名称	说明
基本	基本	该情绪的标准强度。
LessIntense	较低强度	一个较温和的变体（例如 喜悦 → 宁静, 愤怒 → 恼怒).
MoreIntense	更强烈	一个加强版变体（例如 喜悦 → 狂喜, 愤怒 → 暴怒).
无	—	已标记 BlueprintHidden。当无法确定强度时返回。

---

连接和会话类型

这些类型由连接状态查询和连接管理函数返回。

EC_ConnectionState

聊天机器人组件与 Convai 之间 WebRTC 通道的当前状态。由 GetChatbotConnectionState on UConvaiChatbotComponent.

值	显示名称	说明
已断开	已断开	没有活动会话。
连接中	连接中	握手进行中。
已连接	已连接	会话处于活动状态并已准备好接收音频和文本。
重新连接中	重新连接中	之前的会话已断开，插件正在重新建立连接。

EC_PrepResult

……的结果 PrepareCharacterConnection 在 UConvaiConnectionLibrary。指示预热请求是否被接受，以及连接槽位处于何种状态。

值	显示名称	说明
已接受	已接受	预热请求已被接受，连接槽位正在准备中。
AlreadyWarm	已经预热	该角色的连接槽位已处于活动或预热状态——无需额外操作。
已拒绝	已拒绝	连接管理器拒绝替换当前拥有活动连接槽位的其他角色。
无效输入	无效输入	角色 ID 为空。
已禁用	已禁用	已禁用连接预热，因为解析后的预热连接 TTL 为 0.0 或更低。
内部错误	内部错误	请求无法完成，因为子系统或管理器不可用，或者连接尝试失败。

EC_RunLLMOption

控制 Convai 是否会在环境更新调用后生成语音回复（SetContextState, AddContextEvent, SetObjectInAttention及类似调用）。默认值因函数而异——请查看各函数的描述。

值	显示名称	说明
Auto	Auto	Convai 会根据更新的性质决定是否适合回应。
始终	始终	角色在此更新后总会生成并说出回复。
从不	从不	AI 会被静默告知此次更新，但不会主动谈论它。

EC_ContextUpdateMode

由…使用的模式 UpdateContext on UConvaiChatbotComponent ，用于控制新文本如何与角色现有的动态上下文合并。

值	显示名称	说明
Append	Append	将新文本添加到现有动态上下文末尾。
Replace	Replace	用新文本替换匹配的上下文条目。
Reset	Reset	清除整个动态上下文，然后设置新文本。

---

音频类型

这些类型用于 VAD（语音活动检测）设置和长期记忆说话者识别。

FConvaiVADSettings

语音活动检测覆盖项。通过 SetVADSettings 并通过 GetVADSettings on UConvaiUtils。当 bUseServerDefault 为 true，所有其他字段都会被忽略，Convai 会应用自己的默认值。

字段	类型	默认值	约束	说明
bUseServerDefault	bool	true	—	主开关。当 true时，下面所有按字段的值都会被忽略。
置信度	float	0.7	0.0–1.0	帧包含语音的最低 VAD 模型概率。值越高越严格。
StartSecs	float	0.2	>= 0.0	持续语音的秒数，之后 "user started speaking" 触发。值越高越会忽略短暂爆发。
StopSecs	float	2.2	>= 0.0	静默秒数，之后 "user stopped speaking" 触发。值越低可更快检测到轮次结束，但有截断语音的风险。
MinVolume	float	0.6	0.0–1.0	振幅下限——低于此级别的音频会被视为静音。用于拒绝背景噪音的主要手段。

FConvaiSpeakerInfo

用于长期记忆操作的说话者身份。在将会话记忆与特定最终用户关联时使用。

字段	类型	说明
SpeakerID	FString	说话者的唯一标识符。
名称	FString	说话者的显示名称。
DeviceID	FString	与说话者关联的设备标识符。

---

口型同步类型

EC_LipSyncMode

由面部同步组件配置，并由口型同步辅助函数返回。

值	显示名称	说明
关闭	关闭	口型同步已禁用。
Auto	Auto	插件会根据配置的骨骼系统选择输出模式。
VisemeBased	基于 Viseme	用于音素驱动骨骼系统的 viseme 输出。
BS_MHA	MetaHuman Blendshapes	MetaHuman 和 CC5 混合形状输出。
BS_ARKit	ARKit Blendshapes	ARKit 混合形状输出。
BS_CC4_Extended	CC4 Extended Blendshapes	扩展的 CC4 混合形状输出。

---

混合形状类型

FConvaiBlendshapeParameters

逐个混合形状的变换配置，由 MapBlendshapes 在 Convai 工具函数.

字段	类型	默认值	说明
TargetNames	TArray<FName>	[]	用于写入变换后值的输出键名。
乘数	float	1.0	在全局修饰符之前应用的逐个混合形状乘数。
偏移	float	0.0	在乘法之后应用的逐个混合形状偏移量。
UseOverrideValue	bool	false	当 true，则写入 OverrideValue 直接写入，忽略输入和修饰符。
IgnoreGlobalModifiers	bool	false	当 true, GlobalMultiplier 是位于 GlobalOffset on MapBlendshapes 不会应用到此条目。
OverrideValue	float	0.0	在……时写入的固定值 UseOverrideValue 为 true.
ClampMinValue	float	0.0	输出会被限制为此最小值。
ClampMaxValue	float	1.0	输出会被限制为此最大值。

相关参考

Convai Chatbot 组件Convai Player 组件Convai Object 组件Convai 实用函数