> 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).

# Actions Blueprint 参考

本页是 Convai Unreal Engine 插件中构成角色动作 API 的结构体、枚举、事件和函数的完整参考。除非另有说明，所有条目都可通过 Blueprint 访问。

### FConvaiEnvironmentData

存储在 `环境` ……上的属性 `UConvaiChatbotComponent`. 序列化为 `action_config` 在会话开始时。

| 字段                       | 类型                           | 默认值    | 说明                         |
| ------------------------ | ---------------------------- | ------ | -------------------------- |
| `bEnableActions`         | `bool`                       | `true` | 主开关。通过 **启用操作** 在详情面板中。    |
| `动作`                     | `TArray<FConvaiAction>`      | 四个默认值  | 动作模板。                      |
| `Objects`                | `TArray<FConvaiObjectEntry>` | `[]`   | 场景对象目标。                    |
| `Characters`             | `TArray<FConvaiObjectEntry>` | `[]`   | 场景角色目标。                    |
| `CurrentAttentionObject` | `FConvaiObjectEntry`         | 空      | 通过 `SetObjectInAttention`. |

### FConvaiAction

动作模板结构体。在编辑时于 `动作` 数组 `FConvaiEnvironmentData`.

| 字段                       | 类型                           | 默认值     | 说明                                                           |
| ------------------------ | ---------------------------- | ------- | ------------------------------------------------------------ |
| `名称`                     | `FString`                    | `""`    | 规范动作名称。必须与 Blueprint 处理函数名称完全一致，包括空格。Unreal 在解析处理函数名时不区分大小写。 |
| `说明`                     | `FString`                    | `""`    | 发送给 Convai 的可选提示。                                            |
| `Parameters`             | `TArray<FConvaiActionParam>` | `[]`    | 按顺序排列的带类型参数。                                                 |
| `bWaitForBotSpeech`      | `bool`                       | `false` | 将新序列中的第一个动作延迟，直到语音开始、语音结束、无响应触发或等待超时到期。                      |
| `DelayAfterBotSpeechSec` | `float`                      | `0.0`   | 语音条件满足后额外延迟。                                                 |

### FConvaiActionParam

参数模板。每个占位符对应一项，位于一个 `FConvaiAction`.

| 字段        | 类型                       | 默认值    | 说明                                                |
| --------- | ------------------------ | ------ | ------------------------------------------------- |
| `名称`      | `FString`                | `""`   | 占位符名称。映射到 `Parameters` 中的键 `FConvaiResultAction`. |
| `说明`      | `FString`                | `""`   | 给 Convai 的可选提示。                                   |
| `类型`      | `EConvaiActionParamType` | `Auto` | 声明的类型。见下方类型表。                                     |
| `连接器`     | `FString`                | `""`   | 在此参数之前渲染的连接文本，例如 `"on"`.                          |
| `Choices` | `TArray<FString>`        | `[]`   | 固定选项列表。当 `类型 == 枚举`.                              |
| `枚举类型`    | `UEnum*`                 | `null` | 当 `类型 == 枚举`.                                     |

### EConvaiActionParamType

| 值           | 显示名称            | 解析行为                                     |
| ----------- | --------------- | ---------------------------------------- |
| `Auto`      | Auto            | 推断：引用 > 数字 > 布尔 > 字符串。                   |
| `Reference` | Actor Reference | 解析为 `Objects` / `Characters` 通过精确的已注册名称。 |
| `字符串`       | 字符串             | 原始字符串。                                   |
| `Number`    | Number          | `float` 通过 `Atof`.                       |
| `布尔`        | 布尔              | `"true"`/`"yes"`/`"1"` → `true`.         |
| `枚举`        | 枚举              | 与 `枚举类型` 显示名称匹配；枚举值存储在 `ByteValue`.      |

### FConvaiResultAction

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

| 字段                         | 类型                                  | 说明                                                                 |
| -------------------------- | ----------------------------------- | ------------------------------------------------------------------ |
| `Action`                   | `FString`                           | 模板匹配后的规范动作名称。                                                      |
| `ActionString`             | `FString`                           | 来自 Convai 的未处理原始动作字符串。                                             |
| `Parameters`               | `TMap<FString, FConvaiResultParam>` | 参数名 → 解析后值的映射。使用 `获取参数` / `Get Param As X`.                        |
| `bWaitForBotSpeech`        | `bool`                              | 在解析时从匹配的模板复制。                                                      |
| `DelayAfterBotSpeechSec`   | `float`                             | 从匹配的模板复制。                                                          |
| `RelatedObjectOrCharacter` | `FConvaiObjectEntry`                | **已弃用。** 镜像第一个引用类型参数。使用 `GetParamAsRef` 在 `Parameters` 映射中读取参数值。   |
| `ConvaiExtraParams`        | `FConvaiExtraParams`                | **已弃用。** 镜像第一个数字/文本/命名参数。使用 `GetParamAs*` 在 `Parameters` 映射中读取参数值。 |

### FConvaiResultParam

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

| 字段            | 类型                       | 说明                                   |
| ------------- | ------------------------ | ------------------------------------ |
| `类型`          | `EConvaiActionParamType` | 声明或推断的类型。                            |
| `StringValue` | `FString`                | 原始值。始终填充。                            |
| `NumberValue` | `float`                  | `Atof(StringValue)`. `0` 如果不是数字。     |
| `BoolValue`   | `bool`                   | `true` 如果 `"true"`, `"yes"`，或 `"1"`. |
| `RefValue`    | `FConvaiObjectEntry`     | 已解析的 Actor 引用。若未匹配到环境项则为空。           |
| `ByteValue`   | `uint8`                  | 当 `类型 == 枚举` 是位于 `枚举类型` 已设置； `0` 否则。 |

### FConvaiObjectEntry

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

| 字段                       | 类型                                | 默认值       | 说明                                                               |
| ------------------------ | --------------------------------- | --------- | ---------------------------------------------------------------- |
| `名称`                     | `FString`                         | `""`      | 唯一标签。必须在所有已注册对象中保持唯一。                                            |
| `Ref`                    | `TWeakObjectPtr<AActor>`          | `null`    | 实时 Actor。若 Actor 被销毁，该条目仍可保留其名称，同时 `Resolve Goal Location` 报告失败。 |
| `说明`                     | `FString`                         | `""`      | 面向 Convai 的自然语言描述。                                               |
| `移动目标模式`                 | `EConvaiMoveTarget`               | `Actor`   | `将 Actor 作为目标` 或 `将组件作为目标`.                                      |
| `接受半径`                   | `float`                           | `150.0`   | 停止距离（厘米）。                                                        |
| `组件名称`                   | `FString`                         | `""`      | 子组件过滤器。用于 `将组件作为目标` 模式下编辑。                                       |
| `Socket 或 Bone 名称`       | `FName`                           | `无`       | 匹配组件上的插槽或骨骼。                                                     |
| `bStepOntoBounds`        | `bool`                            | `false`   | 走到对象顶部，而不是停在边缘。                                                  |
| `ResolvedComponent`      | `TWeakObjectPtr<USceneComponent>` | `null`    | **瞬态，只读** — 由 `ResolveGoalLocation`.                             |
| `OptionalPositionVector` | `FVector`                         | `(0,0,0)` | **已弃用。** 使用 `Out Goal Location` 的输出 `Resolve Goal Location` 代替。  |

### EConvaiMoveTarget

| 值        | 显示名称         | 行为                       |
| -------- | ------------ | ------------------------ |
| `Actor`  | 将 Actor 作为目标 | AI 在 Actor 的边界处停止。       |
| `Vector` | 将组件作为目标      | AI 走到 Actor 上或附近计算出的世界点。 |

### Resolve Goal Location

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

将一个 `FConvaiObjectEntry` 为某个 `AI 移动到` 节点所需的输入，并可选地运行 NavMesh 路径查询。

**输入：**

| 引脚               | 类型                        | 说明              |
| ---------------- | ------------------------- | --------------- |
| `条目`             | `FConvaiObjectEntry` （引用） | 要解析的对象。         |
| `源 Actor`        | `AActor*`                 | 可选。提供时，也会计算可达性。 |
| `bForce Refresh` | `bool`                    | 绕过缓存的解析。高级引脚。   |

**输出：**

| 引脚                   | 类型                  | 说明                                                      |
| -------------------- | ------------------- | ------------------------------------------------------- |
| `输出目标 Actor`         | `AActor*`           | 该 `Ref` Actor。仅在 Actor 模式下连接到 AI Move To。               |
| `输出目标组件`             | `USceneComponent*`  | 已解析的子组件（Vector 模式 + 组件名称匹配）。                            |
| `Out Goal Location`  | `FVector`           | 已解析的世界位置。仅在 Vector 模式下连接到 AI Move To。                   |
| `输出接受半径`             | `float`             | 镜像 `Entry.AcceptanceRadius`.                            |
| `Out Mode`           | `EConvaiMoveTarget` | 在 Step Onto Bounds 提升后生效的模式。 **基于此分支** 在 AI Move To 之前。 |
| `bOut Success`       | `bool`              | `true` 当 `Ref` 是否存活。在发出 AI Move To 之前务必检查。              |
| `bOut Already There` | `bool`              | `true` 当源 Actor 已经到达目标时。若 `true`.                       |
| `bOut Reachable`     | `bool`              | `true` 当 NavMesh 路径到达目标边界时。                             |
| `输出路径终点`             | `FVector`           | 路径查询的最终导航点。                                             |
| `输出路径点`              | `TArray<FVector>`   | 用于调试可视化的完整导航路径。                                         |

### UConvaiActions — 参数访问器

Blueprint 函数库（类别 **Convai | 动作 API**）。所有函数都接受 `const FConvaiResultAction&`.

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

### 编辑器实用工具

这些仅供编辑器使用的工具可为常见的动作设置任务生成脚手架。它们不是 Blueprint 节点。

| 实用工具                           | 在哪里找到它                       | 用途                                                                                                                 |
| ------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **创建 Convai 动作处理器**            | 在角色 Blueprint 中右键单击 **事件图表** | 生成一个 **事件（在事件图中）** 或 **函数（新函数图）** 一个以已声明动作命名的处理程序，并带有一个 `FConvaiResultAction` 输入和一个 `Handle Action Completion` 调用。 |
| **Setup Convai Pawn Movement** | 在 **内容浏览器** → **Convai**     | 为默认移动动作配置 Pawn 移动和导航默认值。                                                                                           |

### UConvaiChatbotComponent — 动作队列函数

所有函数都位于类别 **Convai | 操作**.

| 函数                                            | Parameters                                                                | 返回      | 说明                                        |
| --------------------------------------------- | ------------------------------------------------------------------------- | ------- | ----------------------------------------- |
| `HandleActionCompletion`                      | `IsSuccessful`, `bAutoReport`, `ShouldRespond`, `AdditionalNote`, `Delay` | `void`  | 报告结果；推进或清空队列。                             |
| `AbortActionSequence`                         | `EventText`, `ShouldRespond`                                              | `void`  | 清空队列，并可选择通知 Convai。                       |
| `IsActionsQueueEmpty`                         | —                                                                         | `bool`  | `true` 当没有排队动作时。BlueprintPure。            |
| `ClearActionQueue`                            | —                                                                         | `void`  | 丢弃所有排队动作而不报告。                             |
| `FetchFirstAction`                            | `输出 ConvaiResultAction`                                                   | `bool`  | 读取（但不移除）队列前端项。BlueprintPure。              |
| `AddAction`                                   | `动作：FConvaiAction`                                                        | `void`  | 添加单个模板；在下一次会话中生效。                         |
| `AddActions`                                  | `动作：TArray<FConvaiAction>`                                                | `void`  | 一次添加多个模板；在下一次会话中生效。                       |
| `AddActionByName`                             | `名称：FString`                                                              | `void`  | 便捷方式：按名称添加一个无描述/无参数的动作。                   |
| `RemoveAction`                                | `名称：FString`                                                              | `void`  | 按名称移除（区分大小写）。                             |
| `RemoveActions`                               | `名称：TArray<FString>`                                                      | `void`  | 按名称移除多个。                                  |
| `ClearActions`                                | —                                                                         | `void`  | 移除所有动作模板。                                 |
| `AddObject`                                   | `对象，bFlushImmediately`                                                    | `void`  | 向本地环境添加单个对象；在适用时会发送实时场景上下文更新。             |
| `AddObjects`                                  | `对象，bFlushImmediately`                                                    | `void`  | 一次向本地环境添加多个条目。                            |
| `RemoveObject`                                | `对象名称，bFlushImmediately`                                                  | `void`  | 按名称移除。                                    |
| `RemoveObjects`                               | `对象名称，bFlushImmediately`                                                  | `void`  | 按名称移除多个。                                  |
| `ClearObjects`                                | `bFlushImmediately`                                                       | `void`  | 清除所有对象。                                   |
| `AddCharacter`                                | `角色，bFlushImmediately`                                                    | `void`  | 向本地环境添加单个角色条目。                            |
| `AddCharacters`                               | `角色，bFlushImmediately`                                                    | `void`  | 一次向本地环境添加多个角色条目。                          |
| `RemoveCharacter`                             | `角色名称，bFlushImmediately`                                                  | `void`  | 按名称移除。                                    |
| `RemoveCharacters`                            | `角色名称，bFlushImmediately`                                                  | `void`  | 按名称移除多个。                                  |
| `ClearCharacters`                             | `bFlushImmediately`                                                       | `void`  | 清除所有角色。                                   |
| `SetObjectInAttention`                        | `AttentionObject、Text、ShouldRespond、bFlushImmediately`                    | `void`  | 设置注意力槽位（显式来源）。                            |
| `TrySetObjectInAttentionFromGaze`             | `AttentionObject、Text、ShouldRespond、bFlushImmediately`                    | `bool`  | 受凝视门控的设置器；返回 `false` 当槽位为 Explicit 时。     |
| `TryClearObjectInAttentionFromGaze`           | `ExpectedObject`                                                          | `bool`  | 受凝视门控的清除；当所有权发生变化时不执行任何操作。                |
| `EnsureObjectComponentsForEnvironmentObjects` | —                                                                         | `int32` | 自动生成 `UConvaiObjectComponent` 为缺少组件的对象生成。 |
| `SetConversationPartner`                      | `伙伴，bFlushImmediately`                                                    | `void`  | 设置当前对话伙伴。                                 |
| `GatherEnvironmentExtras` (**原生事件**)          | `输出 ExtraActions，输出 ExtraObjects，输出 ExtraCharacters`                      | `void`  | 在 Blueprint 中重写，以便在会话开始前追加额外项。            |

### UConvaiChatbotComponent — 动作队列事件

| 事件                         | 显示名称                | 签名                                                                                             |
| -------------------------- | ------------------- | ---------------------------------------------------------------------------------------------- |
| `OnActionReceivedEvent_V2` | On Actions Received | `（ChatbotComponent、InteractingPlayerComponent、SequenceOfActions: TArray<FConvaiResultAction>）` |

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

| 属性                                       | 类型     | 类别                | 说明                                                            |
| ---------------------------------------- | ------ | ----------------- | ------------------------------------------------------------- |
| `bAutoFillConversationPartnerFromPlayer` | `bool` | `Convai\|Session` | 当 `true` （默认），插件会在 `Characters` 列表中在会话开始时。手动注册伙伴时请禁用，以避免重复条目。 |

### EConvaiAttentionSource

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

### EC\_RunLLMOption

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

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

### 相关页面

{% content-ref url="/pages/4034933484ffa13478584311631f11ea8d503bb4" %}
[构建自定义动作处理器](/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" %}
[参数化动作](/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" %}
[排查角色动作问题](/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 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/features/character-actions/actions-blueprint-reference.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.