> 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` 组件的 `环境` 该属性控制角色操作的方方面面：角色可以执行哪些操作、可以引用哪些对象和角色，以及操作是否完全启用。请在编辑器中设置操作模板并注册对象；在进入播放模式前编译角色 Blueprint 以保存更改。

### Environment 属性

该 `Convai Chatbot` 组件（`UConvaiChatbotComponent`）公开一个 **环境** 类型为 `FConvaiEnvironmentData` 在 **Convai | 操作** 详细信息面板中的类别。

`FConvaiEnvironmentData` 具有以下顶级字段：

| 字段               | 类型                           | 作用                                                                                                                                                               |
| ---------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bEnableActions` | `bool`                       | 总开关。默认值为 `true`。当 `false`时，不会 `action_config` 在会话开始时发送，且操作被禁用。                                                                                                   |
| `操作`             | `TArray<FConvaiAction>`      | 角色可以执行的操作模板。                                                                                                                                                     |
| `对象`             | `TArray<FConvaiObjectEntry>` | 角色可以将其作为操作目标引用的场景对象。                                                                                                                                             |
| `Characters`     | `TArray<FConvaiObjectEntry>` | 场景中存在的其他角色。                                                                                                                                                      |
| `当前关注对象`         | `FConvaiObjectEntry`         | 当前位于聊天机器人注意槽中的对象（参见 [注意对象与指代消解](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/attention-and-reference-grounding.md)). |

#### 启用操作

**启用操作** 默认值为 `true` 在每个新的 `Convai Chatbot` 组件上——新角色无需手动步骤。若要为只需对话而不执行物理任务的角色禁用操作，请展开 **环境** 详细信息面板中的并取消勾选 **启用操作**.

### 定义操作模板

其中的每一项 `操作` 数组都是一个 `FConvaiAction` 结构体，包含三个主要字段：

| 字段   | 类型                           | 作用                                                                                                                                              |
| ---- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `名称` | `FString`                    | 不含参数占位符的规范操作名称。必须与处理器名称完全匹配，包括空格和标点符号。                                                                                                          |
| `说明` | `FString`                    | 发送给 Convai 的可选自然语言提示，用于描述该操作的作用。                                                                                                                |
| `参数` | `TArray<FConvaiActionParam>` | 有序的类型化参数。请参见 [参数化操作](/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`. |

#### 默认操作

该 `操作` 数组默认预填充了四项：

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

默认值 **说明** 这些模板上的值均为空，只有 `跟随`，随附 `“跟随角色”`。您可以根据需要重命名、描述或移除任何默认操作。要移除默认操作，请在数组中选中它并点击删除按钮。

这四个默认项适用于任何新的 `Convai Chatbot` 组件。随附的 `BP_ConvaiChatbotComponent` 便捷 Blueprint 还附带一个额外的 `护送` 操作可直接使用，其 `等待操作` 条目已存在，但默认禁用。

#### 添加自定义操作

{% stepper %}
{% step %}

#### 添加新条目

点击 **+** 在 `操作` 数组。
{% endstep %}

{% step %}

#### 将操作命名为

设置 **名称** 一个唯一且具有描述性的动词短语，例如 `“打开门”`, `“Print”`，或 `“跳舞”`.
{% endstep %}

{% step %}

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

设置 **说明** 仅当仅凭操作名称含义不明确时才添加。请保持简短，或留空以减少发送给 Convai 的上下文。
{% endstep %}

{% step %}

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

向 **参数** 添加条目，如果该操作需要类型化输入。请参见 [参数化操作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/parameterized-actions.md).
{% endstep %}

{% step %}

#### 编译并生成处理器脚手架

点击 **编译** 在角色 Blueprint 上，然后生成处理器脚手架。请参见 [构建自定义操作处理器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/building-custom-action-handlers.md).
{% endstep %}
{% endstepper %}

#### 编写提示

| 做法            | 重要性                                                          |
| ------------- | ------------------------------------------------------------ |
| 简短且彼此区分的操作名称  | Convai 按名称匹配模板。 `“跳舞”` 比 `“执行舞蹈动画”`.                         |
| 简短或为空的描述      | 描述会随操作契约发送。额外的冗长文字只会增加上下文，并不会改善行为。                           |
| 明确区分的对象名称     | 使用 `“cube”` 和 `“gun”` 而不是 `“cube”` 和 `“cube2”` 这样引用参数才能可靠解析。 |
| **选择** 用于固定变体 | 一个 `舞蹈` 操作，带有一个 `类型` 参数，以及三个 **选择** 比三个分别的舞蹈模板（带重复描述）更好。     |
| 在播放前编译        | 新的或已编辑的操作模板在 Blueprint 编译之前不会对处理器可用。                         |

{% hint style="warning" %}
操作名称必须与所属 Actor 上的 Blueprint 函数或事件名称匹配，包括空格和标点。Unreal 解析处理器名称时不区分大小写，但 `“停止移动”` 和 `“StopMoving”` 是不同的名称。
{% endhint %}

### 实验性内置操作

在 `Convai Chatbot`中还有两个额外切换项，类别 `Convai|操作|实验`，可添加不会出现在 `操作` 数组中的内置操作。启用其中之一会在下次连接时将该操作加入发送给 Convai 的内容；处理器在组件内部运行，因此无需为其生成 Blueprint 处理器脚手架。

| 属性                           | 类型     | 默认值     | 作用                                                                                                                                                                                                            |
| ---------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bEnableRemindSelfAction`    | `bool` | `false` | 显示名称 **启用自我提醒操作**。添加内置的 **自我提醒** 操作：角色可以在另一个操作之后将其加入队列（例如 `移动到`）以在该操作完成后提醒自己要考虑或说什么，例如走到一幅画前然后描述它。提醒会在下一次对话停顿时传达，且绝不会打断正在进行的交流。                                                                               |
| `bEnableWatchPropertyAction` | `bool` | `false` | 显示名称 **启用监视属性操作**。添加内置的 **监视属性** 操作：角色可以按其精确上下文键（例如 `“FrontDoor.DoorState”`）对跟踪属性设置一次性监视，并在其下一次真实变化时收到通知，或者等待其达到特定值（例如 `“Platform.Movement = Stopped”`）。即使该属性自身的 **应响应** 是 `Never` 或 `自动`也会生效，并且监视在触发一次后自动解除。 |

这两个切换项都会在下一次会话开始时生效，并且需要 **启用操作**.

{% hint style="warning" %}
`启用自我提醒操作` 和 `启用监视属性操作` 是实验性的（类别 `Convai|操作|实验`）。其行为可能在未来版本中更改。
{% endhint %}

### 注册对象

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

| 字段        | 类型                             | 作用                                                                            |
| --------- | ------------------------------ | ----------------------------------------------------------------------------- |
| `名称`      | `FString`                      | 角色用于识别此对象的唯一标签。                                                               |
| `引用`      | `TWeakObjectPtr<AActor>`       | 此条目所代表的关卡内 Actor。                                                             |
| `说明`      | `FString`                      | 提供给 Convai 的可选通俗描述。                                                           |
| `对象引用`    | `EConvaiObjectReference`       | 显示名称 **对象为**. `整个 Actor` （在 Actor 边界处停止——这意味着要走到对象占地范围上）或 `特定组件` （走到某个特定子组件）。 |
| `接受半径`    | `float`                        | AI 必须靠近到什么程度才算移动完成。默认 `150` 厘米。                                               |
| `组件名称`    | `FString`                      | 用于 `特定组件` 模式的可选子组件名称。                                                         |
| `插槽或骨骼名称` | `FName`                        | 匹配组件上的可选插槽或骨骼名称。                                                              |
| `移动点`     | `TArray<FConvaiMovementPoint>` | 设计师可创建的可选命名目的地。启用其中任何一个时，它们将替代 `对象引用` 作为移动目标。                                 |

`对象引用` 替代了早期 beta 所使用的移动目标枚举和边界标志： `整个 Actor` 本身就意味着在对象边界处停止，因此不需要单独的标志。关于升级仍读取旧字段的项目，请参见 [迁移到 4.0.0-beta.27](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/overview/migrate-to-4-0-0-beta-27.md).

**要添加对象：**

1. 点击 **+** 在 `对象` 数组。
2. 设置 `名称` 设为一个简短且唯一的标签。
3. 分配 `引用` 使用取样器将其指定给目标 Actor。
4. 设置 `说明` 如果有帮助的话。
5. 调整 `对象引用` 和 `接受半径` 用于导航精度。

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

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

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

### 注册角色

该 `Characters` 数组的工作方式与 `对象` 完全相同，但表示聊天机器人可在诸如 `跟随`.

在会话开始时，如果 `bAutoFillConversationPartnerFromPlayer` 是 `true` 在聊天机器人组件上启用，插件可以自动将玩家对话伙伴添加到角色列表中。插件会使用它找到的第一个 `UConvaiPlayerComponent` ，必要时回退到玩家 Pawn `0` 命名为 `用户` 。此属性位于 **Convai | 会话** 详细信息面板的类别中，默认值为 `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

仅当环境必须在会话开始时根据运行时状态发生变化时才使用此重写。重写 `Gather Environment Extras` NPC Actor 上的 Blueprint 原生事件，以便在会话开始前添加额外的操作、对象或角色。该重写仅在 `StartSession` 时运行一次，并且是增量式的——不会替代详细信息面板中的默认项。

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

### 下一步

{% 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/8e18d509947b40274dca96b384f432486348198f" %}
[动作 Blueprint 参考](/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.