> 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/features/character-actions/actions-blueprint-reference.md).

# 动作 Blueprint 参考

用于支持 Unreal Engine 中 Convai 角色动作的 Blueprint 结构体、枚举、事件和队列函数的参考。

本页完整介绍了 Convai Unreal Engine 插件中构成角色动作 API 的结构体、枚举、事件和函数。除非另有说明，所有项均可在蓝图中访问。

### FConvaiEnvironmentData

存储在 `Environment` 属性中的结构体，该属性位于 `UConvaiChatbotComponent`上。会在会话开始时序列化为 `action_config` 。

| 字段                       | 类型                           | 默认值    | 备注                          |
| ------------------------ | ---------------------------- | ------ | --------------------------- |
| `bEnableActions`         | `bool`                       | `true` | 总开关。通过 **启用动作** 在“细节”面板中设置。 |
| `Actions`                | `TArray<FConvaiAction>`      | 四个默认项  | 动作模板。                       |
| `Objects`                | `TArray<FConvaiObjectEntry>` | `[]`   | 场景对象目标。                     |
| `Characters`             | `TArray<FConvaiObjectEntry>` | `[]`   | 场景角色目标。                     |
| `CurrentAttentionObject` | `FConvaiObjectEntry`         | 空      | 通过 `SetObjectInAttention`.  |

### 中接收填充后的结果

动作模板结构体。在编辑时于 `Actions` 数组中定义，该数组属于 `FConvaiEnvironmentData`.

| 字段                       | 类型                           | 默认值     | 备注                                                     |
| ------------------------ | ---------------------------- | ------- | ------------------------------------------------------ |
| `Name`                   | `FString`                    | `""`    | 规范动作名称。必须与蓝图处理函数的名称一致，包括空格。Unreal 会以不区分大小写的方式解析处理函数名称。 |
| `Description`            | `FString`                    | `""`    | 发送给 Convai 的可选提示。                                      |
| `Parameters`             | `TArray<FConvaiActionParam>` | `[]`    | 有序的类型化参数。                                              |
| `bWaitForBotSpeech`      | `bool`                       | `false` | 新序列中的第一个动作会延迟执行，直到语音开始、语音结束、触发无响应事件或等待超时。              |
| `DelayAfterBotSpeechSec` | `float`                      | `0.0`   | 语音条件满足后额外延迟的时间。                                        |

### FConvaiActionParam

参数模板。每个 `FConvaiAction`.

| 字段            | 类型                       | 默认值       | 备注                                                                |
| ------------- | ------------------------ | --------- | ----------------------------------------------------------------- |
| `Name`        | `FString`                | `""`      | 中的占位符对应一个条目。占位符名称映射到 `Parameters` 中的键，该键位于 `FConvaiResultAction`. |
| `Description` | `FString`                | `""`      | 上。                                                                |
| `Type`        | `EConvaiActionParamType` | `Auto`    | 可选的 Convai 提示。                                                    |
| `Connector`   | `FString`                | `""`      | 声明的类型。请参见下方的类型表。 `"on"`.                                          |
| `Choices`     | `TArray<FString>`        | `[]`      | 前置于此参数并呈现的连接文本，例如 `固定选项列表。当`.                                     |
| `EnumType`    | `Type == Enum`           | `时显示为灰色。` | UEnum\* `null`.                                                   |

### EConvaiActionParamType

| 值           | 显示名称 | 当                                                    |
| ----------- | ---- | ---------------------------------------------------- |
| `Auto`      | 自动   | Type == Enum                                         |
| `Reference` | 时必填。 | 解析行为 `推断：引用 > 数字 > 布尔值 > 字符串。` / `Actor 引用` 按精确注册名称在 |
| `String`    | 字符串  | 中解析。                                                 |
| `Number`    | 数字   | `float` 通过 `Atof`.                                   |
| `Bool`      | 布尔值  | `"true"`/`"yes"`/`"1"` → `true`.                     |
| `Enum`      | 枚举   | 匹配以下内容 `EnumType` 显示名称；枚举值存储在 `ByteValue`.           |

### FConvaiResultAction

传递给操作处理程序的结构体。每个已分发的操作对应一个。

| 字段                         | 类型                                  | 备注                                                                       |
| -------------------------- | ----------------------------------- | ------------------------------------------------------------------------ |
| `Action`                   | `FString`                           | 模板匹配后的规范操作名称。                                                            |
| `ActionString`             | `FString`                           | 来自 Convai 的未经处理的原始操作字符串。                                                 |
| `Parameters`               | `TMap<FString, FConvaiResultParam>` | 参数名称 → 解析后值的映射。使用键访问命名参数，例如 `Get Param` / `Get Param As X`.              |
| `bWaitForBotSpeech`        | `bool`                              | 在解析时从匹配的模板复制。                                                            |
| `DelayAfterBotSpeechSec`   | `float`                             | 从匹配的模板复制。                                                                |
| `RelatedObjectOrCharacter` | `FConvaiObjectEntry`                | **已弃用。** 镜像第一个 Reference 类型的参数。请改用 `GetParamAsRef` 在 `Parameters` 映射上访问。 |
| `ConvaiExtraParams`        | `FConvaiExtraParams`                | **已弃用。** 镜像第一个数字/文本/命名参数。请改用 `GetParamAs*` 在 `Parameters` 映射上访问。         |

### FConvaiResultParam

一个已解析的参数值。无论声明的类型为何，都会尽力填充所有字段。

| 字段            | 类型                       | 备注                                                    |
| ------------- | ------------------------ | ----------------------------------------------------- |
| `Type`        | `EConvaiActionParamType` | 声明或推断的类型。                                             |
| `StringValue` | `FString`                | 原始值。始终会填充。                                            |
| `NumberValue` | `float`                  | `Atof(StringValue)`. `0` （如果不是数字）。                    |
| `BoolValue`   | `bool`                   | `true` 当 `"true"`, `"yes"`或 `"1"`.                    |
| `RefValue`    | `FConvaiObjectEntry`     | 已解析的 Actor 引用。没有匹配的环境对象时为空。                           |
| `ByteValue`   | `uint8`                  | 匹配的枚举值，条件是 `Type == Enum` 且 `EnumType` 已设置； `0` 否则为空。 |

### FConvaiObjectEntry

描述环境中的场景对象或角色。

| 字段                                       | 类型                                | 默认值           | 备注                                                                                                |
| ---------------------------------------- | --------------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
| `Name`                                   | `FString`                         | `""`          | 唯一标签。必须在所有已注册对象中保持唯一。                                                                             |
| `Ref`                                    | `TWeakObjectPtr<AActor>`          | `时显示为灰色。`     | 实时 Actor。如果 Actor 被销毁，该条目仍可保留其名称，但 `Resolve Goal Location` 会报告失败。                                 |
| `Description`                            | `FString`                         | `""`          | 供 Convai 使用的通俗描述。                                                                                 |
| `ObjectReference`                        | `EConvaiObjectReference`          | `Whole Actor` | 显示名称 **对象类型**. `Whole Actor` 或 `Specific Component`。控制注视/注意力范围，以及在 `MovementPoints` 为空时使用的移动备用方案。 |
| `ComponentName`                          | `FString`                         | `""`          | 子组件筛选条件。当 `ObjectReference` 为 `Specific Component`.                                               |
| `SocketOrBoneName`                       | `FName`                           | `None`        | 匹配组件上的可选插槽或骨骼。                                                                                    |
| `AcceptanceRadius`                       | `float`                           | `150.0`       | 停止距离，单位为 cm。                                                                                      |
| `MovementPoints`                         | `TArray<FConvaiMovementPoint>`    | `[]`          | 由设计人员命名的目的地。启用一个或多个点后，它们将取代 `ObjectReference` 成为移动目标；解析器会选择路径最短且可到达的点。                            |
| `bFallbackToObjectWhenPointsUnreachable` | `bool`                            | `false`       | 显示名称 **将对象用作备用目标**。如果所有 `MovementPoints` 条目均无法到达，则走向对象本身。                                         |
| `ResolvedComponent`                      | `TWeakObjectPtr<USceneComponent>` | `时显示为灰色。`     | **临时、只读** — 由 `ResolveGoalLocation`.                                                              |
| `OptionalPositionVector`                 | `FVector`                         | `(0,0,0)`     | **已弃用。** 请改用 `Destination` 的 `Resolve Goal Location` 输出。                                          |

{% hint style="info" %}
`ObjectReference` 取代了早期 beta 版本使用的移动目标枚举和边界标志： `Whole Actor` 本身已表示在对象边界处停止，因此无需单独的标志。关于升级仍读取旧字段的项目，请参阅 [迁移到 4.0.0-beta.27](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/overview/migrate-to-4-0-0-beta-27.md).
{% endhint %}

### EConvaiObjectReference

来源： `ConvaiDefinitions.h:36`.

| 值                   | 显示名称     | 行为                                                           |
| ------------------- | -------- | ------------------------------------------------------------ |
| `WholeActor`        | 整个 Actor | 注视可匹配 Actor 的任意基本体。移动备用方案： `AI Move To` 使用 `Ref` ，并在角色边界处停止。 |
| `SpecificComponent` | 特定组件     | 注视仅匹配指定组件。移动回退目标为该组件（或插槽）的世界位置。                              |

### 解析目标位置

位于 `UConvaiActions` （类别 **Convai | Action API**).

将一个 `FConvaiObjectEntry` 解析为 `AI Move To` 节点所需的输入，并可选择执行 NavMesh 路径查询。源代码： `ConvaiActionUtils.h:262-280`.

{% hint style="info" %}
将 **Target Actor** 和 **Destination** 直接连到一个 `AI Move To` 节点即可，无需分支判断。 `Target Actor` 在 `null` 目标为固定位置时（Movement Point 获胜，或条目引用了组件），因此会自动回退到 `AI Move To` 会自动回退到 `Destination` 。
{% endhint %}

**输入：**

| 引脚             | 类型                        | 备注                          |
| -------------- | ------------------------- | --------------------------- |
| `Entry`        | `FConvaiObjectEntry` （引用） | 要解析的对象。                     |
| `Source Actor` | `AActor*`                 | 可选。提供此项时，还会计算可达性、到达状态和路径输出。 |

**输出：**

| 引脚                         | 类型                 | 备注                                                                          |
| -------------------------- | ------------------ | --------------------------------------------------------------------------- |
| `Target Actor`             | `AActor*`          | 连接到 `AI Move To`的 **Target Actor** 引脚。 `null` 当目标是位置或解析失败时为此值。              |
| `Object Actor` （高级）        | `AActor*`          | `Entry.Ref`，对象存续期间始终有值。用于非移动场景（附加效果、查询）时——不要将此项连接到 `AI Move To`.            |
| `Out Goal Component`       | `USceneComponent*` | 当 `ObjectReference` 为 `Specific Component` 且 `Component Name` 匹配时解析出的子组件。   |
| `Destination`              | `FVector`          | 连接到 `AI Move To`的 **Destination** 引脚。获胜的 Movement Point、组件/插槽位置，或 `Ref`的原点。 |
| `Out Acceptance Radius`    | `float`            | 与 `Entry.AcceptanceRadius`一致。传递给 `AI Move To`.                              |
| `Uses Destination` （高级）    | `bool`             | `true` ，当目标是一个位置时为此值——也就是说，当且仅当 `Target Actor` 为 `null`时。仅显式使用分支的图表需要此项。    |
| `bOut Success`             | `bool`             | `true` 表示 `Ref` 仍然存活且解析成功。调用 `AI Move To`.                                  |
| `bOut Already There`       | `bool`             | `true` 表示 `Source Actor` 已到达目标位置。跳过 `AI Move To` 表示 `true`.                 |
| `bOut Reachable`           | `bool`             | `true` 表示从 `Source Actor` 出发的 NavMesh 路径在容差范围内到达目标。                         |
| `Out Path End Point`       | `FVector`          | 路径查询的最终导航点。                                                                 |
| `Out Path Points`          | `TArray<FVector>`  | 用于调试可视化的完整导航路径。                                                             |
| `Out Goal Travel Distance` | `float`            | 到所选目标的导航路径长度（以虚幻单位计）； `0` 未计算出路径或已到达目标时，                                    |
| `Out Movement Point Index` | `int32`            | 哪个 `MovementPoints` 条目胜出； `-1` 当 `ObjectReference` 解析出目标时则为此值。              |

### Convai 移动至

异步蓝图节点（潜伏式）。 `UConvaiMoveToProxy::ConvaiMoveTo`，类别 **Convai | 移动**。源文件： `Actions/ConvaiMoveToTask.h:244,263`.

将一个 Actor 移动到 `FConvaiObjectEntry` 目标位置——可以是整个 Actor、组件/插槽或预先设置的 Movement Points——无需手动连接 `Resolve Goal Location` → `AI Move To` 节点。

| 引脚                  | 类型                        | 备注                                             |
| ------------------- | ------------------------- | ---------------------------------------------- |
| `Moving Actor`      | `AActor*`                 | 要移动的 Actor。                                    |
| `Destination`       | `FConvaiObjectEntry`      | 目标条目。                                          |
| `bLockAILogic` （高级） | `bool`                    | 默认值 `false`.                                   |
| `Succeeded` （执行引脚）  | —                         | 在以下情况触发： `Reached` 或 `Already At Destination`. |
| `Failed` （执行引脚）     | —                         | 在其他任何情况下触发，返回 `EConvaiMoveToResultCode`.       |
| `Result Code`       | `EConvaiMoveToResultCode` | 请参见下文。                                         |
| `Additional Note`   | `FString`                 | 可安全地传递给 `Handle Action Completion` 或向玩家回应。     |

#### EConvaiMoveToResultCode

来源： `Actions/ConvaiMoveToTask.h:18`.

| 值                               | 显示名称      |
| ------------------------------- | --------- |
| `Reached`                       | 已到达       |
| `AlreadyAtDestination`          | 已在目的地     |
| `UnknownDestination`            | 未知目的地     |
| `Unreachable`                   | 无法到达      |
| `InvalidCharacter`              | 无效角色      |
| `MissingController`             | 缺少 AI 控制器 |
| `MissingMovementComponent`      | 缺少移动组件    |
| `MissingPathFollowingComponent` | 缺少路径跟随组件  |
| `MissingNavigationData`         | 缺少导航数据    |
| `MoveFailed`                    | 移动失败      |

### Convai 护送

异步蓝图节点（延迟执行）。 `UConvaiEscortProxy::ConvaiEscort`，类别 **Convai | 移动**。来源： `Actions/ConvaiEscortToTask.h:221,239`.

将护送者 Actor 移动到目的地，同时让被护送角色跟随；当被护送角色落后时暂停，以便其跟上。

| 引脚                 | 类型                        | 备注                                             |
| ------------------ | ------------------------- | ---------------------------------------------- |
| `护送者 Actor`        | `AActor*`                 | 带领护送并拥有用于跟随提示的 `Convai Chatbot` 的 Actor。       |
| `被护送角色`            | `FConvaiObjectEntry`      | 被护送的角色。                                        |
| `Destination`      | `FConvaiObjectEntry`      | 目标条目。                                          |
| `Succeeded` （执行引脚） | —                         | 在以下情况触发： `Reached` 或 `Already At Destination`. |
| `Failed` （执行引脚）    | —                         | 在任何其他 `EConvaiEscortResultCode`.               |
| `Result Code`      | `EConvaiEscortResultCode` | 请参见下文。                                         |
| `Additional Note`  | `FString`                 | 可安全传递给 `Handle Action Completion`.             |

随附的 `BP_ConvaiChatbotComponent` 便捷蓝图中包含一个 `Escort` 操作，开箱即用。

#### EConvaiEscortResultCode

来源： `Actions/ConvaiEscortToTask.h:21`.

| 值                        | 显示名称   |
| ------------------------ | ------ |
| `Reached`                | 已到达    |
| `AlreadyAtDestination`   | 已在目的地  |
| `EscorteeUnavailable`    | 角色不可用  |
| `DestinationUnavailable` | 目的地不可用 |
| `InvalidGuideSetup`      | 护送设置无效 |
| `MovementFailed`         | 移动失败   |

### UConvaiActions — 参数访问器

蓝图函数库（类别 **Convai | 操作 API**）。所有函数均接受 `const FConvaiResultAction&`.

| 函数                 | 显示名称      | 返回类型                     |
| ------------------ | --------- | ------------------------ |
| `GetFirstParam`    | 获取第一个参数   | `FConvaiResultParam`     |
| `GetParam`         | 获取参数      | `FConvaiResultParam`     |
| `GetParamType`     | 获取参数类型    | `EConvaiActionParamType` |
| `GetParamAsString` | 将参数获取为字符串 | `FString`                |
| `GetParamAsNumber` | 将参数获取为数字  | `float`                  |
| `GetParamAsBool`   | 将参数获取为布尔值 | `bool`                   |
| `GetParamAsRef`    | 将参数获取为引用  | `FConvaiObjectEntry`     |
| `GetParamAsByte`   | 将参数获取为字节  | `uint8`                  |
| `HasParam`         | 是否包含参数    | `bool`                   |

### 编辑器实用工具

这些仅限编辑器使用的工具可为常见操作设置任务搭建框架。它们不是蓝图节点。

| 实用工具                  | 位置                       | 用途                                                                                                                       |
| --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| **创建 Convai 操作处理程序**  | 在角色蓝图中单击右键 **事件图表**      | 搭建一个 **事件（位于事件图表中）** 或 **函数（新建函数图表）** 处理程序，其名称与已声明的操作同名，并包含一个 `FConvaiResultAction` 输入和一个 `Handle Action Completion` 调用。 |
| **设置 Convai Pawn 移动** | 在 **内容浏览器** → **Convai** | 为默认移动操作配置 Pawn 移动和导航默认值。                                                                                                 |

### UConvaiChatbotComponent — 操作队列函数

所有函数均位于 **Convai | 操作**.

| 函数                                            | 参数                                                                        | 返回      | 备注                                                                                                                                             |
| --------------------------------------------- | ------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `HandleActionCompletion`                      | `IsSuccessful`, `bAutoReport`, `ShouldRespond`, `AdditionalNote`, `Delay` | `void`  | 报告结果；推进或清空队列。                                                                                                                                  |
| `AbortActionSequence`                         | `EventText`, `ShouldRespond`                                              | `void`  | 清空队列，并可选择通知 Convai。                                                                                                                            |
| `CancelCurrentActionPlan`                     | —                                                                         | `void`  | 显示名称 **取消当前操作计划**。以协作方式取消当前计划：丢弃排队的操作，并向活动的 Blueprint 处理程序提供一个可选事件，其名称必须完全是 `Cancel <Action Name>` ，并附带原始的 `FConvaiResultAction`。重复调用只会请求一次取消。 |
| `IsActionsQueueEmpty`                         | —                                                                         | `bool`  | `true` （没有排队的操作时）。BlueprintPure。                                                                                                               |
| `ClearActionQueue`                            | —                                                                         | `void`  | 丢弃所有排队的操作，不报告结果。                                                                                                                               |
| `FetchFirstAction`                            | `out ConvaiResultAction`                                                  | `bool`  | 读取队列首项（但不移除）。BlueprintPure。                                                                                                                    |
| `AddAction`                                   | `Action: FConvaiAction`                                                   | `void`  | 添加单个模板；在下次会话中生效。                                                                                                                               |
| `AddActions`                                  | `Actions: TArray<FConvaiAction>`                                          | `void`  | 一次添加多个模板；在下次会话中生效。                                                                                                                             |
| `AddActionByName`                             | `Name: FString`                                                           | `void`  | 便捷函数：按名称添加不含描述和参数的操作。                                                                                                                          |
| `RemoveAction`                                | `Name: FString`                                                           | `void`  | 按名称移除（区分大小写）。                                                                                                                                  |
| `RemoveActions`                               | `Names: TArray<FString>`                                                  | `void`  | 按名称移除多个项目。                                                                                                                                     |
| `ClearActions`                                | —                                                                         | `void`  | 移除所有操作模板。                                                                                                                                      |
| `AddObject`                                   | `Object, bFlushImmediately`                                               | `void`  | 向本地环境添加单个对象；适用时会发送实时场景上下文更新。                                                                                                                   |
| `AddObjects`                                  | `Objects, bFlushImmediately`                                              | `void`  | 一次向本地环境添加多个条目。                                                                                                                                 |
| `RemoveObject`                                | `ObjectName, bFlushImmediately`                                           | `void`  | 按名称移除。                                                                                                                                         |
| `RemoveObjects`                               | `ObjectNames, bFlushImmediately`                                          | `void`  | 按名称移除多个项目。                                                                                                                                     |
| `ClearObjects`                                | `bFlushImmediately`                                                       | `void`  | 清除所有对象。                                                                                                                                        |
| `AddCharacter`                                | `Character, bFlushImmediately`                                            | `void`  | 向本地环境添加单个人物条目。                                                                                                                                 |
| `AddCharacters`                               | `Characters, bFlushImmediately`                                           | `void`  | 一次向本地环境添加多个角色条目。                                                                                                                               |
| `RemoveCharacter`                             | `CharacterName, bFlushImmediately`                                        | `void`  | 按名称移除。                                                                                                                                         |
| `RemoveCharacters`                            | `CharacterNames, bFlushImmediately`                                       | `void`  | 按名称移除多个项目。                                                                                                                                     |
| `ClearCharacters`                             | `bFlushImmediately`                                                       | `void`  | 清除所有角色。                                                                                                                                        |
| `SetObjectInAttention`                        | `AttentionObject, Text, ShouldRespond, bFlushImmediately`                 | `void`  | 设置注意力槽（显式来源）。                                                                                                                                  |
| `TrySetObjectInAttentionFromGaze`             | `AttentionObject, Text, ShouldRespond, bFlushImmediately`                 | `bool`  | 受注视条件约束的设置器；当注意力槽为显式来源时，返回 `false` 。                                                                                                           |
| `TryClearObjectInAttentionFromGaze`           | `ExpectedObject`                                                          | `bool`  | 受注视条件约束的清除操作；所有权已变更时不执行任何操作。                                                                                                                   |
| `EnsureObjectComponentsForEnvironmentObjects` | —                                                                         | `int32` | 自动为缺少组件的对象生成 `UConvaiObjectComponent` 。                                                                                                        |
| `SetConversationPartner`                      | `Partner, bFlushImmediately`                                              | `void`  | 设置当前对话对象。                                                                                                                                      |
| `GatherEnvironmentExtras` (**原生事件**)          | `out ExtraActions, out ExtraObjects, out ExtraCharacters`                 | `void`  | 在 Blueprint 中重写此事件，以便在会话开始前追加额外内容。                                                                                                             |

### UConvaiChatbotComponent — 操作队列事件

| 事件                         | 显示名称     | 签名                                                                                                        |
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `OnActionReceivedEvent_V2` | 收到动作时    | `(ChatbotComponent, InteractingPlayerComponent, SequenceOfActions: TArray<FConvaiResultAction>)`          |
| `OnBotTurnCompletedEvent`  | 机器人回合完成时 | `(ChatbotComponent, ResponseId: FString, bWasInterrupted: bool, bWasAborted: bool, ErrorReason: FString)` |

`On Bot Turn Completed` 是 Convai 报告的权威响应生命周期终止事件 — 触发时，本地音频和面部动画可能仍在播放。类别 `Convai`。在决定是否推进依赖动作的逻辑之前，可用它确认回合确实结束，而不要仅依赖本地语音结束事件。

### UConvaiChatbotComponent — 会话属性（与动作相关）

| 属性                                       | 类型     | 类别                              | 备注                                                                                                                                                        |
| ---------------------------------------- | ------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bAutoFillConversationPartnerFromPlayer` | `bool` | `Convai\|Session`               | 当 `true` （默认值）时，插件会在会话开始时自动将对话伙伴注册到 `Characters` 列表中。手动注册对话伙伴时，请禁用此项，以避免重复条目。                                                                             |
| `bEnableCancelActionPlanAction`          | `bool` | `Convai\|Actions\|Experimental` | 显示名称 **启用取消动作计划**。默认值为 `false`。添加保留的 `Cancel Action Plan` 控制动作，使 Convai 可以在玩家改换方向或放弃正在执行的计划时调用 `Cancel Current Action Plan` 。此设置从下次会话开始时生效；需要启用 **启用动作**. |

### UConvaiPlayerComponent — 是否正在说话

`IsSpeaking` — `UFUNCTION(BlueprintPure, BlueprintCallable, Category = "Convai", meta = (DisplayName = "Is Speaking"))`，返回 `bool`。源文件： `ConvaiPlayerComponent.h:246`.

`true` 表示玩家正在说话。服务器的语音活动事件是主要信号；非空的部分或最终转录可用于补足缺失的状态变化，而短暂的实时停止宽限期可吸收过早或重复的停止数据包。这是本地会话状态，不会复制到其他端。在动作处理程序中使用它，可避免在移动或交互动作仍在执行时打断玩家说话。

### EConvaiAttentionSource

| 值          | 显示名称                | 备注                                        |
| ---------- | ------------------- | ----------------------------------------- |
| `None`     | 无                   | 槽位为空。                                     |
| `Explicit` | 显式设置（Blueprint/C++） | 通过直接调用 `SetObjectInAttention` 进行设置。会阻止注视。 |
| `Gaze`     | 注视                  | 由注视管线设置。可被另一注视事件替换。                       |

### EC\_RunLLMOption

控制是否 `HandleActionCompletion` 和 `AbortActionSequence` 触发角色的语音回复。

| 值        | 显示名称 | 对 HandleActionCompletion / AbortActionSequence 的影响 |
| -------- | ---- | -------------------------------------------------- |
| `Auto`   | 自动   | 由 Convai 决定是否做出响应。                                 |
| `Always` | 始终   | 强制触发语音回复。                                          |
| `Never`  | 从不   | 仅静默更新上下文。                                          |

### 相关页面

{% content-ref url="/pages/4034933484ffa13478584311631f11ea8d503bb4" %}
[构建自定义动作处理器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/building-custom-action-handlers.md)
{% endcontent-ref %}

{% content-ref url="/pages/e29ff52f0d30b08b7f190e5b10f7b84aa21c7ff4" %}
[参数化动作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/parameterized-actions.md)
{% endcontent-ref %}

{% content-ref url="/pages/8c96d39684a8203fb0c40d8bcb7467ca8267e3c9" %}
[排查角色动作问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/troubleshoot-character-actions.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/features/character-actions/actions-blueprint-reference.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.
