For the complete documentation index, see llms.txt. This page is also available as Markdown.

动作 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 的输出 解析目标位置 替代。

ObjectReference 替代了早期测试版使用的移动目标枚举和边界标志: 整个 Actor 已经隐含会在对象边界处停止,因此不需要单独的标志。如果项目仍在读取旧字段,升级说明见于 迁移到 4.0.0-beta.27.

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.

连接 目标 Actor 和 Destination 直接接入一个 AI Move To 节点——无需分支。 目标 Actor 是 null 仅当目标是固定位置时(移动点获胜,或条目引用了组件)才会如此,因此 AI Move To 会落入 Destination 会自动处理。

输入:

引脚
类型
备注

条目

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 触发角色的语音回复。

值
显示名称
对 HandleActionCompletion / AbortActionSequence 的影响

自动

自动

由 Convai 决定是否响应。

始终

始终

强制发出语音回复。

从不

从不

仅静默更新上下文。

相关页面

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

最后更新于

这有帮助吗?