> 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-chatbot-component.md).

# Convai 聊天机器人组件

AI 角色组件参考——Convai Chatbot Component 暴露的每个 Blueprint 可见属性、函数和事件。

`UConvaiChatbotComponent` (Blueprint 显示名称 **Convai 聊天机器人**) 是添加到 AI 角色上的主要组件 `Actor`。它管理角色与 Convai 的会话，接收音频和面部数据，分发动作和情绪更新，并提供完整的 Blueprint API，用于对话和环境控制。

将其添加到任何 `Actor` 通过 **添加组件** 按钮，在 **Details** 面板。

### 身份和角色数据

这些属性用于标识角色和加载的运行时名称。

| 属性              | 类型        | 访问权限                       | 类别       | 说明                                                                                                                                    |
| --------------- | --------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `CharacterID`   | `FString` | `EditAnywhere`, `已复制`      | `Convai` | 来自以下位置的角色 ID： [Convai 仪表板](https://convai.com)。通过 Blueprint setter 设置此值会调用 `LoadCharacter`，它会获取角色详情并触发 `OnCharacterDataLoadEvent_V2`. |
| `CharacterName` | `FString` | `BlueprintReadOnly`, `已复制` | `Convai` | 从 Convai 获取的角色名称。在以下事件后填充： `OnCharacterDataLoadEvent_V2` 触发后。                                                                         |

### 会话

| 属性 / 函数                                  | 类型        | 默认     | 类别                | 说明                                                                                                                                     |
| ---------------------------------------- | --------- | ------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `bAutoInitializeSession`                 | `bool`    | `true` | `Convai\|Session` | 当 `true`，调用 `StartSession` 会话会自动在 `BeginPlay`.                                                                                         |
| `bAutoFillConversationPartnerFromPlayer` | `bool`    | `true` | `Convai\|Session` | 当 `true`, `StartSession` 填充 `ConversationPartner` ，来源于第一个注册的 `UConvaiPlayerComponent`。在以下情况下设为 `false` 当你显式分配 `ConversationPartner` 时。 |
| `SessionID`                              | `FString` | `"-1"` | `Convai`          | 对话记忆令牌。 `"-1"` 表示没有先前的对话。保存此值以恢复会话。 `ResetConversation` 将其重置为 `"-1"`。已复制。                                                              |

#### 会话函数

| 函数                                         | 类别                | 说明                                                                                                                                                                                                                                              |
| ------------------------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `StartSession`                             | `Convai\|Session` | 打开到 Convai 的 WebRTC 通道。调用 `GatherEnvironmentExtras` ，然后再连接。角色详情由 `BeginPlay` 当 `CharacterID` 被设置时，或由 `LoadCharacter` 当 `CharacterID` 发生更改时。                                                                                                     |
| `StopSession`                              | `Convai\|Session` | 关闭通道。再次调用 `StartSession` 会重新打开它。                                                                                                                                                                                                                |
| `ResetConversation`                        | `Convai`          | 重置 `SessionID` 为 `"-1"`，清除对话记忆。不会停止会话。                                                                                                                                                                                                          |
| `GatherEnvironmentExtras` (Blueprint 原生事件) | `Convai\|Session` | 在 Blueprint 中重写，以便在以下操作之前追加额外的动作、对象或角色： `/connect`。输出引脚： `OutExtraActions (TArray<FConvaiAction>)`, `OutExtraObjects (TArray<FConvaiObjectEntry>)`, `OutExtraCharacters (TArray<FConvaiObjectEntry>)`。Details 面板中的默认值仍会发送——此钩子只会在其基础上追加，不会替换它们。 |

参见 [会话生命周期](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md) 以了解连接状态以及会话启动/停止行为。

### 长期记忆（LTM）

| 属性                | 类型        | 访问权限                                 | 类别       | 说明                              |
| ----------------- | --------- | ------------------------------------ | -------- | ------------------------------- |
| `EndUserID`       | `FString` | `BlueprintReadWrite`, `EditAnywhere` | `Convai` | 用于长期记忆的最终用户身份令牌。在连接时发送给 Convai。 |
| `EndUserMetadata` | `FString` | `BlueprintReadWrite`, `EditAnywhere` | `Convai` | 包含用于 LTM 的额外用户元数据的 JSON 字符串。    |

参见 [LTM Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/long-term-memory/ltm-blueprint-reference.md) 用于 LTM 专用节点。

### 对话状态查询

这些是 `BlueprintPure` 可随时调用以读取角色状态的函数。

| 函数                             | 返回                   | 类别                   | 说明                                                                                                                       |
| ------------------------------ | -------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `IsInConversation`             | `bool`               | `Convai`             | 返回 `true` 当 `IsProcessing()`, `IsListening()`，或 `GetIsTalking()` 是 `true`。在当前插件源码中，这会简化为 `GetIsTalking()` 仅仅因为另外两个查询是存根。 |
| `IsProcessing` (显示名称 **正在思考**) | `bool`               | `Convai`             | 旨在返回 `true` 当角色正在等待来自 Convai 的完整响应时。 **当前源码：** 始终返回 `false` （存根，等待会话代理连接）。                                               |
| `IsListening`                  | `bool`               | `Convai`             | 旨在返回 `true` 当角色正在接收玩家音频时。 **当前源码：** 始终返回 `false` （存根）。                                                                   |
| `GetIsTalking` (显示名称 **正在说话**) | `bool`               | `Convai`             | `true` 当角色正在播放其语音音频时。                                                                                                    |
| `GetChatbotConnectionState`    | `EC_ConnectionState` | `Convai\|Connection` | 当前 WebRTC 通道状态： `已断开连接`, `连接中`, `已连接`，或 `重新连接中`.                                                                         |

### 语音和说话

| 属性                              | 类型      | 默认    | 类别       | 说明                   |
| ------------------------------- | ------- | ----- | -------- | -------------------- |
| `InterruptVoiceFadeOutDuration` | `float` | `1.0` | `Convai` | 角色音频在被打断后淡出为静音所需的秒数。 |

| 函数                        | 返回      | 类别              | 说明                                   |
| ------------------------- | ------- | --------------- | ------------------------------------ |
| `GetTalkingTimeElapsed`   | `float` | `Convai\|Voice` | `BlueprintPure`。自角色在当前轮次开始说话以来经过的秒数。 |
| `GetTalkingTimeRemaining` | `float` | `Convai\|Voice` | `BlueprintPure`。当前轮次预计剩余的音频时长。       |

| 函数                | 输入                              | 类别       | 说明                        |
| ----------------- | ------------------------------- | -------- | ------------------------- |
| `InterruptSpeech` | `InVoiceFadeOutDuration（float）` | `Convai` | 在调用该函数的组件上淡出并停止角色当前的音频播放。 |

### 口型同步

这些函数继承自 `UConvaiAudioStreamer` ，并可在 Blueprint 中的聊天机器人组件上访问。

| 函数                                      | 返回                   | 类别                | 说明                                                                   |
| --------------------------------------- | -------------------- | ----------------- | -------------------------------------------------------------------- |
| `SetLipSyncComponent(LipSyncComponent)` | `bool`               | `Convai\|LipSync` | 附加一个实现以下接口的口型同步组件： `IConvaiLipSyncInterface`。返回 `false` 当该组件未实现该接口时。 |
| `SupportsLipSync()`                     | `bool`               | `Convai\|LipSync` | `BlueprintPure`. `true` 当附加了口型同步组件时。                                 |
| `GetLipSyncMode()`                      | `EC_LipSyncMode`     | `Convai\|LipSync` | `BlueprintPure`。返回由所附加组件设置的口型同步模式。                                   |
| `HasPlayableFaceFrames()`               | `bool`               | `Convai\|LipSync` | `BlueprintPure`. `true` 当口型同步系统已有可应用的缓冲帧时。                           |
| `GetFacialData()`                       | `TArray<float>`      | `Convai\|LipSync` | `BlueprintPure`。将当前 blendshape 分数作为一个扁平的 float 数组返回。                 |
| `GetFacialDataNames()`                  | `TArray<FString>`    | `Convai\|LipSync` | `BlueprintPure`。按与以下项相同的顺序返回 blendshape 曲线名称： `GetFacialData`.       |
| `ConvaiGetFaceBlendshapes()`            | `TMap<FName, float>` | `Convai\|LipSync` | `BlueprintPure`。返回当前 blendshape 的名称到分数映射。                            |
| `GeneratesFacialDataAsBlendshapes()`    | `bool`               | `Convai\|LipSync` | `BlueprintPure`. `true` 当输出为 blendshape 格式时（而不是 viseme 索引时）。         |

{% content-ref url="/pages/8b7003d8fdf40c7b56b0fd2a54376bfc5105903c" %}
[Face Sync 组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/lip-sync/face-sync-component-reference.md)
{% endcontent-ref %}

### 视觉

| 函数                                    | 返回     | 类别               | 说明                                                                |
| ------------------------------------- | ------ | ---------------- | ----------------------------------------------------------------- |
| `SetVisionComponent(VisionComponent)` | `bool` | `Convai\|Vision` | 附加一个实现以下接口的视觉组件： `IConvaiVisionInterface`。返回 `false` 当该组件未实现该接口时。 |
| `SupportsVision()`                    | `bool` | `Convai\|Vision` | `BlueprintPure`. `true` 当附加了视觉组件时。                                |

### 音频播放计时

这些 `BlueprintPure` 函数会暴露角色音频管线的计时信息，适用于将字幕、动画或 UI 元素与角色的语音同步。

| 函数                              | 返回       | 类别              | 说明                                        |
| ------------------------------- | -------- | --------------- | ----------------------------------------- |
| `GetAudioPlaybackTime()`        | `double` | `Convai\|Audio` | 自当前说话轮次开始以来经过的秒数。使用字节消耗跟踪和挂钟时间，返回两者中较小的值。 |
| `GetRemainingContentDuration()` | `double` | `Convai\|Audio` | 当前已缓冲或正在播放内容的预计剩余音频时长（秒）。                 |

### 叙事设计触发器

| 函数                                                  | 输入                                                                                    | 类别       | 说明                                |
| --------------------------------------------------- | ------------------------------------------------------------------------------------- | -------- | --------------------------------- |
| `InvokeNarrativeDesignTrigger` (显示名称 **调用叙事设计触发器**) | `TriggerName (FString)`, `InGenerateActions (bool)`, `InReplicateOnNetwork (bool)`    | `Convai` | 激活在 Convai 仪表板中配置的叙事设计图里的一个命名触发器。 |
| `ExecuteNarrativeTrigger` (显示名称 **调用语音**)           | `TriggerMessage (FString)`, `InGenerateActions (bool)`, `InReplicateOnNetwork (bool)` | `Convai` | 向角色发送任意触发消息，使其像接收到该输入一样做出响应。      |

参见 [叙事设计 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-blueprint-reference.md) 用于完整的叙事表面。

### 叙事设计模板键

| 属性                      | 类型                       | 访问权限                                 | 类别                        | 说明                                                                           |
| ----------------------- | ------------------------ | ------------------------------------ | ------------------------- | ---------------------------------------------------------------------------- |
| `NarrativeTemplateKeys` | `TMap<FString, FString>` | `BlueprintReadWrite`, `EditAnywhere` | `Convai\|NarrativeDesign` | 运行时替换到叙事模板占位符中的键值对。通过 Blueprint setter 设置时会调用 `UpdateNarrativeTemplateKeys`. |

### 上下文（静态和动态）

| 属性                       | 类型        | 访问权限                                 | 类别       | 说明                                                                                                            |
| ------------------------ | --------- | ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `DynamicEnvironmentInfo` | `FString` | `BlueprintReadWrite`, `EditAnywhere` | `Convai` | 在连接时注入的自由文本上下文。适用于角色在会话开始时需要的静态事实（库存、玩家生命值、一天中的时间）。通过 Blueprint setter 设置时会调用 `UpdateDynamicEnvironmentInfo`. |

对于角色可在会话中途响应的运行时上下文更新，请使用下面的动态上下文函数。

#### 动态上下文函数

这些函数可在不重启会话的情况下更新角色的运行时上下文。在以下时间窗口内的更新： `ContextDebounceWindow` 会合并为一次发送。

| 函数                                         | 输入                                                                                             | 类别                       | 说明                                     |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------ | -------------------------------------- |
| `UpdateContext`                            | `Text（FString）`, `Mode（EC_ContextUpdateMode）`, `ShouldRespond（EC_RunLLMOption）`                | `Convai`                 | 使用追加、替换或重置模式发送上下文更新。                   |
| `SetContextState` (显示名称 **设置上下文状态**)       | `Name（FString）`, `Value（FString）`, `ShouldRespond（EC_RunLLMOption）`, `bFlushImmediately（bool）` | `Convai\|DynamicContext` | 设置或替换单个命名状态属性（例如 `“Health”` → `"80"`). |
| `SetContextStates` (显示名称 **设置上下文状态**)      | `States（TMap<FString,FString>）`, `ShouldRespond（EC_RunLLMOption）`, `bFlushImmediately（bool）`   | `Convai\|DynamicContext` | 一次调用设置多个状态属性。                          |
| `AddContextEvent` (显示名称 **添加上下文事件**)       | `Text（FString）`, `ShouldRespond（EC_RunLLMOption）`, `bFlushImmediately（bool）`                   | `Convai\|DynamicContext` | 追加一个按时间顺序排列的事件（例如 `“玩家接近了商人”`).        |
| `RemoveContextState` (显示名称 **移除上下文状态**)    | `Name（FString）`, `bFlushImmediately（bool）`                                                     | `Convai\|DynamicContext` | 移除一个命名状态属性，并重建规范化上下文。                  |
| `ResetDynamicContext` (显示名称 **重置动态上下文**)   | —                                                                                              | `Convai\|DynamicContext` | 清除所有已跟踪的状态属性和事件，并重置远程上下文。              |
| `GetContextStateValue` (显示名称 **获取上下文状态值**) | `Name（FString）` → `OutValue（FString）`，返回 `bool`                                                | `Convai\|DynamicContext` | 返回已跟踪状态属性的当前值。返回 `false` 当该属性不存在时。     |

`模式` 在 `UpdateContext` 接受 `EC_ContextUpdateMode` 值； `ShouldRespond` 在所有动态上下文函数中接受 `EC_RunLLMOption` 值。有关值说明，请参见 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

#### 动态上下文防抖设置

| 属性                         | 类型      | 默认    | 类别                            | 说明                                                         |
| -------------------------- | ------- | ----- | ----------------------------- | ---------------------------------------------------------- |
| `ContextDebounceWindow`    | `float` | `0.5` | `Convai\|DynamicContext` （高级） | 在最近一次暂存更新后等待多少秒再刷新。在此时间窗口内的每次新更新都会重置计时器。                   |
| `ContextMaxDebounceWindow` | `float` | `3.0` | `Convai\|DynamicContext` （高级） | 防抖延迟的上限（秒）。防止持续不断的更新流无限期推迟刷新。必须 ≥ `ContextDebounceWindow`. |

参见 [动态上下文 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/dynamic-context-blueprint-reference.md) 用于完整的动态上下文接口和任务流程。

### 环境和角色动作

环境会跟踪聊天机器人所感知到的对象、角色和动作。 `EnvironmentData` 属性（`FConvaiEnvironmentData`，类别 `Convai|Actions`，显示名称 **Environment**）在编辑时于 **Details** 面板中设置。其 `bEnableActions` 切换决定是否在 `/connect` 时发送动作数据。

#### 环境变更函数（对象）

| 函数              | 输入                                                               | 类别                | 说明                                                  |
| --------------- | ---------------------------------------------------------------- | ----------------- | --------------------------------------------------- |
| `AddObject`     | `Object（FConvaiObjectEntry）`, `bFlushImmediately（bool）`          | `Convai\|Actions` | 向环境中添加一个对象，并安排一次 `更新场景元数据` 发送。同名条目会在原位替换。           |
| `AddObjects`    | `Objects（TArray<FConvaiObjectEntry>）`, `bFlushImmediately（bool）` | `Convai\|Actions` | 一次批量调用添加多个对象。                                       |
| `RemoveObject`  | `ObjectName（FString）`, `bFlushImmediately（bool）`                 | `Convai\|Actions` | 移除与以下名称匹配的对象： `ObjectName` 从环境中移除。若未找到该名称，则不执行任何操作。 |
| `RemoveObjects` | `ObjectNames（TArray<FString>）`, `bFlushImmediately（bool）`        | `Convai\|Actions` | 移除所有名称出现在以下列表中的对象： `ObjectNames`.                   |
| `ClearObjects`  | `bFlushImmediately（bool）`                                        | `Convai\|Actions` | 从环境中移除所有已跟踪对象。                                      |

`bFlushImmediately` 绕过防抖窗口并立即发送。对于高频更新，建议使用默认的批量行为。

#### 环境变更函数（角色）

| 函数                | 输入                                                                  | 类别                | 说明                                                                                        |
| ----------------- | ------------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------- |
| `AddCharacter`    | `Character（FConvaiObjectEntry）`, `bFlushImmediately（bool）`          | `Convai\|Actions` | 向环境中添加一个角色并安排同步。同名条目会在原位替换。                                                               |
| `AddCharacters`   | `Characters（TArray<FConvaiObjectEntry>）`, `bFlushImmediately（bool）` | `Convai\|Actions` | 一次批量调用添加多个角色。                                                                             |
| `RemoveCharacter` | `InCharacterName（FString）`, `bFlushImmediately（bool）`               | `Convai\|Actions` | 移除与以下名称匹配的角色： `InCharacterName`。当未找到该名称时不执行任何操作。                                          |
| `移除角色`            | `角色名称（TArray<FString>）`, `bFlushImmediately（bool）`                  | `Convai\|Actions` | 按名称移除多个角色。                                                                                |
| `清除角色`            | `bFlushImmediately（bool）`                                           | `Convai\|Actions` | 从环境中移除所有已跟踪的角色。                                                                           |
| `设置对话对象`          | `对话对象（FConvaiObjectEntry）`, `bFlushImmediately（bool）`               | `Convai\|Actions` | 设置此聊天机器人当前正在对话的角色。会自动添加到 `EnvironmentData.Characters` 如果尚未存在。传入一个空条目即可清除对话对象，而不从列表中移除任何人。 |

#### 环境修改函数（动作）

{% hint style="warning" %}
动作修改将应用于 **下一次** 会话开始时，而不是实时会话中——动作集合在 `/connect` 时固定。要使新动作对正在运行的角色可用，请调用 `StopSession` 然后 `StartSession`.
{% endhint %}

| 函数        | 输入                          | 类别                | 说明                       |
| --------- | --------------------------- | ----------------- | ------------------------ |
| `添加动作`    | `动作（FConvaiAction）`         | `Convai\|Actions` | 向本地环境添加一个动作模板。同名条目会原地替换。 |
| `添加多个动作`  | `动作（TArray<FConvaiAction>）` | `Convai\|Actions` | 一次调用添加多个动作模板。            |
| `按名称添加动作` | `Name（FString）`             | `Convai\|Actions` | 仅按名称添加一个无描述、无参数的动作。      |
| `移除动作`    | `Name（FString）`             | `Convai\|Actions` | 移除匹配以下项的动作 `名称`。区分大小写。   |
| `移除多个动作`  | `名称（TArray<FString>）`       | `Convai\|Actions` | 按名称移除多个动作。               |
| `清除动作`    | —                           | `Convai\|Actions` | 移除所有已跟踪的动作模板。            |

#### 注意对象

| 属性                    | 类型                       | 访问权限                      | 类别                | 说明                                                                        |
| --------------------- | ------------------------ | ------------------------- | ----------------- | ------------------------------------------------------------------------- |
| `ConversationPartner` | `FConvaiObjectEntry`     | `EditAnywhere`, `已复制`     | `Convai\|Actions` | 此聊天机器人当前正在对话的角色或玩家。会自动添加到 `EnvironmentData.Characters` 如果尚未存在。            |
| `注意来源`                | `EConvaiAttentionSource` | `BlueprintReadOnly`, `瞬时` | `Convai\|Actions` | 最后设置注意对象的是： `无`, `注视`，或 `显式`。一个 `显式` 设置会锁定该槽位，直到通过向以下项传入空条目将其清除 `设置注意对象`. |

| 函数             | 输入                                                                                                                                                                   | 返回              | 类别                | 说明                                                                                                                                                                             |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `设置注意对象`       | `注意对象（FConvaiObjectEntry）`, `Text（FString）`, `ShouldRespond（EC_RunLLMOption）`, `传递方式（EConvaiContextDelivery）`, `bAddAttentionEvent（bool）`, `bFlushImmediately（bool）` | —               | `Convai\|Actions` | 设置聊天机器人当前聚焦的对象。 `bAddAttentionEvent` 默认开启，并发出一次性播报事件；关闭后即可静默设置该槽位。 `传递方式` 可以将该提示延后到对话暂停时再处理。当以下情况时会记录警告且不起作用： `EnvironmentData.bEnableActions` 是 `false`，当对象不在环境列表中，或在连接时未发送时。 |
| `尝试根据注视设置注意对象` | 与以下项相同 `设置注意对象`                                                                                                                                                      | `bool`          | `Convai\|Actions` | 仅在以下情况下设置注意 `注意来源` 是 `无` 或 `注视`。返回 `false` 当槽位为 `显式`归属时，并记录一条警告，说明为何该调用没有生效。                                                                                                   |
| `尝试根据注视清除注意对象` | `期望对象（FConvaiObjectEntry）`                                                                                                                                           | `bool`          | `Convai\|Actions` | 仅当注视拥有的注意槽位仍匹配时才清除 `期望对象`。返回 `false` 当槽位已更改时。                                                                                                                                  |
| `为环境对象确保对象组件`  | —                                                                                                                                                                    | `int32` （已生成组件） | `Convai\|Actions` | 自动生成 `UConvaiObjectComponent` 在每个 `EnvironmentData.Objects` 尚未拥有该组件的 actor 上。幂等。                                                                                               |

#### 动作队列

| 函数         | 返回                                                   | 类别                | 说明                                   |
| ---------- | ---------------------------------------------------- | ----------------- | ------------------------------------ |
| `动作队列是否为空` | `bool`                                               | `Convai\|Actions` | `true` 当 `动作队列` 没有待处理项。              |
| `获取第一个动作`  | `bool`, `ConvaiResultAction（FConvaiResultAction）` 输出 | `Convai\|Actions` | 返回队列中的第一个动作，但不移除它。返回 `false` 当队列为空时。 |
| `清除动作队列`   | —                                                    | `Convai\|Actions` | 清除 `动作队列` 而不向 LLM 发送任何事件。            |

| 属性     | 类型                            | 访问权限                | 类别                | 说明                                             |
| ------ | ----------------------------- | ------------------- | ----------------- | ---------------------------------------------- |
| `动作队列` | `TArray<FConvaiResultAction>` | `BlueprintReadOnly` | `Convai\|Actions` | 待执行动作的有序列表。由以下项填充： `OnActionReceivedEvent_V2`. |

#### 处理动作完成

报告当前动作的结果。成功时，出队并推进到下一个动作。失败时，清除剩余队列。可选地向 LLM 发送自动生成的结果事件。

| 参数              | 类型                | 默认     | 说明                                                                                                              |
| --------------- | ----------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `是否成功`          | `bool`            | `true` | `true` — 出队已完成的动作并开始下一个。 `false` — 清除整个剩余队列。                                                                    |
| `bAutoReport`   | `bool`            | `true` | 当 `true`，向 LLM 发送默认结果消息： `“你已成功<action>”` 成功时，或 `“<action>失败，试试别的办法，或咨询<player name>”` 失败时。设为 `false` 即可抑制默认消息。 |
| `ShouldRespond` | `EC_RunLLMOption` | `从不`   | LLM 如何响应结果事件。 `从不` — 静默上下文更新；结果会在下一轮用户回合进入 LLM 的视图。 `自动` — 由 LLM 决定。 `始终` — 强制口头回复。                             |
| `附加说明`          | `FString`         | `""`   | 高级显示。可选文本，将作为以下内容附加到自动生成的消息： `“，备注：<text>”`。当 `bAutoReport` 是 `false` 且此项非空时，它会单独发送。                            |
| `延迟`            | `float`           | `0.0`  | 高级显示。在下一个与 LLM 交互的步骤之前等待的秒数。成功时，延后启动下一个动作。失败时，延后发送外发事件。                                                         |

#### 中止动作序列

清空整个动作队列，不重试也不推进。用于处理器遇到无法恢复的问题（目标消失、前置条件失败），并希望 LLM 规划新序列时。

| 参数              | 类型                | 默认   | 说明                                                  |
| --------------- | ----------------- | ---- | --------------------------------------------------- |
| `事件文本`          | `FString`         | `""` | 高级显示。可选消息，用于描述失败原因。为空时，中止为静默——队列会被清空，但不会向 LLM 发送事件。 |
| `ShouldRespond` | `EC_RunLLMOption` | `自动` | 高级显示。当以下情况时忽略： `事件文本` 为空。                           |

参见 [动作蓝图参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-reference.md) 用于查看完整的动作接口，包括 `FConvaiAction`, `FConvaiResultAction`以及环境结构详情。

### 动画目标

这些属性驱动 AnimBP 中的视线和指向 IK。它们对对话或音频管线没有影响。

| 属性     | 类型        | 访问权限                        | 类别                  | 说明                                    |
| ------ | --------- | --------------------------- | ------------------- | ------------------------------------- |
| `注视目标` | `AActor*` | `BlueprintReadWrite`, `已复制` | `Convai\|Animation` | 角色应注视的 actor。由 AnimBP 读取，用于头部/眼睛 IK。  |
| `指向目标` | `AActor*` | `BlueprintReadWrite`, `已复制` | `Convai\|Animation` | 角色应指向的 actor。由 AnimBP 读取，用于手臂 IK 或手势。 |

### 情绪

| 属性       | 类型      | 默认      | 类别                | 说明                                                   |
| -------- | ------- | ------- | ----------------- | ---------------------------------------------------- |
| `锁定情绪状态` | `bool`  | `false` | `Convai\|Emotion` | 当 `true`，来自 Convai 的传入情绪更新会被忽略，并且 `情绪状态` 保持不变。       |
| `情绪偏移`   | `float` | `0.0`   | `Convai`          | 应用于情绪强度的标量偏置。高于 `0` 会增强；低于 `0` 会减弱。有效范围： `-1` 为 `1`. |

{% hint style="warning" %}
`锁定情绪状态` 是一个已序列化的 `bool`。如果保持 `true` 在已保存的场景或预制体中，该组件会静默忽略来自 Convai 的所有实时情绪信号。请确认该值 `false` 在发布前。
{% endhint %}

| 函数         | 输入                                                              | 返回                   | 类别                | 说明                       |
| ---------- | --------------------------------------------------------------- | -------------------- | ----------------- | ------------------------ |
| `强制设置情绪`   | `基础情绪（EBasicEmotions）`, `强度（EEmotionIntensity）`, `重置其他情绪（bool）` | —                    | `Convai\|Emotion` | 用指定的情绪和强度覆盖当前情绪状态。       |
| `获取情绪分数`   | `情绪（EBasicEmotions）`                                            | `float`              | `Convai\|Emotion` | 返回特定情绪的当前分数（0.0–1.0）。    |
| `获取情绪混合形态` | —                                                               | `TMap<FName, float>` | `Convai\|Emotion` | 返回当前情绪混合形态映射，可直接应用于骨骼网格。 |
| `重置情绪状态`   | —                                                               | —                    | `Convai\|Emotion` | 将所有情绪分数清零并恢复到中性。         |

关于 `EBasicEmotions` 和 `EEmotionIntensity` 取值说明，请参见 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

参见 [情绪蓝图参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/emotion/emotion-blueprint-reference.md) 以了解情绪任务流程和附加节点。

### 事件（可在蓝图中绑定的委托）

请在角色蓝图中使用以下项绑定这些事件： **分配** 节点，在 `Convai 聊天机器人` 组件引用上。

#### 继承自 `UConvaiConversationComponent`

| 事件                                | 显示名称 | 类别                      | 触发条件：                                                                                                 |
| --------------------------------- | ---- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `OnTranscriptionReceivedDelegate` | —    | `Convai\|Transcription` | 收到转写更新时触发。每次发言会触发多次：每个中间部分一次，最终结果一次。参数： `说话者`, `监听者`, `转写（FString）`, `转写是否就绪（bool）`, `是否为最终结果（bool）`. |
| `参与者连接状态变化事件`                     | —    | `Convai\|Connection`    | 某位参与者的连接状态发生变化。参数： `ConvaiConversationComponent`, `参与者ID（FString）`, `连接状态（EC_ConnectionState）`.       |

#### 聊天机器人专属事件

| 事件                            | 显示名称        | 类别                | 触发条件：                                                                                                                          |
| ----------------------------- | ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `开始说话委托`                      | —           | `Convai`          | 角色的音频播放开始进入新的回复轮次。无参数。                                                                                                         |
| `结束说话委托`                      | —           | `Convai`          | 角色的音频播放完全结束，包括任何剩余的缓冲音频。无参数。                                                                                                   |
| `面部数据就绪委托`                    | —           | `Convai\|LipSync` | 唇同步管线提供了一个新的混合形态帧。无参数。                                                                                                         |
| `OnActionReceivedEvent_V2`    | **收到动作**    | `Convai`          | Convai 发送一个或多个角色动作。 `动作队列` 在此触发时已填充。参数： `ChatbotComponent`, `InteractingPlayerComponent`, `动作序列（TArray<FConvaiResultAction>）`. |
| `情绪状态变化事件`                    | **情绪状态已变化** | `Convai`          | Convai 返回更新后的情绪状态。 `情绪状态` 在此触发时已更新。参数： `ChatbotComponent`, `InteractingPlayerComponent`.                                       |
| `OnCharacterDataLoadEvent_V2` | **角色数据已加载** | `Convai`          | 插件完成从 Convai 获取角色详情。触发于 `LoadCharacter` 或一个 `CharacterID` 变更后。参数： `ChatbotComponent`, `成功（bool）`.                              |
| `收到叙事章节事件`                    | **收到叙事章节**  | `Convai`          | AI 进入新的叙事设计章节。参数： `ChatbotComponent`, `叙事章节ID（FString）`.                                                                       |
| `收到交互ID事件`                    | **收到交互ID**  | `Convai`          | 新的交互轮次开始。参数： `ChatbotComponent`, `InteractingPlayerComponent`, `交互ID（FString）`.                                                |
| `中断事件`                        | **被中断**     | `Convai`          | `InterruptSpeech` 在角色说话且音频淡出开始时调用。参数： `ChatbotComponent`, `InteractingPlayerComponent`.                                        |
| `失败事件`                        | **失败**      | `Convai`          | 会话遇到无法恢复的错误。无参数。                                                                                                               |

参见 [事件系统](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/event-system.md) 以了解绑定模式和时序细节。

### 相关参考

{% 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-chatbot-component.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.