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

# 角色动作快速入门

我们将配置一个现有的 Convai NPC 以执行角色动作。完成后，你的 NPC 将拥有默认动作处理器、移动设置、NavMesh 覆盖范围，以及一个已注册的对象目标，供你测试 `移动到`, `跟随`, `停止移动`，以及 `等待`.

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

### 前提条件

* Convai Unreal Engine 插件已安装，且 API 密钥已配置。请参见 [安装 Convai 插件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md) 和 [配置你的 API 密钥](/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 角色](/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` 组件上。

该 **动作** 数组预填充了 `移动到`, `跟随`, `停止移动`，以及 `等待`。在本快速入门中请保留这些条目不变。
{% endstep %}
{% endstepper %}

### 设置 Pawn 移动

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

{% stepper %}
{% step %}

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

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

{% step %}

#### 运行 设置 Convai Pawn Movement

右键单击蓝图资源，选择 **Convai**，然后 **设置 Convai Pawn Movement**.

该工具会根据其父类调整蓝图：

| 父类                       | 工具执行的操作                                                           |
| ------------------------ | ----------------------------------------------------------------- |
| 精确 `AActor` 父级           | 重新设定父类为 `APawn` 并添加 `Floating Pawn Movement` ，并应用 Convai 调校后的默认值。 |
| `APawn` （非 `Character`)  | 添加 `Floating Pawn Movement` （如缺失），并应用调校后的默认值。                     |
| `Character`              | 调校现有的 `Character Movement` 组件（最大行走速度、加速度、制动）。                     |
| 自定义 `Actor` 的子类，且不是 pawn | 会记录警告并保持父类不变。将父类重新设为 `APawn` 或 `Character`，然后再次运行该工具。             |
| 非 Actor 父类               | 会在输出日志中记录警告。请使用基于 Actor 的蓝图进行动作移动。                                |

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

### 添加导航网格

该 `移动到` 和 `跟随` 动作依赖 Unreal 内置的导航系统来找到通往目标地点的路径。如果没有构建 NavMesh，角色将无法计算路线，并会停留在原地。

{% stepper %}
{% step %}

#### 放置 Nav Mesh Bounds Volume

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

{% step %}

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

将体积缩放到覆盖角色应行走的所有区域。选择 **构建 > 构建路径** （或 **构建全部**).

按 **P** 在视口中切换绿色导航覆盖层。确认角色出生点下方以及所有计划目的地处都有绿色覆盖。
{% endstep %}
{% endstepper %}

### 添加默认动作处理器

该 `动作` 数组只声明了 Convai 可以让 NPC 执行的内容。NPC 仍然需要与之匹配的蓝图事件，用于 `移动到`, `跟随`, `停止移动`，以及 `等待` ，这样移动才能运行。

{% stepper %}
{% step %}

#### 添加处理器事件

打开 [内置动作处理器](/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 %}

### 测试默认移动动作

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

| 提示词                | 预期行为     |
| ------------------ | -------- |
| `“跟随我”`            | 角色会跟随玩家。 |
| `“停止”` 或 `“停止跟随我”` | 角色停止移动。  |

当 `bAutoFillConversationPartnerFromPlayer` 为 `true` 在聊天机器人上开启（默认值），因此 `“我”` 会解析为对话伙伴。

{% hint style="warning" %}
如果角色会说话但不会移动，则角色蓝图缺少对应的处理器事件，用于 `移动到`, `跟随`, `停止移动`，以及 `等待`。请参见 [内置动作处理器](/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 | 动作 > 环境 > 对象** 并点击 **+**.

设置：

* **名称** — 一个简短、独特的标签，Convai 可以准确返回，例如 `“cube”` 或 `“Crate”`.
* **引用** — 目标 Actor（使用选择器或吸管工具）。
* **描述** — 可选的自然语言提示，例如 `“地板上的一个蓝色立方体”`.

保持 **移动目标模式** 为开启 **将 Actor 作为目标** ，用于本快速入门。
{% endstep %}

{% step %}

#### 如有需要可添加更多对象

对每个可交互道具重复此操作。使用不同的名称，例如 `“cube”` 和 `“gun”` 而不是 `“cube”` 和 `“cube2”` 这样 Convai 才能选择正确的目标。
{% endstep %}
{% endstepper %}

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

在播放模式下，尝试组合多个默认动作的提示：

* `“去那个立方体。”` — 角色会走向已注册的对象。
* `“去那个立方体，等待几秒，然后去那个枪，最后回到我这里。”` — 角色会执行一个多步骤动作序列。

{% hint style="success" %}
当角色移动到命名对象并推进多动作序列时，动作管线就正常工作了。请保持已注册对象名称简短且明确，以便引用参数能够正确解析。
{% endhint %}

### 验证设置

继续之前，请确认：

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

### 后续步骤

{% 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/9d759a9e65c274645e91b88390d8bb2c4762bd80" %}
[配置动作](/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 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/character-actions-quick-start.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.