数据类型和枚举

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 此条目所指向的对象。
可选位置向量	FVector	(0, 0, 0)	已弃用。 解析后的目标位置的自动写入快照。不要手动设置。请改用 解析目标位置的 输出目标位置 输出，以获取实时世界点。
名称	FString	""	发送给 Convai 的显示名称。必须在聊天机器人环境中的所有对象和角色之间保持唯一。
描述	FString	""	该 Actor 的自然语言描述——AI 应理解它是什么。
ObjectReference （蓝图显示名称 对象是)	EConvaiObjectReference	整个 Actor	该 Actor 算作此对象的哪一部分——整体，还是其中某个特定组件。这决定角色在关注对象时看向哪里，以及在以下情况下走向哪里 MovementPoints 为空时忽略。
ComponentName	FString	""	对 Actor的组件进行不区分大小写的子串匹配，当 ObjectReference 为 特定组件。留空则使用 Actor自身的位置。
SocketOrBoneName	FName	无	在匹配到的组件上用作目标点的插槽或骨骼。未找到时回退到组件原点。仅在 ObjectReference 为 特定组件.
AcceptanceRadius	float （厘米）	150.0	角色必须接近到多少厘米内才算到达。精确目标（门把手）设小一些，宽大对象（车辆）设大一些。
MovementPoints	TArray<FConvaiMovementPoint>	[]	该对象由设计者编写的可到达目的地——例如，门两侧各一个点。为空时，角色会直接走向对象本身，通过 ObjectReference.
将对象作为回退 (bFallbackToObjectWhenPointsUnreachable)	bool	false	当所有 MovementPoints 条目不可达，则直接走向对象本身，而不是报告对象不可达。默认关闭。
ResolvedComponent	TWeakObjectPtr<USceneComponent>	—	仅输出。 Convai 使用 ComponentName解析的组件。当动作到达时由插件填充。不要手动设置此字段。

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

EConvaiObjectReference

一个 FConvaiObjectEntry的引用指向什么——对象本身。用于凝视/注意范围、视觉标记，以及在没有 MovementPoints 被编写时作为移动回退。 当 MovementPoints 被编写在条目上时，它们就成为移动目标，而 ObjectReference 只定义对象是什么。

值	显示名称	描述
整个 Actor	整个 Actor	整个 Actor 就是对象。凝视匹配其任一原语；移动回退会停在 Actor 的边界处。
特定组件	特定组件	位于 Actor 就是对象（设置 ComponentName，可选一个插槽或骨骼）。凝视只匹配该组件；移动回退会以其世界位置为目标。

EConvaiMovementPointAttachment

如何解释 FConvaiMovementPoint的变换。

值	显示名称	描述
相对于对象	相对于对象	该点的变换相对于对象——会随目标 Actor一起移动，或在 ObjectReference 是组件范围时随特定组件一起移动。默认。
KeepWorldPosition	保持世界位置	该点的变换是绝对世界空间——即使对象移动，它也保持不动。

FConvaiMovementPoint

一个由设计者编写的移动接入点——角色移动到对象时应站立的位置，例如门两侧各一个点。纯数据，可通过 UConvaiObjectComponent 上的视口可视化器或直接在细节面板中编辑。解析器会选择可达且步行路径最短的点。

字段	类型	默认值	描述
变换	FTransform	—	当选中此点时角色所站的位置。只有位置会驱动移动；旋转会被存储且可编辑，但保留供未来的朝向控制使用。
附着方式	EConvaiMovementPointAttachment	相对于对象	该点是随对象移动还是固定在世界中。
是否启用 （蓝图显示名称 已启用)	bool	true	取消勾选可将该点移出可用状态而不删除它。如果对象上的每个点都被禁用，则对象的表现就像没有这些点一样——角色会直接走到对象本身。
bCreatesSeparateDestination （蓝图显示名称 创建单独目的地)	bool	false	开启后，该点会成为 AI 可前往的独立目的地，称为 “<对象> <目的地名称>”。关闭时，该点只是 AI 前往对象本身时可站立的位置之一。
名称 （蓝图显示名称 目标名称)	FString	""	这个独立目的地的名称。仅在 bCreatesSeparateDestination 已开启。

FConvaiEnvironmentData

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

字段	类型	默认值	描述
bEnableActions	bool	true	主开关。当 false时，不会发送 action_config ，并且所有其他字段都会被忽略。
动作	TArray<FConvaiAction>	移动到, 跟随, 停止移动, 等待	角色可执行的物理动作。
对象	TArray<FConvaiObjectEntry>	[]	角色可以引用或前往的世界对象。
角色	TArray<FConvaiObjectEntry>	[]	角色可以交互的其他角色或 NPC。
CurrentAttentionObject	FConvaiObjectEntry	—	当前被聚焦的对象——Convai 用它来解析代词引用（"这个", "那个", "它").

FConvaiTrackedProperty

拥有者上的一个属性 Actor 该 UConvaiObjectComponent 监视并向所有聊天机器人报告。AI 在会话开始时接收当前值，并在其每次变化时再次接收。

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

FConvaiTrackedPropertyStateValueDesc

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

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

EConvaiAttentionSource

跟踪谁设置了聊天机器人的当前 CurrentAttentionObject。由凝视驱动的注意力只有在其为 无 或已 目光。一个 显式 通过 Blueprint 或 C++ 设置时才能占用该槽位，并会一直保留直到清除。

值	显示名称	描述
无	无	当前没有对象处于注意中。
显式	显式（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", "秒数").
描述	FString	""	对参数含义的可选描述。会展示给 LLM，以便更好地选择值。
类型	EConvaiActionParamType	Auto	声明的类型。既决定提示词线索，也决定解析器如何解释响应。
连接词	FString	""	在 wire format 中于此参数之前渲染的可选连接文本（例如 "on" 用于“把球放在桌子上”）。
Choices	TArray<FString>	[]	固定选项约束。非空时，LLM 会从该列表中选择。以下情况会忽略 类型 为 Enum.
EnumType	TObjectPtr<UEnum>	nullptr	用于从中提取选项的 Blueprint 枚举类型。以下情况必须提供 类型 为 Enum.

EConvaiActionParamType

动作参数的声明类型。决定 LLM 如何在 wire format 中呈现该参数，以及解析器如何解释响应。

值	显示名称	描述
Auto	Auto	解析时推断：先尝试 Reference ，然后 Number，然后 Bool，再回退到 String。最灵活的选项。
Reference	Actor 引用	该值会相对于 Environment.Objects 和 Environment.Characters进行解析。结果填充到 FConvaiResultParam.RefValue.
String	String	自由形式文本值。结果位于 FConvaiResultParam.StringValue.
Number	Number	数值。结果位于 FConvaiResultParam.NumberValue.
Bool	Bool	布尔值（"true", "是", "1" → true）。结果位于 FConvaiResultParam.BoolValue.
Enum	Enum	值受 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", "是"，或 "1"。始终会尝试。
RefValue	FConvaiObjectEntry	匹配到的 Actor 条目，当 StringValue 相对于 Environment.Objects 或 Environment.Characters解析后。若无匹配则为空。
ByteValue	uint8	当参数类型为 Enum 和 EnumType 时，匹配到的枚举项的字节值。请使用 Byte 转 Enum 转换节点获取有类型的值。 0 用于非Enum 参数。

---

情绪类型

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

EBasicEmotions

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

值	Blueprint 显示名称	注意
喜悦	快乐
信任	平静
恐惧	害怕
惊讶	惊讶
悲伤	悲伤
厌恶	无聊
愤怒	生气
期待	—	已标记 隐藏。仅供内部使用。
无	—	已标记 隐藏。在未找到情绪时返回。

EEmotionIntensity

在使用 ForceSetEmotion.

值	显示名称	描述
Basic	Basic	强制设置情绪状态时应用的强度修饰符。该情绪的标准强度。
LessIntense	较低强度	较温和的变体（例如 喜悦 → 宁静, 愤怒 → 烦恼).
MoreIntense	更高强度	增强的变体（例如 喜悦 → 狂喜, 愤怒 → 暴怒).
无	—	已标记 BlueprintHidden。在无法确定强度时返回。

---

连接和会话类型

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

EC_ConnectionState

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

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

EC_PrepResult

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

值	显示名称	描述
Accepted	Accepted	预热请求已被接受，正在准备一个连接槽位。
AlreadyWarm	已预热	此角色的连接槽位已经处于活动或预热状态——无需额外工作。
Rejected	Rejected	连接管理器拒绝挤掉当前拥有活动连接槽位的另一个角色。
InvalidInput	输入无效	角色 ID 为空。
Disabled	Disabled	由于解析出的预热连接 TTL 为 0.0 或更低，连接预热已被禁用。
InternalError	内部错误	由于子系统或管理器不可用，或连接尝试失败，请求无法完成。

EC_RunLLMOption

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

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

EC_ContextUpdateMode

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

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

---

音频类型

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

FConvaiVADSettings

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

字段	类型	默认值	约束	描述
bUseServerDefault	bool	true	—	主开关。当 true时，下面所有按字段的值都会被忽略。
置信度	float	0.7	0.0–1.0	模型判定一帧包含语音的最小 VAD 概率。数值越高越严格。
开始秒数	float	0.2	>= 0.0	持续语音的秒数，直到 “用户开始说话” 触发。数值越高会忽略短暂的语音片段。
停止秒数	float	2.2	>= 0.0	静音持续的秒数，直到 “用户停止说话” 触发。数值越低可更快检测到轮次结束，但可能会截断语音。
最小音量	float	0.6	0.0–1.0	幅度下限——低于此级别的音频会被视为静音。用于过滤背景噪声的主要参数。

FConvaiSpeakerInfo

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

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

---

口型同步类型

EC_LipSyncMode

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

值	显示名称	描述
Off	Off	已禁用口型同步。
Auto	Auto	插件会根据所配置的骨架自动选择输出模式。
VisemeBased	基于 Viseme	适用于基于音素驱动的骨架的可视素输出。
BS_MHA	MetaHuman 混合形状	MetaHuman 和 CC5 的混合形状输出。
BS_ARKit	ARKit 混合形状	ARKit 混合形状输出。
BS_CC4_Extended	CC4 扩展混合形状	扩展的 CC4 混合形状输出。

---

混合形状类型

FConvaiBlendshapeParameters

按混合形状配置的变换设置，用于 MapBlendshapes 在 Convai 工具函数.

字段	类型	默认值	描述
TargetNames	TArray<FName>	[]	要写入变换后数值的输出键名。
乘数	float	1.0	每个混合形状在全局修饰符之前应用的乘数。
偏移量	float	0.0	每个混合形状在乘法之后应用的偏移量。
使用覆盖值	bool	false	当 true，将 覆盖值 直接写入，忽略输入和修饰符。
忽略全局修饰符	bool	false	当 true, 全局乘数 和 全局偏移量 on MapBlendshapes 不会应用到此条目。
覆盖值	float	0.0	当 使用覆盖值 为 true.
最小钳制值	float	0.0	输出将被钳制到此最小值。
最大钳制值	float	1.0	输出将被钳制到此最大值。

相关参考

Convai 聊天机器人组件Convai 玩家组件Convai Object ComponentConvai 工具函数