> 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/character-actions-quick-start.md).

# 角色动作快速入门

启用角色动作，设置 Pawn 移动和导航，注册场景对象，并在播放模式下验证默认移动动作。

我们将准备一个现有的 Convai NPC，使其能够执行角色动作。完成后，你的 NPC 将配备默认动作处理程序、移动设置、NavMesh 覆盖范围，以及一个已注册的对象目标，供你测试 `Move To`, `Follow`, `Stop Moving`，以及 `Wait For`.

{% embed url="<https://youtu.be/lB5_KRWdg_w>" %}
Convai AI 角色动作演练
{% endembed %}

### 前提条件

* 已安装 Convai Unreal Engine 插件并配置 API 密钥。请参阅 [安装 Convai 插件](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md) 并 [配置 API 密钥](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md).
* 关卡中包含一个 NPC Actor，其上有一个 `Convai Chatbot` 组件，以及一个 `Convai Player` 组件。它位于玩家 Pawn 上。请参阅 [添加你的第一个 Convai 角色](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/add-your-first-convai-character.md).
* 你的角色蓝图已打开，或可从以下位置访问： **内容浏览器**.

### 在聊天机器人上启用操作

{% stepper %}
{% step %}

#### 选择角色

在关卡中选择 NPC Actor。在 **详情** 面板中，选择 `Convai Chatbot` 组件。
{% endstep %}

{% step %}

#### 确认“启用操作”已开启

在 **Convai | 操作**，展开 **环境** 并确认 **启用操作** 已勾选。默认情况下 `true` 新建时 `Convai Chatbot` 组件。

该 **操作** 数组已预先填入 `Move To`, `Follow`, `Stop Moving`，以及 `Wait For`。快速入门期间请保留这些条目。
{% endstep %}
{% endstepper %}

### 设置 Pawn 移动

默认移动操作需要一个能够导航的 Pawn。该插件提供了一个编辑器实用工具，可为常见的角色设置配置移动功能。

{% stepper %}
{% step %}

#### 在内容浏览器中打开角色蓝图

在 **内容浏览器**中，找到你的角色蓝图（例如 MetaHuman 或 `ConvaiBaseCharacter` 导数）。
{% endstep %}

{% step %}

#### 运行“设置 Convai Pawn 移动”

右键单击蓝图资产，选择 **Convai**，然后选择 **设置 Convai Pawn 移动**.

该实用工具会根据蓝图的父类进行调整：

| 父类                        | 实用工具的操作                                                           |
| ------------------------- | ----------------------------------------------------------------- |
| 精确 `AActor` 父类            | 将父类更改为 `APawn` 并添加 `Floating Pawn Movement` 并使用针对 Convai 调整的默认设置。 |
| `APawn` （而不是 `Character`) | 添加 `Floating Pawn Movement` （如果缺少）并应用经过调整的默认值。                    |
| `Character`               | 调整现有的 `Character Movement` 组件（最大行走速度、加速度、制动）。                     |
| 自定义 `Actor` 子类，但不是 Pawn   | 记录一条警告，并保持父类不变。将父类重新设置为 `APawn` 或 `Character`，然后再次运行该实用工具。        |
| 非 Actor 父级                | 在输出日志中记录一条警告。请使用基于 Actor 的蓝图来实现动作移动。                              |

如果该实用工具报告了警告，请打开 **窗口 > 输出日志** 并搜索 `ConvaiContentBrowserContextMenu` 以读取该消息。
{% endstep %}
{% endstepper %}

### 添加导航网格

“ `Move To` ”和 `Follow` ”操作依赖 Unreal 内置的导航系统来寻找通往目的地的路径。如果未构建 NavMesh，角色就无法计算路线，只会停留在原地。

{% stepper %}
{% step %}

#### 放置 Nav Mesh Bounds Volume

打开 **窗口 > 放置 Actor** （或使用关卡编辑器的快速添加菜单）。搜索 `Nav Mesh Bounds Volume` 并将其拖入关卡。
{% endstep %}

{% step %}

#### 缩放体积并构建路径

缩放体积，使其覆盖角色应该行走的所有区域。选择 **Build > Build Paths** （或 **Build All**).

按 **P** 在视口中切换绿色导航覆盖层。确认角色生成点及所有计划目的地均被绿色覆盖。
{% endstep %}
{% endstepper %}

### 添加默认操作处理程序

该 `Actions` 数组仅声明 Convai 可以要求 NPC 执行哪些操作。NPC 仍需要与以下操作对应的蓝图事件： `Move To`, `Follow`, `Stop Moving`以及 `Wait For` 这样移动才能运行。

{% stepper %}
{% step %}

#### 添加处理程序事件

打开 [内置操作处理程序](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/built-in-action-handlers.md) 并将四个默认处理程序添加到 NPC Actor 蓝图中。使用 **创建 Convai 操作处理程序** 如果该功能可用；否则，请创建名称与操作名称完全一致的自定义事件。
{% endstep %}

{% step %}

#### 编译蓝图

点击 **编译** 和 **保存** 在添加处理程序后。如果这是你第一次测试此流程，请添加一个临时的 **打印字符串** 节点到每个处理程序的开头，以便确认事件已触发。
{% endstep %}
{% endstepper %}

### 测试默认移动操作

在“播放”模式下运行关卡，并等待会话连接。尝试以下语音提示：

| 提示                               | 预期行为     |
| -------------------------------- | -------- |
| `"Follow me"`                    | 角色会跟随玩家。 |
| `"Stop"` 或 `"Stop following me"` | 角色停止移动。  |

玩家会自动注册，只要 `bAutoFillConversationPartnerFromPlayer` 在聊天机器人上设为 `true` （默认值），因此 `"我"` 解析为对话对象。

{% hint style="warning" %}
如果角色会说话但不会移动，说明角色蓝图缺少以下事件的处理程序： `Move To`, `Follow`, `Stop Moving`以及 `Wait For`。请参阅 [内置操作处理程序](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/built-in-action-handlers.md) 以添加这些处理程序，然后重新测试。
{% endhint %}

### 注册场景对象

若要导航到关卡中的道具，请将它们添加到聊天机器人的环境中。

{% stepper %}
{% step %}

#### 添加对象条目

选中 NPC Actor 后，展开 **Convai | Actions > Environment > Objects** 并点击 **+**.

设置：

* **名称** — 简短且独特的标签，Convai 可以按原样返回，例如 `"立方体"` 或 `"箱子"`.
* **引用** — 目标 Actor（使用选择器或吸管工具）。
* **描述** — 可选的自然语言提示，例如 `"地板上的蓝色立方体"`.

将 **Object Is** 设为 **Whole Actor** ，用于本快速入门。
{% endstep %}

{% step %}

#### 按需添加更多对象

为每个可交互道具重复上述步骤。使用不同的名称，例如 `"立方体"` 和 `"枪"` 而不是 `"立方体"` 和 `"立方体2"` 这样 Convai 才能选择正确的目标。
{% endstep %}
{% endstepper %}

### 测试导航和操作序列

在 Play 模式下，尝试组合多个默认操作的提示：

* `"前往立方体。"` — 角色会走到已注册的对象处。
* `"前往立方体，等待几秒，然后前往枪的位置，最后回到我这里。"` — 角色会执行多步骤操作序列。

{% hint style="success" %}
当角色移动到指定名称的对象处，并依次执行多项操作时，说明操作流程已正常运行。注册对象的名称应简短且明确，以确保引用参数能够正确解析。
{% endhint %}

### 验证设置

继续之前，请确认：

* **已启用 Actions** 已在 `Convai Chatbot` 组件上勾选。
* 角色蓝图已配置移动（通过 **Setup Convai Pawn Movement** 或等效的手动设置）。
* 一个 `Nav Mesh Bounds Volume` 覆盖可行走区域，并且已构建路径。
* 角色蓝图中存在默认动作处理程序（或者你已根据 [内置动作处理程序](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/built-in-action-handlers.md)).
* 至少有一个对象已注册在 **环境 > 对象** 且具有有效的 **Ref**.

### 后续步骤

{% 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/9d759a9e65c274645e91b88390d8bb2c4762bd80" %}
[配置动作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/configuring-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 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/character-actions-quick-start.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.
