动作 Blueprint 参考
用于支持 Unreal Engine 中 Convai 角色动作的 Blueprint 结构体、枚举、事件和队列函数的参考。
本页是构成 Convai Unreal Engine 插件中角色动作 API 的结构体、枚举、事件和函数的完整参考。除非另有说明,所有项目都可在 Blueprint 中访问。
FConvaiEnvironmentData
存储在 Environment 属性,位于 UConvaiChatbotComponent中的结构体。序列化为 action_config 于会话开始时。
bEnableActions
bool
true
主开关。通过 启用动作 Details 面板中的
动作
TArray<FConvaiAction>
四个默认值
动作模板。
对象
TArray<FConvaiObjectEntry>
[]
场景对象目标。
角色
TArray<FConvaiObjectEntry>
[]
场景角色目标。
CurrentAttentionObject
FConvaiObjectEntry
空
通过 SetObjectInAttention.
FConvaiAction
控制。动作模板结构体。在编辑时定义于 动作 数组中 FConvaiEnvironmentData.
名称
FString
""
规范动作名称。必须与 Blueprint 处理函数名称匹配,包括空格。Unreal 会不区分大小写地解析处理函数名称。
说明
FString
""
发送给 Convai 的可选提示。
参数
TArray<FConvaiActionParam>
[]
有序的类型化参数。
bWaitForBotSpeech
bool
false
将新序列中的第一个动作延迟到语音开始、语音结束、无响应触发或等待超时结束为止。
DelayAfterBotSpeechSec
float
0.0
在语音条件解析后追加的额外延迟。
FConvaiActionParam
参数模板。每个占位符对应一个条目,位于 FConvaiAction.
名称
FString
""
占位符名称。映射到 参数 中的键 FConvaiResultAction.
说明
FString
""
给 Convai 的可选提示。
类型
EConvaiActionParamType
自动
声明的类型。参见下方类型表。
连接符
FString
""
在此参数之前渲染的连接文本,例如 "on".
选项
TArray<FString>
[]
固定选项列表。当 Type == Enum 时变灰.
枚举类型
UEnum*
null
当以下情况时必需 Type == Enum 时变灰.
EConvaiActionParamType
自动
自动
推断:引用 > 数字 > 布尔 > 字符串。
引用
Actor 引用
解析到 对象 / 角色 按精确的已注册名称进行解析。
字符串
字符串
原始字符串。
数值
数值
float 通过 Atof.
布尔值
布尔值
"true"/"yes"/"1" → true.
枚举
枚举
与 枚举类型 显示名称匹配;枚举值存储在 ByteValue.
FConvaiResultAction
传递给动作处理器的结构体。每个已分发动作对应一个。
操作
FString
模板匹配后得到的规范动作名称。
ActionString
FString
来自 Convai 的未经处理的原始动作字符串。
参数
TMap<FString, FConvaiResultParam>
参数名 → 已解析值 的映射。可使用 获取参数 / 以 X 形式获取参数.
bWaitForBotSpeech
bool
在解析时从匹配的模板复制。
DelayAfterBotSpeechSec
float
从匹配的模板复制。
RelatedObjectOrCharacter
FConvaiObjectEntry
已弃用。 镜像第一个 Reference 类型参数。使用 GetParamAsRef 在 参数 映射中读取参数值。
ConvaiExtraParams
FConvaiExtraParams
已弃用。 镜像第一个数字/文本/命名参数。使用 GetParamAs* 在 参数 映射中读取参数值。
FConvaiResultParam
一个已解析的参数值。无论声明类型如何,所有字段都会尽力填充。
类型
EConvaiActionParamType
声明或推断的类型。
StringValue
FString
原始值。始终填充。
NumberValue
float
Atof(StringValue). 0 如果不是数字。
BoolValue
bool
true 如果 "true", "yes",或 "1".
RefValue
FConvaiObjectEntry
已解析的 Actor 引用。如果环境中没有匹配项则为空。
ByteValue
uint8
匹配到的枚举值,当 Type == Enum 时变灰 和 枚举类型 已设置; 0 否则。
FConvaiObjectEntry
描述环境中的场景对象或角色。
名称
FString
""
唯一标签。必须在所有已注册对象中保持唯一。
引用
TWeakObjectPtr<AActor>
null
活动的 Actor。如果该 Actor 被销毁,该条目仍可保留其名称,而 解析目标位置 会报告失败。
说明
FString
""
供 Convai 使用的自然语言描述。
ObjectReference
EConvaiObjectReference
整个 Actor
显示名称 对象为. 整个 Actor 或 特定组件。控制视线/注意力范围,以及在以下情况下使用的移动回退: MovementPoints 为空。
组件名称
FString
""
子组件过滤器。用于当 ObjectReference 是 特定组件.
Socket 或骨骼名称
FName
无
匹配组件上的可选插槽或骨骼。
接受半径
float
150.0
停止距离,单位 cm。
MovementPoints
TArray<FConvaiMovementPoint>
[]
命名的设计器自定义目的地。当启用一个或多个点时,它们会替换 ObjectReference 作为移动目标;解析器会选择路径最短且可到达的点。
bFallbackToObjectWhenPointsUnreachable
bool
false
显示名称 将对象用作回退。当所有 MovementPoints 条目都不可达时,改为直接走到对象本身。
ResolvedComponent
TWeakObjectPtr<USceneComponent>
null
瞬态、只读 ——由 ResolveGoalLocation.
OptionalPositionVector
FVector
(0,0,0)
已弃用。 使用 Destination 的输出 解析目标位置 替代。
EConvaiObjectReference
来源: ConvaiDefinitions.h:36.
WholeActor
整个 Actor
视线匹配该 Actor 的任意原语组件。移动回退: AI Move To 使用 引用 直接到达,并停在该 Actor 的边界处。
SpecificComponent
特定组件
视线只匹配命名组件。移动回退以该组件(或插槽)的世界位置为目标。
解析目标位置
位于 UConvaiActions (类别 Convai | Action API).
将一个 FConvaiObjectEntry 解析为一个 AI Move To 节点所需的输入,并可选地运行 NavMesh 路径查询。来源: ConvaiActionUtils.h:262-280.
输入:
条目
FConvaiObjectEntry (引用)
要解析的对象。
源 Actor
AActor*
可选。提供后,还会计算可达性、到达和路径输出。
输出:
目标 Actor
AActor*
连到 AI Move To的 目标 Actor 引脚。 null 当目标是一个位置或解析失败时。
Object Actor (高级)
AActor*
Entry.Ref,在存活期间始终填充。用于非移动用途(附加特效、查询)——不要把它接到 AI Move To.
输出目标组件
USceneComponent*
已解析的子组件,当 ObjectReference 是 特定组件 和 组件名称 已匹配。
Destination
FVector
连到 AI Move To的 Destination 引脚。获胜的移动点,或组件/插槽位置,或 引用的原点。
输出接受半径
float
镜像 Entry.AcceptanceRadius。转发到 AI Move To.
使用目标位置 (高级)
bool
true 当目标是一个位置时——也就是恰好当 目标 Actor 是 null。仅对显式分支的图有需要。
bOut Success
bool
true 当 引用 处于存活状态且解析成功。调用之前务必先对此分支。 AI Move To.
bOut 已到达
bool
true 当 源 Actor 已经到达目标。跳过 AI Move To 当 true.
bOut 可达
bool
true 当从 源 Actor 到达目标且在容差范围内时。
输出路径终点
FVector
路径查询的最终导航点。
输出路径点
TArray<FVector>
用于调试可视化的完整导航路径。
输出目标行进距离
float
到所选目标的 Nav 路径长度,单位为 Unreal 单位; 0 当未计算路径或已经在目标处时。
输出移动点索引
int32
哪个 MovementPoints 条目胜出; -1 当 ObjectReference 而是由其解析出目标。
Convai Move To
异步 Blueprint 节点(latent)。 UConvaiMoveToProxy::ConvaiMoveTo,类别 Convai | 移动。来源: Actions/ConvaiMoveToTask.h:244,263.
将一个 Actor 移动到一个 FConvaiObjectEntry 目的地——整个 Actor、组件/插槽,或作者定义的移动点——无需手动 解析目标位置 → AI Move To 接线。
正在移动的 Actor
AActor*
要移动的 Actor。
Destination
FConvaiObjectEntry
目标条目。
bLockAILogic (高级)
bool
默认 false.
成功 (执行)
—
触发于 已到达 或 已在目的地.
Failed (执行)
—
触发于任何其他 EConvaiMoveToResultCode.
结果代码
EConvaiMoveToResultCode
见下文。
附加说明
FString
可以安全地传递给 Handle Action Completion 或回说给玩家。
EConvaiMoveToResultCode
来源: Actions/ConvaiMoveToTask.h:18.
已到达
已到达
AlreadyAtDestination
已在目的地
UnknownDestination
未知目的地
不可达
不可达
InvalidCharacter
无效角色
MissingController
缺少 AI 控制器
MissingMovementComponent
缺少移动组件
MissingPathFollowingComponent
缺少路径跟随组件
MissingNavigationData
缺少导航数据
MoveFailed
移动失败
Convai 护送
异步 Blueprint 节点(latent)。 UConvaiEscortProxy::ConvaiEscort,类别 Convai | 移动。来源: Actions/ConvaiEscortToTask.h:221,239.
将护送 Actor 移动到目的地,同时被护送角色跟随;当其落后时会暂停,以便被护送角色跟上。
执行护送的 Actor
AActor*
引领护送并拥有 Convai 聊天机器人 用于跟随提示。
被护送角色
FConvaiObjectEntry
正在被护送的角色。
Destination
FConvaiObjectEntry
目标条目。
成功 (执行)
—
触发于 已到达 或 已在目的地.
Failed (执行)
—
触发于任何其他 EConvaiEscortResultCode.
结果代码
EConvaiEscortResultCode
见下文。
附加说明
FString
可以安全地传递给 Handle Action Completion.
打包好的 BP_ConvaiChatbotComponent 便捷 Blueprint 自带一个 护送 动作,开箱即用。
EConvaiEscortResultCode
来源: Actions/ConvaiEscortToTask.h:21.
已到达
已到达
AlreadyAtDestination
已在目的地
EscorteeUnavailable
角色不可用
DestinationUnavailable
目的地不可用
InvalidGuideSetup
无效护送设置
MovementFailed
移动失败
UConvaiActions — 参数访问器
Blueprint 函数库(类别 Convai | Action API)。所有函数都接受 const FConvaiResultAction&.
GetFirstParam
获取第一个参数
FConvaiResultParam
GetParam
获取参数
FConvaiResultParam
GetParamType
获取参数类型
EConvaiActionParamType
GetParamAsString
获取参数为字符串
FString
GetParamAsNumber
获取参数为数值
float
GetParamAsBool
获取参数为布尔值
bool
GetParamAsRef
GetParamAsRef
FConvaiObjectEntry
GetParamAsByte
获取参数为字节
uint8
HasParam
是否有参数
bool
编辑器工具
这些仅编辑器可用的工具用于搭建常见的动作设置任务。它们不是 Blueprint 节点。
Create Convai Action Handler
在角色 Blueprint 中右键单击 事件图表
生成一个 事件(在事件图表上) 或 函数(新建函数图) 处理器,名称与已声明动作相对应,并带有一个 FConvaiResultAction 输入和一个 Handle Action Completion 调用。
设置 Convai Pawn 移动
在 内容浏览器 → Convai
中右键单击角色 Blueprint。配置 Pawn 移动和导航默认值,用于默认移动动作。
UConvaiChatbotComponent — 动作队列函数
所有函数都在类别 Convai | 动作.
HandleActionCompletion
IsSuccessful, bAutoReport, ShouldRespond, AdditionalNote, 延迟
void
报告结果;推进或清空队列。
AbortActionSequence
事件文本, ShouldRespond
void
清空队列并可选地通知 Convai。
CancelCurrentActionPlan
—
void
显示名称 Cancel Current Action Plan。协作式取消当前计划:丢弃排队动作,并向活动的 Blueprint 处理器提供一个可选事件,名称严格为 Cancel <Action Name> 以及原始的 FConvaiResultAction。重复调用只会请求一次取消。
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
移除所有动作模板。
添加对象
Object, bFlushImmediately
void
向本地环境添加单个对象;在适用时会发送实时场景上下文更新。
AddObjects
Objects, bFlushImmediately
void
一次向本地环境添加多个条目。
RemoveObject
ObjectName, bFlushImmediately
void
按名称移除。
RemoveObjects
ObjectNames, bFlushImmediately
void
按名称移除多个。
ClearObjects
bFlushImmediately
void
清除所有对象。
AddCharacter
Character, bFlushImmediately
void
向本地环境添加单个角色条目。
AddCharacters
Characters, bFlushImmediately
void
一次向本地环境添加多个角色条目。
RemoveCharacter
CharacterName, bFlushImmediately
void
按名称移除。
RemoveCharacters
CharacterNames, bFlushImmediately
void
按名称移除多个。
ClearCharacters
bFlushImmediately
void
清除所有角色。
SetObjectInAttention
AttentionObject, Text, ShouldRespond, bFlushImmediately
void
设置注意力槽位(显式来源)。
TrySetObjectInAttentionFromGaze
AttentionObject, Text, ShouldRespond, bFlushImmediately
bool
基于视线的设置器;当槽位为 Explicit 时返回 false 。
TryClearObjectInAttentionFromGaze
预期对象
bool
基于视线的清除;如果所有权已变更则不执行任何操作。
为环境对象确保对象组件
—
int32
自动生成 UConvaiObjectComponent 用于没有组件的对象。
SetConversationPartner
Partner, bFlushImmediately
void
设置当前对话伙伴。
GatherEnvironmentExtras (原生事件)
输出 ExtraActions、输出 ExtraObjects、输出 ExtraCharacters
void
可在 Blueprint 中重写,在会话开始前附加额外内容。
UConvaiChatbotComponent — 动作队列事件
OnActionReceivedEvent_V2
On Actions Received
(ChatbotComponent, InteractingPlayerComponent, SequenceOfActions: TArray<FConvaiResultAction>)
OnBotTurnCompletedEvent
机器人回合完成
(ChatbotComponent, ResponseId: FString, bWasInterrupted: bool, bWasAborted: bool, ErrorReason: FString)
机器人回合完成 是 Convai 报告的权威响应生命周期终点——触发时,本地音频和面部动画可能仍在收尾。类别 Convai。用它来判断一轮是否真正结束,再决定是否推进依赖动作的逻辑,而不要仅依赖本地语音结束事件。
UConvaiChatbotComponent — 会话属性(与动作相关)
bAutoFillConversationPartnerFromPlayer
bool
Convai|Session
当 true (默认)时,插件会将对话伙伴自动注册到 角色 会话开始时的列表中。手动注册对话伙伴时请禁用,以避免重复条目。
bEnableCancelActionPlanAction
bool
Convai|Actions|Experimental
显示名称 启用取消动作计划。默认 false。添加保留的 取消动作计划 控制动作,使 Convai 能调用 Cancel Current Action Plan 当玩家改道或放弃正在进行的计划时。将在下一次会话开始时生效;需要 启用动作.
UConvaiPlayerComponent — 是否在说话
IsSpeaking — UFUNCTION(BlueprintPure, BlueprintCallable, Category = "Convai", meta = (DisplayName = "是否在说话")),返回 bool。来源: ConvaiPlayerComponent.h:246.
true 在玩家说话期间。服务器的语音活动事件是主要信号;非空的部分转写或最终转写可补足缺失边界,短暂的实时停止宽限可吸收过早或重复的停止数据包。这是本地会话状态——不复制。请在动作处理程序中使用它,以避免在移动或交互动作仍在处理中时打断玩家说话。
EConvaiAttentionSource
无
无
槽位为空。
显式
显式(蓝图/C++)
由直接 SetObjectInAttention 调用设置。阻止注视。
凝视
凝视
由注视管线设置。可被另一个注视事件替换。
EC_RunLLMOption
控制是否 HandleActionCompletion 和 AbortActionSequence 触发角色的语音回复。
自动
自动
由 Convai 决定是否响应。
始终
始终
强制发出语音回复。
从不
从不
仅静默更新上下文。
相关页面
构建自定义动作处理器参数化动作排查角色动作问题最后更新于
这有帮助吗?