> 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/configuring-actions.md).

# 配置动作

定义动作集，启用角色动作，并注册环境对象和角色，以便 Convai 可以引用它们。

该 `Convai Chatbot` 组件的 `Environment` 属性控制角色动作的各个方面：角色可以执行哪些动作、可以引用哪些物体和角色，以及是否启用动作。在编辑器中设置动作模板并注册物体；进入 Play 模式前，编译角色蓝图以保存更改。

### Environment 属性

Convai Chatbot `Convai Chatbot` 组件（`UConvaiChatbotComponent`）在 Details 面板的 **Convai | Actions** 类别中公开了一个类型为 `FConvaiEnvironmentData` 的 **Convai | Actions** 类别。

`FConvaiEnvironmentData` 包含以下顶层字段：

| 字段                       | 类型                           | 用途                                                                                                                                                                                    |
| ------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bEnableActions`         | `bool`                       | 总开关。默认值为 `true`。当 `false`时，启动会话时不会发送 `action_config` ，并且动作会被禁用。                                                                                                                       |
| `Actions`                | `TArray<FConvaiAction>`      | 角色可以执行的动作模板。                                                                                                                                                                          |
| `Objects`                | `TArray<FConvaiObjectEntry>` | 角色可引用为动作目标的场景物体。                                                                                                                                                                      |
| `Characters`             | `TArray<FConvaiObjectEntry>` | 场景中的其他角色。                                                                                                                                                                             |
| `CurrentAttentionObject` | `FConvaiObjectEntry`         | 聊天机器人当前注意力槽中的物体（参见 [注意力与引用定位](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/attention-and-reference-grounding.md)). |

#### 启用动作

**Enable Actions** 默认值为 `true` ，适用于每个新建的 `Convai Chatbot` 组件——新建角色无需手动操作。若要禁用某个角色的动作，使其只进行对话而不执行实体任务，请在 Details 面板中展开 **Environment** 并取消勾选 **Enable Actions**.

### 定义动作模板

Actions `Actions` 数组是一个 `FConvaiAction` 包含三个主要字段的结构体：

| 字段            | 类型                           | 用途                                                                                                                                                                    |
| ------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Name`        | `FString`                    | 不含参数占位符的规范操作名称。必须与处理程序名称一致，包括空格和标点。                                                                                                                                   |
| `Description` | `FString`                    | 可选的人类语言提示，用于向 Convai 描述该操作的作用。                                                                                                                                        |
| `Parameters`  | `TArray<FConvaiActionParam>` | 按顺序排列的类型化参数。详情请参阅 [参数化操作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/parameterized-actions.md) 。 |

其他时间字段：

| 字段                       | 类型      | 默认值     | 用途                                              |
| ------------------------ | ------- | ------- | ----------------------------------------------- |
| `bWaitForBotSpeech`      | `bool`  | `false` | 当 `true` 且此操作在新序列中最先到达时，延迟触发，直到角色开始或结束说话。       |
| `DelayAfterBotSpeechSec` | `float` | `0.0`   | 语音条件满足后额外延迟的秒数。当 `bWaitForBotSpeech` 为 `false`. |

#### 默认操作

该 `Actions` 数组默认预先填充了四个条目：

| 操作名称      | 参数                       | 用途              |
| --------- | ------------------------ | --------------- |
| `Move To` | `destination` （Actor 引用） | 导航到已注册的对象或角色目标。 |
| `跟随`      | `角色` （角色引用）              | 跟随已注册的角色或玩家。    |
| `停止移动`    | —                        | 停止导航。           |
| `等待`      | `秒数` （数字）                | 等待指定时长。         |

默认 **描述** 这些模板中的值均为空，除了 `Follow`，它随附 `"Follow a character"`。你可以根据需要重命名、添加描述或移除任何默认操作。若要移除默认操作，请在数组中选中它，然后点击删除按钮。

这四个默认项适用于所有新建的 `Convai Chatbot` 组件。捆绑的 `BP_ConvaiChatbotComponent` 便捷蓝图还附带一个 `Escort` 可直接使用的动作，其 `Wait for Action` 条目也已添加，但默认处于禁用状态。

#### 添加自定义动作

{% stepper %}
{% step %}

#### 添加一个新条目

点击 **+** 在 `Actions` 数组中。
{% endstep %}

{% step %}

#### 为动作命名

将 **Name** 设为独特且描述性强的动词短语，例如 `"打开门"`, `"打印"`或 `"跳舞"`.
{% endstep %}

{% step %}

#### 添加描述（可选）

仅在动作名称本身含义不明确时设置 **Description** 。描述应简短，也可以留空，以减少发送给 Convai 的上下文。
{% endstep %}

{% step %}

#### 添加参数（可选）

如果动作需要带类型的输入，请在 **Parameters** 中添加条目。请参阅 [带参数的动作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/parameterized-actions.md).
{% endstep %}

{% step %}

#### 编译并生成处理程序框架

点击 **Compile** 角色蓝图中的，然后生成处理程序框架。请参阅 [构建自定义动作处理程序](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/building-custom-action-handlers.md).
{% endstep %}
{% endstepper %}

#### 编写建议

| 建议做法          | 原因                                                         |
| ------------- | ---------------------------------------------------------- |
| 动作名称应简短且易于区分  | Convai 会根据名称匹配模板。 `"跳舞"` 比 `"播放舞蹈动画"`.                     |
| 更容易匹配。        | 描述会随动作契约一同发送。额外的文字会增加上下文，却无法改善行为效果。                        |
| 对象名称应易于区分     | 使用 `"立方体"` 和 `"枪"` 而不是 `"立方体"` 和 `"cube2"` 从而确保引用参数能够可靠解析。 |
| **选项** 用于固定变体 | 一个 `Dance` 操作，带有一个 `type` 参数和三个 **选项** 优于三个描述重复的独立舞蹈模板。    |
| 编译后再播放        | 在 Blueprint 编译之前，处理程序无法使用新建或编辑过的操作模板。                      |

{% hint style="warning" %}
操作名称必须与所属 Actor 上的 Blueprint 函数或事件名称完全一致，包括空格和标点。Unreal 不区分大小写地解析处理程序名称，但 `"Stop Moving"` 和 `"StopMoving"` 是不同的名称。
{% endhint %}

### 实验性内置操作

在 `Convai Chatbot`（类别为 `Convai|Actions|Experimental`）上启用另外两个开关，即可添加不会出现在 `Actions` 数组中的内置操作。启用后，下次连接时会将该操作发送给 Convai；处理程序在组件内部运行，因此无需为其搭建 Blueprint 处理程序。

| 属性                           | 类型     | 默认值     | 用途                                                                                                                                                                                                                                     |
| ---------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bEnableRemindSelfAction`    | `bool` | `false` | 显示名称 **启用“提醒自己”操作**。添加内置的 **提醒自己** 操作：角色可以在另一个操作之后将其加入队列（例如 `Move To`），以便在该操作完成后提醒自己需要考虑或说些什么，例如走到一幅画前再描述它。提醒会在对话的下一个停顿时送达，不会打断正在进行的交流。                                                                                                |
| `bEnableWatchPropertyAction` | `bool` | `false` | 显示名称 **启用“监视属性”操作**。添加内置的 **监视属性** 操作：角色可以通过属性的确切上下文键（例如 `"FrontDoor.DoorState"`）为受跟踪的属性设置一次性监视，并在属性确实发生变化时收到通知；也可以等待属性达到特定值（例如 `"Platform.Movement = Stopped"`）。即使该属性自身的 **Should Respond** 设为 `Never` 或 `Auto`，此功能依然有效；监视器触发一次后便会解除。 |

这两个开关都会在下次会话开始时生效，并且需要 **启用 Actions**.

{% hint style="warning" %}
`Enable Remind Self Action` 和 `Enable Watch Property Action` 属于实验性功能（类别 `Convai|Actions|Experimental`）。它们的行为可能会在未来版本中发生变化。
{% endhint %}

### 注册对象

Objects `数组包含` 个 `FConvaiObjectEntry` 结构体，用于表示可交互的场景对象。每个条目包含：

| 字段                 | 类型                             | 用途                                                                                              |
| ------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------- |
| `Name`             | `FString`                      | 角色用来识别此对象的唯一标签。                                                                                 |
| `Ref`              | `TWeakObjectPtr<AActor>`       | 此条目所代表的关卡内 Actor。                                                                               |
| `Description`      | `FString`                      | 提供给 Convai 的可选自然语言描述。                                                                           |
| `ObjectReference`  | `EConvaiObjectReference`       | 显示名称 **对象类型**. `Whole Actor` （在 Actor 边界处停止——这意味着要走到对象占据的范围内）或 `Specific Component` （走到特定子组件处）。 |
| `AcceptanceRadius` | `float`                        | AI 必须接近到多近，才会将移动视为完成。默认值为 `150` 厘米。                                                             |
| `ComponentName`    | `FString`                      | Specific Component `模式的可选子组件名称。` 模式。                                                            |
| `SocketOrBoneName` | `FName`                        | 匹配组件上可选的插槽或骨骼名称。                                                                                |
| `MovementPoints`   | `TArray<FConvaiMovementPoint>` | 设计人员可选用的命名目的地。启用其中任意一个后，它们会取代 `ObjectReference` 作为移动目标。                                         |

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

**添加对象：**

1. 点击 **+** 上的 `Objects` 数组。
2. 将 `Name` 设置为简短且唯一的标签。
3. 使用吸管工具将 `Ref` 指定为目标 Actor。
4. 如有帮助，可设置 `Description` 。
5. 根据导航精度需求调整 `ObjectReference` 和 `AcceptanceRadius` 。

#### 使用 `UConvaiObjectComponent` 自动注册

无需手动填充 `Objects` 数组，只需将 `UConvaiObjectComponent` 添加到任意场景 Actor。会话开始时，这些组件会通过 `UConvaiSubsystem`自动向所有聊天机器人注册。对于包含大量可交互对象的关卡，这是推荐的做法。

关于 [场景元数据](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata.md) 的完整文档，请参阅 `UConvaiObjectComponent`.

### 注册角色

Characters `数组的工作方式与` Objects `数组相同，但它表示聊天机器人可以在` 等操作中引用的其他 NPC 或 AI 角色。 `Follow`.

会话开始时，如果聊天机器人组件上的 `bAutoFillConversationPartnerFromPlayer` 为 `true` ，插件可以自动将玩家的对话伙伴添加到角色列表中。插件会使用找到的第一个 `UConvaiPlayerComponent` ；如果找不到，则在需要时回退到玩家 Pawn `0` ，并将其命名为 `User` 。此属性位于 Details 面板的 **Convai | Session** 类别中，默认值为 `true`。使用 `SetConversationPartner` 当你需要注册非玩家对话对象时使用。

### 运行时修改

运行时修改适用于高级使用场景。大多数项目只需使用上述编辑器设置。

你可以使用 `UConvaiChatbotComponent`:

| 方法                                                    | 用途                                |
| ----------------------------------------------------- | --------------------------------- |
| `AddObject(Object, bFlushImmediately)`                | 向环境中添加单个 `FConvaiObjectEntry` 条目。 |
| `AddObjects(Objects, bFlushImmediately)`              | 一次添加多个条目。                         |
| `RemoveObject(ObjectName, bFlushImmediately)`         | 按名称移除。                            |
| `RemoveObjects(ObjectNames, bFlushImmediately)`       | 按名称移除多个条目。                        |
| `ClearObjects(bFlushImmediately)`                     | 移除所有对象。                           |
| `AddCharacter(Character, bFlushImmediately)`          | 添加一个角色条目。                         |
| `AddCharacters(Characters, bFlushImmediately)`        | 一次添加多个角色条目。                       |
| `RemoveCharacter(CharacterName, bFlushImmediately)`   | 按名称移除角色。                          |
| `RemoveCharacters(CharacterNames, bFlushImmediately)` | 按名称移除多个角色。                        |
| `ClearCharacters(bFlushImmediately)`                  | 移除所有角色。                           |

运行时对对象和角色的更改会立即更新本地 `EnvironmentData` 镜像。在实时会话中，尚未包含在连接时场景元数据快照中的更改会先批量处理，再通过 `update-scene-metadata` 发送，以便 Convai 获取更新后的场景上下文。仅当必须立即更新时才设置 `bFlushImmediately = true` ，因为频繁刷新会产生过多网络流量。

#### 高级用法：GatherEnvironmentExtras

仅当环境必须根据会话开始时的运行时状态发生变化时，才使用此重写。在 NPC Actor 上重写 `Gather Environment Extras` Blueprint 原生事件，以便在会话开始前追加其他动作、对象或角色。该重写会在 `StartSession` 时执行一次，并且采用累加方式——不会替换 Details 面板中的默认设置。

```
// 蓝图伪代码
// Blueprint 原生事件重写 — 在 NPC Actor Blueprint 中实现
Event GatherEnvironmentExtras(out ExtraActions, out ExtraObjects, out ExtraCharacters)
    // 追加依赖运行时状态的任务专属物品
    Add FConvaiAction("Pick Up", "Pick up the item", []) → ExtraActions
    Add FConvaiObjectEntry("QuestKey", KeyActor)          → ExtraObjects
```

### 后续步骤

{% 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/8e18d509947b40274dca96b384f432486348198f" %}
[动作 Blueprint 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-reference.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/configuring-actions.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.
