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

### Environment 属性

该 `Convai 聊天机器人` 组件（`UConvaiChatbotComponent`) 会公开一个 **环境** 类型为以下类型的属性 `FConvaiEnvironmentData` 在 **Convai | 动作** Details 面板中的类别。

`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 聊天机器人` 组件上——新角色无需手动步骤。若要为仅应对话而不执行物理任务的角色禁用动作，请展开 **环境** 在 Details 面板中，然后取消勾选 **启用动作**.

### 定义动作模板

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

| 字段           | 类型                           | 目的                                                                                                                                               |
| ------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `名称`         | `FString`                    | 不包含参数占位符的规范动作名称。必须与处理器名称完全匹配，包括空格和标点符号。                                                                                                          |
| `描述`         | `FString`                    | 可选的人类语言提示，会发送给 Convai 以描述该动作的作用。                                                                                                                 |
| `Parameters` | `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`. |

#### 默认动作

该 `动作` 数组默认预填充了四个条目：

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

默认值 **描述** 这些模板中的值均为空，除了 `跟随`，其自带 `“跟随角色”`。你可以根据需要重命名、描述或移除任何默认动作。要移除默认动作，请在数组中选中它并点击删除按钮。

这四个默认项适用于任何新的 `Convai 聊天机器人` 组件。随附的 `BP_ConvaiChatbotComponent` 便捷 Blueprint 还附带一个额外的 `Escort` 动作可直接使用，而其 `等待动作` 条目已存在，但默认处于禁用状态。

#### 添加自定义动作

{% stepper %}
{% step %}

#### 添加新条目

点击 **+** 位于 `动作` 数组。
{% endstep %}

{% step %}

#### 将动作命名为

设置 **名称** 一个独特且具描述性的动词短语，例如 `"Open Door"`, `“打印”`，或 `“舞蹈”`.
{% endstep %}

{% step %}

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

设置 **描述** 仅在仅凭动作名称不够明确时使用。请保持简短，或留空，以减少发送给 Convai 的上下文。
{% endstep %}

{% step %}

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

向以下项添加条目： **Parameters** 如果动作需要带类型的输入。请参见 [参数化动作](/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”` 这样引用参数才能可靠解析。 |
| **Choices** 用于固定变体 | 一个 `舞蹈` 带有 `类型` 参数，以及三个 **Choices** 比三个带重复描述的独立舞蹈模板更好。                        |
| Play 前先编译          | 新的或已编辑的动作模板在 Blueprint 编译之前不会对处理器可用。                                          |

{% hint style="warning" %}
动作名称必须与所属 Actor 上的 Blueprint 函数或事件名称匹配，包括空格和标点符号。Unreal 对处理器名称的大小写不敏感解析，但 `"Stop Moving"` 和 `"StopMoving"` 它们是不同的名称。
{% endhint %}

### 实验性内置动作

在 `Convai 聊天机器人`，类别 `Convai|Actions|Experimental`上的另外两个开关，可添加永远不会出现在 `动作` 数组中的内置动作。启用其中一个会在下次连接时将该动作加入发送给 Convai 的内容；处理器在组件内部运行，因此无需为其生成 Blueprint 处理器脚手架。

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

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

{% hint style="warning" %}
`启用提醒自己动作` 和 `启用监视属性动作` 属于实验性功能（类别 `Convai|Actions|Experimental`）。其行为可能在未来版本中发生变化。
{% endhint %}

### 注册对象

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

| 字段                 | 类型                             | 目的                                                                            |
| ------------------ | ------------------------------ | ----------------------------------------------------------------------------- |
| `名称`               | `FString`                      | 角色用于标识此对象的唯一标签。                                                               |
| `Ref`              | `TWeakObjectPtr<AActor>`       | 此条目所代表的关卡内 Actor。                                                             |
| `描述`               | `FString`                      | 可选的自然语言描述，供 Convai 使用。                                                        |
| `ObjectReference`  | `EConvaiObjectReference`       | 显示名称 **对象是**. `整个 Actor` （在 Actor 边界处停止——这意味着需要走到对象的占地范围上）或 `特定组件` （走到特定子组件）。 |
| `AcceptanceRadius` | `float`                        | AI 需要靠近到什么距离，移动才视为完成。默认 `150` 厘米。                                             |
| `ComponentName`    | `FString`                      | 用于以下项的可选子组件名称： `特定组件` 模式。                                                     |
| `SocketOrBoneName` | `FName`                        | 匹配组件上的可选插槽或骨骼名称。                                                              |
| `MovementPoints`   | `TArray<FConvaiMovementPoint>` | 可选的设计师预设命名目的地。启用其中任何一个时，它们将替代 `ObjectReference` 作为移动目标。                       |

`ObjectReference` 取代了早期 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. 分配 `Ref` 使用吸管工具将其指定给目标 Actor。
4. 设置 `描述` 如果有帮助的话。
5. 调整 `ObjectReference` 和 `AcceptanceRadius` 以提高导航精度。

#### 使用 `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` 名为 `User` （User），在需要时使用。此属性位于 **Convai | Session** Details 面板中的类别，默认值为 `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` 时运行一次，并且是增量式的——它不会替代 Details 面板中的默认值。

```
// Blueprint 伪代码
// Blueprint 原生事件重载——在 NPC Actor Blueprint 中实现
Event GatherEnvironmentExtras(out ExtraActions, out ExtraObjects, out ExtraCharacters)
    // 追加依赖于运行时状态的任务特定项
    Add FConvaiAction("拾取", "拾取该物品", []) → 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.