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

### “Environment” 属性

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

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

| 字段                       | 类型                           | 用途                                                                                                                                                               |
| ------------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bEnableActions`         | `bool`                       | 主开关。默认值为 `true`。当 `false`，不会有 `action_config` 在会话开始时发送，且操作被禁用。                                                                                                   |
| `操作`                     | `TArray<FConvaiAction>`      | 角色可以执行的操作模板。                                                                                                                                                     |
| `对象`                     | `TArray<FConvaiObjectEntry>` | 角色可引用为操作目标的场景对象。                                                                                                                                                 |
| `角色`                     | `TArray<FConvaiObjectEntry>` | 场景中的其他角色。                                                                                                                                                        |
| `CurrentAttentionObject` | `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 引用） | 跟随已注册的角色或玩家。    |
| `停止移动` | —               | 停止导航。           |
| `等待`   | `持续时间（秒）` （数值）  | 等待指定时长。         |

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

#### 添加自定义操作

{% 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 按名称匹配模板。 `“跳舞”` 比以下更容易作为目标： `“执行舞蹈动画”`.           |
| 简短或空的说明       | 说明会随操作契约发送。额外的文字只会增加上下文，却不会改善行为。                         |
| 明确区分的对象名称     | 使用 `“立方体”` 和 `“枪”` 而不是 `“立方体”` 和 `“cube2”` 这样引用参数才能可靠解析。 |
| **选项** 用于固定变体 | 一个 `舞蹈` 操作，带有一个 `类型` 参数，以及三个 **选项** 比三个带重复说明的独立舞蹈模板更好。   |
| 先编译再播放        | 新建或编辑的操作模板在 Blueprint 编译之前对处理器不可用。                       |

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

### 注册对象

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

| 字段                 | 类型                       | 用途                                                 |
| ------------------ | ------------------------ | -------------------------------------------------- |
| `名称`               | `FString`                | 角色用来识别此对象的唯一标签。                                    |
| `引用`               | `TWeakObjectPtr<AActor>` | 此条目所代表的关卡内 Actor。                                  |
| `描述`               | `FString`                | 提供给 Convai 的可选自然语言说明。                              |
| `MoveTargetMode`   | `EConvaiMoveTarget`      | `Actor 作为目标` （在 Actor 边界处停止）或 `组件作为目标` （走到特定的子组件）。 |
| `接受半径`             | `float`                  | AI 必须靠近到多近才算移动完成。默认值 `150` 厘米。                     |
| `ComponentName`    | `FString`                | 可选的子组件名称，用于 `组件作为目标` 模式。                           |
| `SocketOrBoneName` | `FName`                  | 匹配组件上的可选 Socket 或骨骼名称。                             |
| `bStepOntoBounds`  | `bool`                   | 当 `true`，AI 会走到对象顶部，而不是停在其边缘。                      |

**要添加对象：**

1. 点击 **+** 在该 `对象` 数组。
2. 将 `名称` 为一个简短的唯一标签。
3. 分配 `引用` 使用滴管将其分配给目标 Actor。
4. 将 `描述` 如有帮助，可填写。
5. 调整 `MoveTargetMode` 和 `接受半径` 以提高导航精度。

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

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

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

### 注册角色

该 `角色` 数组的工作方式与……完全相同 `对象` 但表示聊天机器人可在以下操作中引用的其他 NPC 或 AI 角色，例如 `跟随`.

在会话开始时，当 `bAutoFillConversationPartnerFromPlayer` 是 `true` 在聊天机器人组件上启用时，插件可以自动将玩家对话伙伴添加到角色列表。插件会使用找到的第一个 `UConvaiPlayerComponent` 它，并在需要时回退到玩家 Pawn `0` 中创建一个新的 C# 脚本， `用户` 。此属性位于 **Convai | 会话** 详细信息面板的类别中，默认值为 `true`。使用 `SetConversationPartner` 当您需要注册非玩家对话伙伴时。

### 运行时修改

{% hint style="info" %}
运行时修改适用于高级用例——大多数项目只需要上面的编辑器期设置。
{% endhint %}

您可以在运行时使用以下方法添加或移除条目： `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 上的 `收集环境额外内容` Blueprint 原生事件，以便在会话开始前追加额外的操作、对象或角色。该重写在 `StartSession` 时执行一次，并且是追加式的——不会替换详细信息面板中的默认值。

```
// Blueprint 伪代码
// Blueprint 原生事件重写——在 NPC Actor Blueprint 中实现
事件 GatherEnvironmentExtras(out ExtraActions, out ExtraObjects, out ExtraCharacters)
    // 追加依赖运行时状态的任务特定物品
    添加 FConvaiAction("拾取", "捡起物品", []) → ExtraActions
    添加 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" %}
[Actions 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 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/configuring-actions.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.