Convai Toolset 参考

已连接编码代理可调用的七个编辑器操作参考，用于设置 Convai 角色、玩家和动作。

Convai 工具集注册了七个 AICallable 编辑器操作，使用引擎的 ToolsetRegistry 插件，分布在 UConvaiSetupToolset 和 UConvaiActionToolset 在 Source/ConvaiToolsetGated/Private/ConvaiToolset.h。需要 Unreal Engine 5.8 或更高版本 以及一个 编辑器 构建——该 ConvaiToolset 模块在任何非 Editor 目标上都会抛出构建错误，而其受条件限制的部分在 UE 5.8 以下会完全编译排除。

这七个操作是 AICallable，而不是 BlueprintCallable。连接的编码代理通过引擎的 MCP 服务器调用它们——它们不会出现在 Blueprint 节点面板中，任何 Blueprint 图表都无法调用它们。

全部七个操作

Action	工具集类	作用
SetupConvaiCharacter	UConvaiSetupToolset	将角色 Blueprint 转换为可对话的 Convai 角色
SetupConvaiPlayer	UConvaiSetupToolset	向玩家 Pawn Blueprint 添加 Convai 玩家组件
SetupConvaiPawnMovement	UConvaiSetupToolset	为角色/pawn Blueprint 设置经过 Convai 调优的移动
AddNavMeshVolumeForCurrentLevel	UConvaiSetupToolset	生成一个与当前关卡大小匹配的导航网格边界体积
SetBlueprintPropertyAndPropagate	UConvaiSetupToolset	设置一个 Blueprint 属性，并将其传播到已放置的关卡实例
AddConvaiAction	UConvaiActionToolset	向聊天机器人的操作列表追加一个带参数的操作
CreateConvaiActionHandler	UConvaiActionToolset	为指定操作合成一个 Blueprint 事件处理器

每个操作都会返回一条可读的状态字符串，说明它更改了什么，并且是幂等的——使用相同输入再次调用时，会复用现有组件或值，而不是重复创建。

SetupConvaiCharacter

将角色 Blueprint 转换为可对话的 Convai 角色。添加 BP_ConvaiChatbotComponent 以及一个原生 ConvaiFaceSyncComponent 如果其中任一缺失，则设置聊天机器人角色 ID，并启用 bAutoFillConversationPartnerFromPlayer，将面部同步口型同步模式设置为 MetaHuman blendshape 模式（BS_MHA），启用插值，并将 Convai MetaHuman 面部和身体动画 Blueprints 分配给名为 Face 和 Body的骨骼网格组件。编译并保存 Blueprint。

参数	类型	默认值	描述
CharacterBlueprintPath	FString	—（必填）	MetaHuman/角色 Blueprint 的对象路径，例如 /Game/NPCs/BP_Guard
CharacterId	FString	—（必填）	要分配给聊天机器人组件的 Convai 后端 Character ID

返回一条可读的状态字符串，描述已更改的内容。

SetupConvaiPlayer

将 Convai 玩家组件添加到玩家的 Pawn Blueprint——玩家所控制的角色——使玩家可以与 Convai 角色对话。添加 BP_ConvaiPlayerComponent 如果缺失，则编译并保存 Blueprint。

参数	类型	默认值	描述
PlayerBlueprintPath	FString	—（必填）	玩家 Pawn Blueprint（被控制/可操控的角色，拥有摄像机和输入）的对象路径，例如 /Game/FirstPerson/Blueprints/BP_FirstPersonCharacter

返回一条可读的状态字符串，描述已更改的内容。

SetupConvaiPawnMovement

为角色/pawn Blueprint 设置经过 Convai 调优的移动，使其能够导航。如果该 Blueprint 的父类只是一个普通的 AActor，则会重新指定父类为 APawn。一个 UFloatingPawnMovement 组件，如果尚未存在或继承，则添加该组件，并应用 Convai 移动默认值（MaxSpeed=375, Acceleration=200, Deceleration=250, TurningBoost=3，以及导航路径跟随默认值）。对于基于 Character 的 Blueprints，继承的 CharacterMovementComponent 则会改为调整为等效的行走速度和导航代理默认值。安全时编译 Blueprint 并保存。

参数	类型	默认值	描述
CharacterBlueprintPath	FString	—（必填）	角色/pawn Blueprint 的对象路径，例如 /Game/NPCs/BP_Guard

返回一条可读的状态字符串，描述已更改的内容。

AddNavMeshVolumeForCurrentLevel

在当前编辑器关卡中生成一个 NavMeshBoundsVolume ，使 Convai 角色可以进行路径查找。默认情况下，该体积居中并调整大小以覆盖关卡中所有 Actor 的合并边界。生成体积后会重建导航。

参数	类型	默认值	描述
位置	TOptional<FVector>	未设置	体积的可选世界空间中心。若未设置，则使用关卡边界中心
范围	TOptional<FVector>	未设置	体积盒的可选半范围（厘米）。若未设置，则根据关卡边界并加上边距推导

返回一条可读的状态字符串，包含最终体积位置和范围。

SetBlueprintPropertyAndPropagate

设置 Blueprint 上的一个属性，并将新值传播到每个已放置且仍保留旧值的关卡实例，同时保留每个实例的覆盖。既可处理组件模板属性（在其中传入组件变量名 ComponentName），也可处理 Actor/Blueprint 级属性（将 ComponentName 留空）。当更改也必须影响已经放置在关卡中的角色时，请使用此方法，而不是直接设置属性并编译——引擎自带的属性设置工具或普通的 Blueprint 编译都不会将模板或类默认对象的编辑传播到已放置实例。该值通过属性自身的文本导入器解析，因此任何类型都可以： 300.0 （float）， true （bool）， 你好 （字符串/名称）， （X=0,Y=0,Z=300） （向量/结构体）， /Game/P.A （对象）。编译并保存 Blueprint。

参数	类型	默认值	描述
BlueprintPath	FString	—（必填）	Blueprint 的对象路径，例如 /Game/NPCs/BP_Guard
ComponentName	FString	—（必填，可为空）	该组件的 Blueprint 变量名，例如 ProximitySphere。对于 Actor/Blueprint 级属性请留空
PropertyName	FString	—（必填）	属性名称，例如 SphereRadius （组件）或 MyVar （Actor 级）
ValueAsString	FString	—（必填）	Unreal 文本形式的新值，由属性导入器解析

返回一条可读的状态字符串，包含已更新的已放置实例数量。

通过以下方式编辑属性 SetBlueprintPropertyAndPropagate 从一开始。先前通过原始属性设置而已失同步的值，在传播逻辑看来会像是每实例覆盖，因此不会被更新。

AddConvaiAction

将一个带参数的操作追加到聊天机器人的 Environment 操作列表中。定位 BP_ConvaiChatbotComponent （或任何 UConvaiChatbotComponent）于给定 Blueprint 上，启用 EnvironmentData.bEnableActions，并添加一个 FConvaiAction ，其名称、描述和参数按给定内容设置，同时保留现有操作。若存在同名操作，则会原地替换。编译并保存 Blueprint。这些操作会在聊天机器人下次连接时生效——它们准备的是下一次会话，而不是当前在线会话。

参数	类型	默认值	描述
CharacterBlueprintPath	FString	—（必填）	拥有聊天机器人组件的 Blueprint 的对象路径
ActionName	FString	—（必填）	规范化操作名称，例如 Wave, 拾取, 说。应与处理器事件名称匹配
描述	FString	—	该操作作用的人类可读描述
Parameters	TArray<FConvaiToolsetActionParam>	—	调用时代理应填写的已声明参数有序列表（名称、描述、类型和可选项）

FConvaiToolsetActionParam 镜像了面向代理的以下子集： FConvaiActionParam:

字段	类型	描述
名称	FString	代理看到的占位符名称，例如 文本, destination, 秒数
描述	FString	可选的人类可读参数含义描述
类型	EConvaiActionParamType	该值的解释方式： String, Number, Reference （根据聊天机器人已知的 Objects/Characters 解析）， Bool, Enum，或 Auto （默认，在解析时推断）
Choices	TArray<FString>	对于固定选项集参数，允许的值，与以下项一起使用： Type=String. AddConvaiAction 无法提供一个 UEnum，因此一个 Type=Enum 参数会被强制转换为 String ，其选项列在 Choices

返回一条可读的状态字符串，描述已更改的内容。

CreateConvaiActionHandler

在 Blueprint 的事件图中合成一个 Convai 操作处理器。创建一个名称完全为以下内容的 Custom Event： ActionName ，并带有一个类型为以下内容的单个输入引脚： FConvaiResultAction，并将其执行输出连接到一个 HandleActionCompletion 对 Blueprint 的聊天机器人组件的调用；如果存在，则自动从组件变量连接聊天机器人 self 引脚。这是以下内容在运行时的契约： UConvaiChatbotComponent::TriggerNamedBlueprintAction 所期望的。编译 Blueprint。

参数	类型	默认值	描述
BlueprintPath	FString	—（必填）	要添加处理器的 Blueprint 的对象路径
ActionName	FString	—（必填）	精确的操作名称；创建的 Custom Event 也使用相同名称

成功时返回创建的事件名称，或返回以前缀以下内容开头的错误字符串： 错误：.

下一步

AI 编码助手AI 编码助手快速入门Convai AgentSkills