动作 Blueprint 参考

Convai 角色动作在 Unreal Engine 中所依赖的 Blueprint 结构体、枚举、事件和队列函数参考。

本页是 Convai Unreal Engine 插件中构成角色动作 API 的结构体、枚举、事件和函数的完整参考。除非另有说明，所有条目都可通过 Blueprint 访问。

FConvaiEnvironmentData

存储在 环境 ……上的属性 UConvaiChatbotComponent. 序列化为 action_config 在会话开始时。

字段	类型	默认值	说明
bEnableActions	bool	true	主开关。通过 启用操作 在详情面板中。
动作	TArray<FConvaiAction>	四个默认值	动作模板。
Objects	TArray<FConvaiObjectEntry>	[]	场景对象目标。
Characters	TArray<FConvaiObjectEntry>	[]	场景角色目标。
CurrentAttentionObject	FConvaiObjectEntry	空	通过 SetObjectInAttention.

FConvaiAction

动作模板结构体。在编辑时于 动作 数组 FConvaiEnvironmentData.

字段	类型	默认值	说明
名称	FString	""	规范动作名称。必须与 Blueprint 处理函数名称完全一致，包括空格。Unreal 在解析处理函数名时不区分大小写。
说明	FString	""	发送给 Convai 的可选提示。
Parameters	TArray<FConvaiActionParam>	[]	按顺序排列的带类型参数。
bWaitForBotSpeech	bool	false	将新序列中的第一个动作延迟，直到语音开始、语音结束、无响应触发或等待超时到期。
DelayAfterBotSpeechSec	float	0.0	语音条件满足后额外延迟。

FConvaiActionParam

参数模板。每个占位符对应一项，位于一个 FConvaiAction.

字段	类型	默认值	说明
名称	FString	""	占位符名称。映射到 Parameters 中的键 FConvaiResultAction.
说明	FString	""	给 Convai 的可选提示。
类型	EConvaiActionParamType	Auto	声明的类型。见下方类型表。
连接器	FString	""	在此参数之前渲染的连接文本，例如 "on".
Choices	TArray<FString>	[]	固定选项列表。当 类型 == 枚举.
枚举类型	UEnum*	null	当 类型 == 枚举.

EConvaiActionParamType

值	显示名称	解析行为
Auto	Auto	推断：引用 > 数字 > 布尔 > 字符串。
Reference	Actor Reference	解析为 Objects / Characters 通过精确的已注册名称。
字符串	字符串	原始字符串。
Number	Number	float 通过 Atof.
布尔	布尔	"true"/"yes"/"1" → true.
枚举	枚举	与 枚举类型 显示名称匹配；枚举值存储在 ByteValue.

FConvaiResultAction

传递给动作处理程序的结构体。每次分发的动作对应一个。

字段	类型	说明
Action	FString	模板匹配后的规范动作名称。
ActionString	FString	来自 Convai 的未处理原始动作字符串。
Parameters	TMap<FString, FConvaiResultParam>	参数名 → 解析后值的映射。使用 获取参数 / Get Param As X.
bWaitForBotSpeech	bool	在解析时从匹配的模板复制。
DelayAfterBotSpeechSec	float	从匹配的模板复制。
RelatedObjectOrCharacter	FConvaiObjectEntry	已弃用。 镜像第一个引用类型参数。使用 GetParamAsRef 在 Parameters 映射中读取参数值。
ConvaiExtraParams	FConvaiExtraParams	已弃用。 镜像第一个数字/文本/命名参数。使用 GetParamAs* 在 Parameters 映射中读取参数值。

FConvaiResultParam

一个已解析的参数值。无论声明类型如何，所有字段都会尽可能填充。

字段	类型	说明
类型	EConvaiActionParamType	声明或推断的类型。
StringValue	FString	原始值。始终填充。
NumberValue	float	Atof(StringValue). 0 如果不是数字。
BoolValue	bool	true 如果 "true", "yes"，或 "1".
RefValue	FConvaiObjectEntry	已解析的 Actor 引用。若未匹配到环境项则为空。
ByteValue	uint8	当 类型 == 枚举 是位于 枚举类型 已设置； 0 否则。

FConvaiObjectEntry

描述环境中的一个场景对象或角色。

字段	类型	默认值	说明
名称	FString	""	唯一标签。必须在所有已注册对象中保持唯一。
Ref	TWeakObjectPtr<AActor>	null	实时 Actor。若 Actor 被销毁，该条目仍可保留其名称，同时 Resolve Goal Location 报告失败。
说明	FString	""	面向 Convai 的自然语言描述。
移动目标模式	EConvaiMoveTarget	Actor	将 Actor 作为目标 或 将组件作为目标.
接受半径	float	150.0	停止距离（厘米）。
组件名称	FString	""	子组件过滤器。用于 将组件作为目标 模式下编辑。
Socket 或 Bone 名称	FName	无	匹配组件上的插槽或骨骼。
bStepOntoBounds	bool	false	走到对象顶部，而不是停在边缘。
ResolvedComponent	TWeakObjectPtr<USceneComponent>	null	瞬态，只读 — 由 ResolveGoalLocation.
OptionalPositionVector	FVector	(0,0,0)	已弃用。 使用 Out Goal Location 的输出 Resolve Goal Location 代替。

EConvaiMoveTarget

值	显示名称	行为
Actor	将 Actor 作为目标	AI 在 Actor 的边界处停止。
Vector	将组件作为目标	AI 走到 Actor 上或附近计算出的世界点。

Resolve Goal Location

位于 UConvaiActions （类别 Convai | 动作 API).

将一个 FConvaiObjectEntry 为某个 AI 移动到 节点所需的输入，并可选地运行 NavMesh 路径查询。

输入：

引脚	类型	说明
条目	FConvaiObjectEntry （引用）	要解析的对象。
源 Actor	AActor*	可选。提供时，也会计算可达性。
bForce Refresh	bool	绕过缓存的解析。高级引脚。

输出：

引脚	类型	说明
输出目标 Actor	AActor*	该 Ref Actor。仅在 Actor 模式下连接到 AI Move To。
输出目标组件	USceneComponent*	已解析的子组件（Vector 模式 + 组件名称匹配）。
Out Goal Location	FVector	已解析的世界位置。仅在 Vector 模式下连接到 AI Move To。
输出接受半径	float	镜像 Entry.AcceptanceRadius.
Out Mode	EConvaiMoveTarget	在 Step Onto Bounds 提升后生效的模式。 基于此分支 在 AI Move To 之前。
bOut Success	bool	true 当 Ref 是否存活。在发出 AI Move To 之前务必检查。
bOut Already There	bool	true 当源 Actor 已经到达目标时。若 true.
bOut Reachable	bool	true 当 NavMesh 路径到达目标边界时。
输出路径终点	FVector	路径查询的最终导航点。
输出路径点	TArray<FVector>	用于调试可视化的完整导航路径。

UConvaiActions — 参数访问器

Blueprint 函数库（类别 Convai | 动作 API）。所有函数都接受 const FConvaiResultAction&.

函数	显示名称	返回类型
GetFirstParam	获取第一个参数	FConvaiResultParam
GetParam	获取参数	FConvaiResultParam
GetParamType	获取参数类型	EConvaiActionParamType
GetParamAsString	将参数获取为字符串	FString
GetParamAsNumber	将参数获取为数字	float
GetParamAsBool	将参数获取为布尔值	bool
GetParamAsRef	将参数获取为引用	FConvaiObjectEntry
GetParamAsByte	将参数获取为字节	uint8
HasParam	有参数	bool

编辑器实用工具

这些仅供编辑器使用的工具可为常见的动作设置任务生成脚手架。它们不是 Blueprint 节点。

实用工具	在哪里找到它	用途
创建 Convai 动作处理器	在角色 Blueprint 中右键单击 事件图表	生成一个 事件（在事件图中） 或 函数（新函数图） 一个以已声明动作命名的处理程序，并带有一个 FConvaiResultAction 输入和一个 Handle Action Completion 调用。
Setup Convai Pawn Movement	在 内容浏览器 → Convai	为默认移动动作配置 Pawn 移动和导航默认值。

UConvaiChatbotComponent — 动作队列函数

所有函数都位于类别 Convai | 操作.

函数	Parameters	返回	说明
HandleActionCompletion	IsSuccessful, bAutoReport, ShouldRespond, AdditionalNote, Delay	void	报告结果；推进或清空队列。
AbortActionSequence	EventText, ShouldRespond	void	清空队列，并可选择通知 Convai。
IsActionsQueueEmpty	—	bool	true 当没有排队动作时。BlueprintPure。
ClearActionQueue	—	void	丢弃所有排队动作而不报告。
FetchFirstAction	输出 ConvaiResultAction	bool	读取（但不移除）队列前端项。BlueprintPure。
AddAction	动作：FConvaiAction	void	添加单个模板；在下一次会话中生效。
AddActions	动作：TArray<FConvaiAction>	void	一次添加多个模板；在下一次会话中生效。
AddActionByName	名称：FString	void	便捷方式：按名称添加一个无描述/无参数的动作。
RemoveAction	名称：FString	void	按名称移除（区分大小写）。
RemoveActions	名称：TArray<FString>	void	按名称移除多个。
ClearActions	—	void	移除所有动作模板。
AddObject	对象，bFlushImmediately	void	向本地环境添加单个对象；在适用时会发送实时场景上下文更新。
AddObjects	对象，bFlushImmediately	void	一次向本地环境添加多个条目。
RemoveObject	对象名称，bFlushImmediately	void	按名称移除。
RemoveObjects	对象名称，bFlushImmediately	void	按名称移除多个。
ClearObjects	bFlushImmediately	void	清除所有对象。
AddCharacter	角色，bFlushImmediately	void	向本地环境添加单个角色条目。
AddCharacters	角色，bFlushImmediately	void	一次向本地环境添加多个角色条目。
RemoveCharacter	角色名称，bFlushImmediately	void	按名称移除。
RemoveCharacters	角色名称，bFlushImmediately	void	按名称移除多个。
ClearCharacters	bFlushImmediately	void	清除所有角色。
SetObjectInAttention	AttentionObject、Text、ShouldRespond、bFlushImmediately	void	设置注意力槽位（显式来源）。
TrySetObjectInAttentionFromGaze	AttentionObject、Text、ShouldRespond、bFlushImmediately	bool	受凝视门控的设置器；返回 false 当槽位为 Explicit 时。
TryClearObjectInAttentionFromGaze	ExpectedObject	bool	受凝视门控的清除；当所有权发生变化时不执行任何操作。
EnsureObjectComponentsForEnvironmentObjects	—	int32	自动生成 UConvaiObjectComponent 为缺少组件的对象生成。
SetConversationPartner	伙伴，bFlushImmediately	void	设置当前对话伙伴。
GatherEnvironmentExtras (原生事件)	输出 ExtraActions，输出 ExtraObjects，输出 ExtraCharacters	void	在 Blueprint 中重写，以便在会话开始前追加额外项。

UConvaiChatbotComponent — 动作队列事件

事件	显示名称	签名
OnActionReceivedEvent_V2	On Actions Received	（ChatbotComponent、InteractingPlayerComponent、SequenceOfActions: TArray<FConvaiResultAction>）

UConvaiChatbotComponent — 会话属性（与动作相关）

属性	类型	类别	说明
bAutoFillConversationPartnerFromPlayer	bool	Convai|Session	当 true （默认），插件会在 Characters 列表中在会话开始时。手动注册伙伴时请禁用，以避免重复条目。

EConvaiAttentionSource

值	显示名称	说明
无	无	槽位为空。
显式	Explicit（Blueprint/C++）	通过直接 SetObjectInAttention 调用设置。阻止凝视。
凝视	凝视	由凝视管线设置。可被另一个凝视事件替换。

EC_RunLLMOption

控制是否 HandleActionCompletion 是位于 AbortActionSequence 触发角色的语音回复。

值	显示名称	对 HandleActionCompletion / AbortActionSequence 的影响
Auto	Auto	由 Convai 决定是否响应。
始终	始终	强制语音回复。
从不	从不	仅静默更新上下文。

相关页面

构建自定义动作处理器参数化动作排查角色动作问题