> 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 聊天机器人组件

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

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

### 身份和角色数据

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

| 属性              | 类型        | 访问                                | 类别       | 说明                                                                                                                  |
| --------------- | --------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `CharacterID`   | `FString` | `EditAnywhere`, `Replicated`      | `Convai` | 来自 [Convai 控制台](https://convai.com)的角色 ID。通过蓝图设置器设置它会调用 `LoadCharacter`，后者会获取角色详情并触发 `OnCharacterDataLoadEvent_V2`. |
| `CharacterName` | `FString` | `BlueprintReadOnly`, `Replicated` | `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` （蓝图原生事件） | `Convai\|Session` | 在蓝图中重写，以便在 `/connect`之前附加额外的动作、对象或角色。输出引脚： `OutExtraActions (TArray<FConvaiAction>)`, `OutExtraObjects (TArray<FConvaiObjectEntry>)`, `OutExtraCharacters (TArray<FConvaiObjectEntry>)`。详情面板中的默认值仍会发送——此钩子只是在其基础上追加，不会替换它们。 |

参见 [会话生命周期](/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 蓝图引用](/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` ，并可在蓝图中的聊天机器人组件上访问。

| 函数                                      | 返回                   | 类别                | 说明                                                               |
| --------------------------------------- | -------------------- | ----------------- | ---------------------------------------------------------------- |
| `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`。将当前混合形状分数作为扁平 float 数组返回。                        |
| `GetFacialDataNames()`                  | `TArray<FString>`    | `Convai\|LipSync` | `BlueprintPure`。按与 `GetFacialData`.                              |
| `ConvaiGetFaceBlendshapes()`            | `TMap<FName, float>` | `Convai\|LipSync` | `BlueprintPure`。返回当前混合形状的名称到分数映射。                                |
| `GeneratesFacialDataAsBlendshapes()`    | `bool`               | `Convai\|LipSync` | `BlueprintPure`. `true` 当输出为混合形状格式（而不是 viseme 索引）时返回             |

{% content-ref url="/pages/8b7003d8fdf40c7b56b0fd2a54376bfc5105903c" %}
[面部同步组件参考](/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` | 向角色发送任意触发消息，使其像接收到该输入一样作出响应。      |

参见 [叙事设计蓝图引用](/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` | 在运行时替换到叙事模板占位符中的键值对。通过蓝图设置器设置会调用 `UpdateNarrativeTemplateKeys`. |

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

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

参见 [动态上下文蓝图引用](/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**）在编辑时于 **详情** 面板中设置。其 `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` | 移除与 `角色名称`。当未找到该名称时不执行任何操作。                                                                             |
| `移除角色`            | `角色名称列表（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`, `Replicated` | `Convai\|Actions` | 此聊天机器人当前正在与之对话的角色或玩家。若尚未存在，则自动添加到 `EnvironmentData.Characters` 中。            |
| `注意力来源`               | `EConvaiAttentionSource` | `BlueprintReadOnly`, `瞬态`    | `Convai\|Actions` | 上一次设置注意力对象的是： `无`, `注视`，或 `显式`。一个 `显式` 设置会锁定该槽位，直到通过向以下项传入空项将其清除： `设置注意力对象`. |

| 函数             | 输入                                                                                                           | 返回              | 类别                | 说明                                                                               |
| -------------- | ------------------------------------------------------------------------------------------------------------ | --------------- | ----------------- | -------------------------------------------------------------------------------- |
| `设置注意力对象`      | `注意力对象（FConvaiObjectEntry）`, `Text (FString)`, `ShouldRespond (EC_RunLLMOption)`, `bFlushImmediately (bool)` | —               | `Convai\|Actions` | 设置聊天机器人正在关注的对象，并可选地发送上下文事件。若以下情况则无效： `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`, `Replicated` | `Convai\|动画` | 角色应注视的 Actor。由 AnimBP 读取，用于头部/眼睛 IK。  |
| `指向目标` | `AActor*` | `BlueprintReadWrite`, `Replicated` | `Convai\|动画` | 角色应指向的 Actor。由 AnimBP 读取，用于手臂 IK 或手势。 |

### 情绪

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

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

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

对于 `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\|转录`         | 收到转录更新时触发。每次话语可能触发多次：每个中间部分一次，最终结果一次。参数： `说话者`, `监听者`, `转录（FString）`, `转录是否就绪（bool）`, `是否最终结果（bool）`. |
| `参与者连接状态变更事件`                     | —    | `Convai\|Connection` | 某个参与者的连接状态发生变化。参数： `ConvaiConversationComponent`, `参与者ID（FString）`, `连接状态（EC_ConnectionState）`.       |

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

| 事件                            | 显示名称        | 类别                | 触发时机：                                                                                                                          |
| ----------------------------- | ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `OnStartedTalkingDelegate`    | —           | `Convai`          | 角色的音频播放在新的回复轮次开始时启动。无参数。                                                                                                       |
| `OnFinishedTalkingDelegate`   | —           | `Convai`          | 角色的音频播放完全结束，包括任何剩余的缓冲音频。无参数。                                                                                                   |
| `OnFacialDataReadyDelegate`   | —           | `Convai\|LipSync` | 口型同步管线中有新的 BlendShape 帧可用。无参数。                                                                                                 |
| `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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.