> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-utility-functions.md).

# Convai 工具函数

查找用于凝视查询、组件查找、音频工具、设置、诊断和命令行标志的跨领域 Blueprint 帮助节点。

`UConvaiUtils` 是一个 `UBlueprintFunctionLibrary` 它向 Blueprint 暴露各种辅助节点。它不需要附加到一个 `Actor`；所有节点都可从任何 Blueprint 图中调用。节点按以下方式分组在 **Convai** Blueprint 节点搜索面板的分类树中。

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

| 库 / 接口                                 | 记录于                                                                                                                                                 |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UConvaiActions` （动作参数访问器）             | [动作 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-reference.md)          |
| 动态上下文传输辅助函数                            | [动态上下文 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-blueprint-reference.md) |
| 除……之外的情绪辅助函数 `UConvaiChatbotComponent` | [情绪 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/emotion/emotion-blueprint-reference.md)                    |
| LTM 说话者和身份辅助函数                         | [LTM Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/long-term-memory/ltm-blueprint-reference.md)              |
| 注视高亮部件和 Actor                          | [凝视关注参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-reference.md)                         |

### 注视辅助函数

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

#### `ConvaiGetLookedAtCharacter`

类别： `Convai|Utilities`

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

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

{% hint style="info" %}
`包含的角色` 和 `排除的角色` 自动创建其引用术语，因此你可以在 Blueprint 中将两者都留空，节点会搜索所有已注册的聊天机器人组件。
{% endhint %}

#### `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`，仅返回会话处于 `已连接` 状态的聊天机器人。               |
| `ConvaiChatbotComponents` | 输出 | `TArray<UConvaiChatbotComponent*>` | 所有匹配的聊天机器人组件。                                  |
| `输出拥有者`                   | 输出 | `TArray<AActor*>`                  | 拥有它们的 Actor，顺序与……相同 `ConvaiChatbotComponents`. |

#### `GetFirstConvaiChatbotComponent`

类别： `Convai|Utilities`

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

| 引脚                   | 方向 | 类型                         | 说明                          |
| -------------------- | -- | -------------------------- | --------------------------- |
| `WorldContextObject` | 输入 | `UObject*`                 | 世界上下文（在 Blueprint 中自动连接）。   |
| `bOnlyConnected`     | 输入 | `bool`                     | 当 `true`，仅考虑处于 `已连接` 状态时。   |
| `返回值`                | 输出 | `UConvaiChatbotComponent*` | 第一个匹配的组件，或 `nullptr` 当不存在时。 |
| `输出拥有者`              | 输出 | `AActor*`                  | 所返回组件的拥有 Actor。             |

#### `ConvaiGetAllPlayerComponents`

类别： `Convai|Utilities`

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

| 引脚                       | 方向 | 类型                                | 说明                                            |
| ------------------------ | -- | --------------------------------- | --------------------------------------------- |
| `WorldContextObject`     | 输入 | `UObject*`                        | 世界上下文（在 Blueprint 中自动连接）。                     |
| `bOnlyConnected`         | 输入 | `bool`                            | 当 `true`，仅返回其会话状态为 `已连接`.                     |
| `ConvaiPlayerComponents` | 输出 | `TArray<UConvaiPlayerComponent*>` | 所有匹配的玩家组件。                                    |
| `输出拥有者`                  | 输出 | `TArray<AActor*>`                 | 拥有它们的 Actor，顺序与……相同 `ConvaiPlayerComponents`. |

#### `GetFirstConvaiPlayerComponent`

类别： `Convai|Utilities`

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

| 引脚                   | 方向 | 类型                        | 说明                          |
| -------------------- | -- | ------------------------- | --------------------------- |
| `WorldContextObject` | 输入 | `UObject*`                | 世界上下文（在 Blueprint 中自动连接）。   |
| `bOnlyConnected`     | 输入 | `bool`                    | 当 `true`，仅考虑其会话状态为 `已连接`.   |
| `返回值`                | 输出 | `UConvaiPlayerComponent*` | 第一个匹配的组件，或 `nullptr` 当不存在时。 |
| `输出拥有者`              | 输出 | `AActor*`                 | 所返回组件的拥有 Actor。             |

#### `ConvaiGetAllObjectComponents`

类别： `Convai|Utilities`

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

| 引脚                       | 方向 | 类型                                | 说明                                            |
| ------------------------ | -- | --------------------------------- | --------------------------------------------- |
| `WorldContextObject`     | 输入 | `UObject*`                        | 世界上下文（在 Blueprint 中自动连接）。                     |
| `ConvaiObjectComponents` | 输出 | `TArray<UConvaiObjectComponent*>` | 所有已注册的对象组件。                                   |
| `输出拥有者`                  | 输出 | `TArray<AActor*>`                 | 拥有它们的 Actor，顺序与……相同 `ConvaiObjectComponents`. |

#### `GetFirstConvaiObjectComponent`

类别： `Convai|Utilities`

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

| 引脚                   | 方向 | 类型                        | 说明                          |
| -------------------- | -- | ------------------------- | --------------------------- |
| `WorldContextObject` | 输入 | `UObject*`                | 世界上下文（在 Blueprint 中自动连接）。   |
| `返回值`                | 输出 | `UConvaiObjectComponent*` | 第一个匹配的组件，或 `nullptr` 当不存在时。 |
| `输出拥有者`              | 输出 | `AActor*`                 | 所返回组件的拥有 Actor。             |

### 设置访问器

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

| 节点                           | 类别                 | 类型                  | 说明                                                                                                                                   |
| ---------------------------- | ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `SetAPI_Key`                 | `Convai\|Settings` | `BlueprintCallable` | 覆盖用于身份验证的 API 密钥。输入： `API_Key (FString)`.                                                                                            |
| `GetAPI_Key`                 | `Convai\|Settings` | `蓝图纯函数`             | 将当前 API 密钥返回为 `FString`.                                                                                                             |
| `SetAuthToken`               | `Convai\|Settings` | `BlueprintCallable` | 覆盖身份验证令牌。输入： `AuthToken (FString)`.                                                                                                  |
| `GetAuthToken`               | `Convai\|Settings` | `蓝图纯函数`             | 将当前身份验证令牌返回为 `FString`.                                                                                                              |
| `GetTestCharacterID`         | `Convai\|Settings` | `蓝图纯函数`             | 返回在设置中配置的测试角色 ID。                                                                                                                    |
| `SetCustomParam`             | `Convai\|Settings` | `BlueprintCallable` | 将一个键值对写入 `CustomPrams` 设置映射。该值由以下方式解析： `GetCustomParam` 使用以下链路：内置默认值 → `CustomPrams` → 命令行覆盖。输入： `Key (FString)`, `Value (FString)`. |
| `GetCustomParam`             | `Convai\|Settings` | `蓝图纯函数`             | 返回以下项的解析值： `键` 使用完整解析链。若解析链的结果为空字符串，则返回 `DefaultValue` 。输入： `Key (FString)`, `DefaultValue (FString)`。返回： `FString`.                 |
| `GetClientVersion`           | `Convai\|Settings` | `蓝图纯函数`             | 返回 `ClientVersion` 通过以下方式解析的值： `CustomPrams` / 命令行解析链。返回： `FString`.                                                                 |
| `GetVADSettings`             | `Convai\|Settings` | `蓝图纯函数`             | 返回当前的快照 `FConvaiVADSettings` ，来自项目设置。                                                                                                |
| `SetVADSettings`             | `Convai\|Settings` | `BlueprintCallable` | 覆盖当前活动的 VAD 设置， `UConvaiSettings` 实例。持久化到 `.ini` ，保存时生效。输入： `InSettings (FConvaiVADSettings)`.                                       |
| `IsAlwaysAllowVisionEnabled` | `Convai\|Settings` | `蓝图纯函数`             | 返回 `true` 当“始终允许视觉”设置启用时。                                                                                                            |

`FConvaiVADSettings` 字段说明（`bUseServerDefault`, `置信度`, `StartSecs`, `StopSecs`, `MinVolume`）位于 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

### 音频辅助函数

#### `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` — `蓝图纯函数`

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

| 引脚         | 方向 | 类型            | 说明                               |
| ---------- | -- | ------------- | -------------------------------- |
| `FilePath` | 输入 | `FString`     | 某个……的绝对路径 `.wav` 文件写入磁盘。         |
| `返回值`      | 输出 | `USoundWave*` | 加载的 SoundWave，或 `nullptr` 失败时返回。 |

### 文件 I/O

| 节点                    | 返回                              | 说明                                                  |
| --------------------- | ------------------------------- | --------------------------------------------------- |
| `ReadFileAsByteArray` | `bool`, `Bytes (TArray<uint8>)` | 读取位于 `FilePath` 的文件到字节数组中。返回 `false` 失败时返回。         |
| `SaveByteArrayAsFile` | `bool`                          | 将 `字节` 写入位于 `FilePath`。返回 `false` 失败时返回。            |
| `ByteArrayToString`   | `FString`                       | 将 `字节` 转换为 UTF-8 `FString`.                         |
| `WriteStringToFile`   | `bool`                          | 将 `StringToWrite` 写入位于 `FilePath`。返回 `false` 失败时返回。 |
| `ReadStringFromFile`  | `bool`, `OutString (FString)`   | 读取位于 `FilePath` 为 `OutString`。返回 `false` 失败时返回。     |

### Blendshape 工具

这些节点会处理 `TMap<FName, float>` blendshape 映射，主要用于口型同步和面部动画管线。请参见 [Convai Chatbot Component](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-chatbot-component.md) ，了解将 blendshape 数据发送到角色的节点。

#### `MapBlendshapes`

类别： `Convai|Blendshapes` — `蓝图纯函数`

将 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` 字段说明位于 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

#### `SplitBlendshapeMapByKeys`

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

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

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

#### `MergeBlendshapeMaps`

类别： `Convai|Blendshapes` — `蓝图纯函数` （显示名称 **合并 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]` 仅在没有候选项被排名时使用。如果没有网格在面部项上得分， `面部组件` 是 `nullptr`.

| 引脚      | 方向 | 类型                        | 说明                    |
| ------- | -- | ------------------------- | --------------------- |
| `Actor` | 输入 | `AActor*`                 | 要检查的 Actor。           |
| `身体组件`  | 输出 | `USkeletalMeshComponent*` | 识别出的身体网格，或 `nullptr`. |
| `面部组件`  | 输出 | `USkeletalMeshComponent*` | 识别出的面部网格，或 `nullptr`. |

### 诊断和平台节点

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

`EC_LipSyncMode` 这些值在文档中有说明 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

### 命令行实用工具

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

| 节点                                         | 类型                           | 返回        | 说明                                                      |
| ------------------------------------------ | ---------------------------- | --------- | ------------------------------------------------------- |
| `GetCommandLineFlagValueAsInt`             | `BlueprintCallable`          | `int32`   | 返回 `标志` 从命令行中获取的整数值。返回 `DefaultValue` （默认 `0`）当该标志不存在时。 |
| `GetCommandLineFlagValueAsString`          | `BlueprintCallable`          | `FString` | 返回 `标志`。返回 `DefaultValue` （默认 `""`）当该标志不存在时。            |
| `GetCommandLineFlagValueAsStringNoDefault` | `BlueprintCallable`, `蓝图纯函数` | `FString` | 返回 `标志` ，且不带默认参数。                                       |
| `GetCommandLineFlagValueAsDouble`          | `BlueprintCallable`, `蓝图纯函数` | `double`  | 返回 `标志`。返回 `DefaultValue` （默认 `0.0`）当该标志不存在时。           |

### 连接管理

`UConvaiConnectionLibrary` 公开了 `PrepareCharacterConnection` 位于 `Convai|Connection` 类别中的 Blueprint 节点。它会预热角色连接，以供后续由 `StartSession`重复使用；请参见 [会话生命周期](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md) 了解连接工作流，以及 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md) 对于 `EC_PrepResult` 值。

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

### 相关参考

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

{% content-ref url="/pages/4a6e5ee0afdb709983f0b5685e8cf00febcf5282" %}
[Convai 聊天机器人组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-chatbot-component.md)
{% endcontent-ref %}

{% content-ref url="/pages/7882b4c0154c419a4eb6df2db3b2035b55cacb03" %}
[Convai 玩家组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-player-component.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-utility-functions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.