> 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).
* 关卡中包含一个带有 `Convai 聊天机器人` 组件以及一个 `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 聊天机器人` 组件。
{% endstep %}

{% step %}

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

在 **Convai | 动作**，展开 **环境** 并确认 **启用动作** 已勾选。它默认是 `true` 在新的 `Convai 聊天机器人` 组件上。

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

### 设置 Pawn 移动

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

{% stepper %}
{% step %}

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

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

{% step %}

#### 运行 Setup Convai Pawn Movement

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

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

| 父类                       | 该工具所做的操作                                                             |
| ------------------------ | -------------------------------------------------------------------- |
| 完全匹配 `AActor` 父类         | 重新设为父类为 `APawn` 并添加 `Floating Pawn Movement` 节点到每个处理器的开头，以便确认事件是否触发。 |
| `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 蓝图中。使用 **Create Convai Action Handler** （如可用），或者使用准确的动作名称创建自定义事件。
{% endstep %}

{% step %}

#### 编译蓝图

点击 **编译** 和 **保存** ，在添加处理器后保存。如果你是第一次测试该流程，请添加一个临时的 **Print String** 节点到每个处理器的开头，以便确认事件是否触发。
{% 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”`.
* **Ref** — 目标 Actor（使用选择器或吸管工具）。
* **描述** — 可选的自然语言提示，例如 `“地板上的一个蓝色立方体”`.

保留 **对象是** on **整个 Actor** 用于此快速入门。
{% endstep %}

{% step %}

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

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

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

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

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

{% hint style="success" %}
当角色移动到指定对象并推进多动作序列时，说明动作流程正常。请保持已注册对象名称简短且无歧义，以便引用参数正确解析。
{% endhint %}

### 验证设置

继续之前，请确认：

* **启用动作** 已在 `Convai 聊天机器人` 组件。
* 角色蓝图已配置移动（通过 **Setup 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)).
* 至少有一个对象已在 **环境 > 对象** 中注册，并带有有效的 **Ref**.

### 下一步

{% 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.