Convai 实用函数

查找跨功能的 Blueprint 帮助节点，用于查看查询、组件查找、音频实用工具、设置、诊断和命令行标志。

UConvaiUtils 是一个 UBlueprintFunctionLibrary 它向 Blueprint 暴露各种杂项辅助节点。它不需要附加到任何 Actor；所有节点都可从任何 Blueprint 图中调用。节点按 Convai Blueprint 节点搜索面板中的类别树进行分组。

本页仅记录跨功能的工具库。特定功能的 Blueprint 库记录在各自的功能参考页中：

库 / 表面	记录于
UConvaiActions （动作参数访问器）	Actions Blueprint 参考
动态上下文传输辅助	动态上下文 Blueprint 参考
超出……的情绪辅助 UConvaiChatbotComponent	Emotion Blueprint 参考
LTM 说话者和身份辅助	LTM Blueprint 参考
视线高亮小部件和 Actor	视线注意力参考

视线注视辅助

这些节点会评估玩家控制器摄像机附近已注册的 Convai 组件，并返回位于配置半径和摄像机前向角阈值内的候选项。

ConvaiGetLookedAtCharacter

类别： Convai|Utilities

返回 UConvaiChatbotComponent 玩家当前注视的角色上的。

引脚	方向	类型	描述
WorldContextObject	输入	UObject*	世界上下文（在 Blueprint 中自动连线）。
PlayerController	输入	APlayerController*	用其摄像机朝向来确定注视方向的控制器。
半径	输入	float	从摄像机位置开始的世界单位搜索半径。
平面视图	输入	bool	当 true，仅使用水平平面角度（忽略垂直俯仰）。
包含的角色	输入	TArray<UObject*>	可选允许列表——仅考虑这些对象。传入空数组以考虑全部。
排除的角色	输入	TArray<UObject*>	可选拒绝列表——这些对象始终会被跳过。
ConvaiCharacter	输出	UConvaiChatbotComponent*	找到的聊天机器人组件，或 nullptr 当 找到 为 false.
找到	输出	bool	true 当在……范围内找到角色时 半径.

包含的角色 和 排除的角色 自动创建它们的引用术语，因此你可以在 Blueprint 中将两者都留空，节点会搜索所有已注册的聊天机器人组件。

ConvaiGetLookedAtObjectOrCharacter

类别： Convai|Utilities

返回 FConvaiObjectEntry 从提供的列表中获取玩家当前注视的（对象或角色）。当你需要在对象和角色混合集合中检测视线注意力时使用此节点。

引脚	方向	类型	描述
WorldContextObject	输入	UObject*	世界上下文（在 Blueprint 中自动连线）。
PlayerController	输入	APlayerController*	使用其摄像机朝向的控制器。
半径	输入	float	世界单位中的搜索半径。
平面视图	输入	bool	当 true，仅使用水平平面角度。
要搜索的列表	输入	TArray<FConvaiObjectEntry>	要搜索的对象和角色列表。
找到的对象或角色	输出	FConvaiObjectEntry	匹配到的条目，或在……时返回空条目 找到 为 false.
找到	输出	bool	true 当在……范围内找到匹配项时 半径.

组件查找

这些节点在世界中查询已注册的 Convai 组件，无需直接对象引用。

ConvaiGetAllChatbotComponents

类别： Convai|Utilities

返回所有 UConvaiChatbotComponent 当前在世界中注册的实例。

引脚	方向	类型	描述
WorldContextObject	输入	UObject*	世界上下文（在 Blueprint 中自动连线）。
bOnlyConnected	输入	bool	当 true，仅返回会话处于 Connected 状态的聊天机器人。
ConvaiChatbotComponents	输出	TArray<UConvaiChatbotComponent*>	所有匹配的聊天机器人组件。
OutOwners	输出	TArray<AActor*>	所属 Actor，顺序与 ConvaiChatbotComponents.

GetFirstConvaiChatbotComponent

类别： Convai|Utilities

返回第一个 UConvaiChatbotComponent 在世界中找到的——当仅存在一个角色时的便捷快捷方式。

引脚	方向	类型	描述
WorldContextObject	输入	UObject*	世界上下文（在 Blueprint 中自动连线）。
bOnlyConnected	输入	bool	当 true，仅考虑处于 Connected 状态的聊天机器人。
返回值	输出	UConvaiChatbotComponent*	第一个匹配的组件，或 nullptr 当不存在时
OutOwner	输出	AActor*	所返回组件的所属 Actor。

ConvaiGetAllPlayerComponents

类别： Convai|Utilities

返回所有 UConvaiPlayerComponent 当前在世界中注册的实例。

引脚	方向	类型	描述
WorldContextObject	输入	UObject*	世界上下文（在 Blueprint 中自动连线）。
bOnlyConnected	输入	bool	当 true，仅返回会话状态为 Connected.
ConvaiPlayerComponents	输出	TArray<UConvaiPlayerComponent*>	所有匹配的玩家组件。
OutOwners	输出	TArray<AActor*>	所属 Actor，顺序与 ConvaiPlayerComponents.

GetFirstConvaiPlayerComponent

类别： Convai|Utilities

返回第一个 UConvaiPlayerComponent 在世界中找到的。

引脚	方向	类型	描述
WorldContextObject	输入	UObject*	世界上下文（在 Blueprint 中自动连线）。
bOnlyConnected	输入	bool	当 true，仅考虑会话状态为 Connected.
返回值	输出	UConvaiPlayerComponent*	第一个匹配的组件，或 nullptr 当不存在时
OutOwner	输出	AActor*	所返回组件的所属 Actor。

ConvaiGetAllObjectComponents

类别： Convai|Utilities

返回所有 UConvaiObjectComponent 当前在世界中注册的实例。

引脚	方向	类型	描述
WorldContextObject	输入	UObject*	世界上下文（在 Blueprint 中自动连线）。
ConvaiObjectComponents	输出	TArray<UConvaiObjectComponent*>	所有已注册的对象组件。
OutOwners	输出	TArray<AActor*>	所属 Actor，顺序与 ConvaiObjectComponents.

GetFirstConvaiObjectComponent

类别： Convai|Utilities

返回第一个 UConvaiObjectComponent 在世界中找到的。

引脚	方向	类型	描述
WorldContextObject	输入	UObject*	世界上下文（在 Blueprint 中自动连线）。
返回值	输出	UConvaiObjectComponent*	第一个匹配的组件，或 nullptr 当不存在时
OutOwner	输出	AActor*	所返回组件的所属 Actor。

设置访问器

这些节点读写当前活动的运行时设置 UConvaiSettings 实例。使用 Set* 节点所做的更改会立即生效；该值不会持久化到 .ini ，除非你单独保存项目设置。

节点	类别	类型	描述
SetAPI_Key	Convai|Settings	BlueprintCallable	覆盖用于身份验证的 API 密钥。输入： API_Key（FString）.
GetAPI_Key	Convai|Settings	BlueprintPure	将当前 API 密钥返回为 FString.
SetAuthToken	Convai|Settings	BlueprintCallable	覆盖认证令牌。输入： AuthToken（FString）.
GetAuthToken	Convai|Settings	BlueprintPure	将当前认证令牌返回为 FString.
GetTestCharacterID	Convai|Settings	BlueprintPure	返回在设置中配置的测试角色 ID。
SetCustomParam	Convai|Settings	BlueprintCallable	将键值对写入 CustomPrams 设置映射。该值通过 GetCustomParam 使用以下链：内置默认值 → CustomPrams → 命令行覆盖项。输入： 键（FString）, 值（FString）.
GetCustomParam	Convai|Settings	BlueprintPure	返回为 键 通过完整解析链解析后的值。返回 DefaultValue 当该链产生空字符串时。输入： 键（FString）, DefaultValue（FString）。返回： FString.
GetClientVersion	Convai|Settings	BlueprintPure	返回 ClientVersion 通过 CustomPrams / 命令行解析链解析得到的值。返回： FString.
GetVADSettings	Convai|Settings	BlueprintPure	返回当前的快照 FConvaiVADSettings 来自项目设置。
SetVADSettings	Convai|Settings	BlueprintCallable	覆盖活动 UConvaiSettings 实例上的 VAD 设置。保存时持久化到 .ini 。输入： InSettings（FConvaiVADSettings）.
IsAlwaysAllowVisionEnabled	Convai|Settings	BlueprintPure	返回 true 当启用“始终允许视觉”设置时。

FConvaiVADSettings 字段说明（bUseServerDefault, Confidence, StartSecs, StopSecs, MinVolume）在 数据类型和枚举.

音频辅助

StereoToMono

类别： Convai|Utilities

将立体声 WAV 字节转换，并将转换后的单声道 WAV 字节写入输出引脚。

引脚	方向	类型	描述
stereoWavBytes	输入	TArray<uint8>	原始立体声 WAV 字节数组。
monoWavBytes	输出	TArray<uint8>	生成的单声道 WAV 字节数组。

WriteSoundWaveToWavFile

类别： Convai|Utilities

将一个 USoundWave 写入到一个 .wav 磁盘文件中。

引脚	方向	类型	描述
SoundWave	输入	USoundWave*	要写入的 SoundWave 资源。
FilePath	输入	FString	输出文件的绝对路径。
返回值	输出	bool	true 成功时。

ReadWavFileAsSoundWave

类别： Convai|Utilities — BlueprintPure

读取一个 .wav 磁盘上的文件，并将其返回为一个 USoundWave.

引脚	方向	类型	描述
FilePath	输入	FString	到一个 .wav 磁盘文件中。
返回值	输出	USoundWave*	加载的 SoundWave，或 nullptr 失败时。

文件 I/O

节点	返回	描述
ReadFileAsByteArray	bool, 字节（TArray<uint8>）	读取位于 FilePath 的文件到字节数组中。返回 false 失败时。
SaveByteArrayAsFile	bool	将 字节 写入到位于 FilePath的文件中。返回 false 失败时。
ByteArrayToString	FString	将 字节 转换为 UTF-8 FString.
WriteStringToFile	bool	将 要写入的字符串 写入到位于 FilePath的文件中。返回 false 失败时。
ReadStringFromFile	bool, OutString（FString）	读取位于 FilePath 到 OutString的文件中。返回 false 失败时。

Blendshape 工具

这些节点操作 TMap<FName, float> blendshape 映射，主要用于口型同步和面部动画管线。参见 Convai 聊天机器人组件 了解将 blendshape 数据发送到角色的节点。

MapBlendshapes

类别： Convai|Blendshapes — BlueprintPure

将 blendshape 从一种命名规范或骨骼绑定映射并转换到另一种。支持按单个 blendshape 设置乘数、偏移、夹取和值覆盖。

引脚	方向	类型	描述
InputBlendshapes	输入	TMap<FName, float>	源 blendshape 映射（例如 ARKit 输出）。
BlendshapeMap	输入	TMap<FName, FConvaiBlendshapeParameters>	每个 blendshape 的转换配置。每个条目将一个源键映射到一个或多个目标名称、乘数、偏移，以及可选的夹取和覆盖值。
GlobalMultiplier	输入	float	应用于所有 blendshape，除了具有 IgnoreGlobalModifiers 设置了……的
GlobalOffset	输入	float	添加到所有 blendshape，除了具有 IgnoreGlobalModifiers 设置了……的
返回值	输出	TMap<FName, float>	已转换的 blendshape 映射，已准备好用于目标骨骼。

FConvaiBlendshapeParameters 字段说明在 数据类型和枚举.

SplitBlendshapeMapByKeys

类别： Convai|Blendshapes — BlueprintCallable （显示名称 按键拆分 Blendshape 映射)

将一个 blendshape 映射拆分为两部分：列在 SplitKeys 中的键会从 InOutOriginalMap 中移除并放入 OutSplitMap。适用于分离需要不同混合模式的面部区域。

引脚	方向	类型	描述
InOutOriginalMap	输入/输出（引用）	TMap<FName, float>	在原地修改——匹配到的键会被移除。
SplitKeys	输入	TArray<FName>	要提取的键。
OutSplitMap	输出	TMap<FName, float>	仅包含提取出的键值对。

MergeBlendshapeMaps

类别： Convai|Blendshapes — BlueprintPure （显示名称 合并 Blendshape 映射)

合并两个 blendshape 映射。当两个映射中存在相同键时，来自 OverrideMap 的值优先。

引脚	方向	类型	描述
BaseMap	输入	TMap<FName, float>	基础 blendshape 值。
OverrideMap	输入	TMap<FName, float>	用于覆盖 BaseMap 在键冲突时。
返回值	输出	TMap<FName, float>	合并后的映射。

骨骼网格辅助

GetBodyAndFaceSkeletalMeshComponents

类型： BlueprintCallable （有执行引脚） 类别： Convai|Utilities

使用骨骼名称启发式规则将一个 Actor 的骨骼网格组件拆分为身体网格和面部网格。适用于面部网格独立的 MetaHuman 风格绑定。

检测规则：

• 0 个骨骼网格组件：两个输出都为 nullptr.
• 恰好 1 个：该网格成为身体；面部为 nullptr.
• 2 个或更多：每个候选项都会根据身体关键词（“pelvis”, “hand”, “neck”，……）以及面部关键词（“eye”, “jaw”, “brow”，……）。得分最高的网格赢得对应位置。如果没有网格在身体上得分，则最浅层的骨骼网格获胜； SkelMeshes[0] 仅在没有候选项排序时使用。如果没有网格在面部上得分， FaceComponent 为 nullptr.

引脚	方向	类型	描述
Actor	输入	AActor*	要检查的 Actor。
BodyComponent	输出	USkeletalMeshComponent*	已识别的身体网格，或 nullptr.
FaceComponent	输出	USkeletalMeshComponent*	已识别的面部网格，或 nullptr.

诊断和平台节点

节点	类别	类型	返回	描述
GetPluginInfo	Convai|Utilities	BlueprintPure	找到（bool）, 版本名称, 引擎版本, 友好名称 (FString （各自）	返回指定插件的元数据。输入： PluginName（FString）.
GetPlatformInfo	Convai|Utilities	BlueprintPure	引擎版本（FString）, 平台名称（FString）	返回当前运行的引擎版本字符串和平台名称。
GetDeviceUniqueIdentifier	Convai|Utilities	BlueprintPure	FString	返回平台级唯一设备标识符。
GetStreamURL	Convai|Utilities	BlueprintPure	FString	返回从设置中解析出的流媒体 URL。
GetLLMProvider	Convai|Utilities	BlueprintPure	FString	返回已配置的 LLM 提供商标识符。
GetConnectionType	Convai|Utilities	BlueprintPure	FString	返回已配置的连接类型字符串。
GetEmotionsProvider	Convai|Utilities	BlueprintPure	FString	返回已配置的情绪提供商标识符。
IsAECEnabled	Convai|Utilities	BlueprintPure	bool	true 当在设置中启用声学回声消除时。
GetAECType	Convai|Utilities	BlueprintPure	FString	返回设置中的 AEC 类型字符串。
IsVADEnabled	Convai|Utilities	BlueprintPure	bool	true 当在设置中启用语音活动检测时。
GetVADMode	Convai|Utilities	BlueprintPure	int32	返回 VAD 激进度模式（0–3）。
IsNoiseSuppressionEnabled	Convai|Utilities	BlueprintPure	bool	true 当在设置中启用噪声抑制时。
IsGainControlEnabled	Convai|Utilities	BlueprintPure	bool	true 当在设置中启用自动增益控制时。
IsHighPassFilterEnabled	Convai|Utilities	BlueprintPure	bool	true 当在设置中启用高通音频滤波器时。
IsFaceSyncSimulateFreeze	Convai|Utilities	BlueprintPure	bool	true 当启用 FaceSync 冻结模拟调试模式时。
GetLipSyncMode	Convai|Utilities	BlueprintPure	EC_LipSyncMode	返回已配置的口型同步模式。
GetLipSyncTimeOffset	Convai|Utilities	BlueprintPure	double	返回口型同步时间偏移（秒）。
GetLipSyncAnimParamOverride	Convai|Utilities	BlueprintPure	FString	返回给定对象的口型同步动画参数覆盖字符串 键.
GetLipSyncStarvationFallback	Convai|Utilities	BlueprintPure	float	返回口型同步管线的饥饿回退持续时间（秒）。
GetConnectionProxyTTL	Convai|Utilities	BlueprintPure	float	返回连接代理生存时间（秒）。
GetPrepConnectionTTL	Convai|Utilities	BlueprintPure	float	返回预先准备的连接生存时间（秒）。
GetObjectPollIntervalSeconds	Convai|Utilities	BlueprintPure	float	返回对象组件轮询 tick 之间的间隔（秒）。
GetClientReadyRetrySecs	Convai|Utilities	BlueprintPure	float	返回等待客户端就绪信号时使用的重试间隔（秒）。
GetClientReadyTimeoutSecs	Convai|Utilities	BlueprintPure	float	返回客户端就绪握手的超时时间（秒）。
GetContextDebounceWindowDefault	Convai|Utilities	BlueprintPure	float	返回上下文更新的默认防抖窗口持续时间（秒）。
GetContextMaxDebounceWindowDefault	Convai|Utilities	BlueprintPure	float	返回上下文更新的最大防抖窗口持续时间（秒）。

EC_LipSyncMode 值记录在 数据类型和枚举.

命令行工具

UCommandLineUtils 是同一模块中的第二个 Blueprint 函数库。其节点出现在 CommandLine 类别中。使用这些节点可在运行时读取命令行参数值，用于调试覆盖和测试自动化，而无需重新编译。

节点	类型	返回	描述
GetCommandLineFlagValueAsInt	BlueprintCallable	int32	返回以下项的整数值： 标志 来自命令行。返回 DefaultValue （默认 0）当标志不存在时。
GetCommandLineFlagValueAsString	BlueprintCallable	FString	返回以下项的字符串值： 标志的文件中。返回 DefaultValue （默认 ""）当标志不存在时。
GetCommandLineFlagValueAsStringNoDefault	BlueprintCallable, BlueprintPure	FString	返回以下项的字符串值： 标志 不带默认参数。
GetCommandLineFlagValueAsDouble	BlueprintCallable, BlueprintPure	double	返回以下项的双精度值： 标志的文件中。返回 DefaultValue （默认 0.0）当标志不存在时。

连接管理

UConvaiConnectionLibrary 公开以下内容： PrepareCharacterConnection Blueprint 节点位于 Convai|Connection 类别中。它会预热角色连接，以便稍后由 StartSession；参见 会话生命周期 了解连接工作流程，以及 数据类型和枚举 关于 EC_PrepResult 值。

引脚	方向	类型	描述
WorldContextObject	输入	UObject*	世界上下文（在 Blueprint 中自动连线）。
CharacterID	输入	FString	要预热的角色 ID。
PrepTTLOverrideSeconds	输入	float	可选的预热窗口持续时间。默认 0.0 使用项目设置；正值会被限制为 1–600 秒。
返回值	输出	EC_PrepResult	预热请求的结果。

相关参考

聊天机器人组件是 blendshape 和 look-at 工具节点的主要使用者；播放器组件使用组件查找和麦克风辅助函数。

Convai Chatbot 组件Convai Player 组件