> 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 覆盖范围以及一个已注册的对象目标，便于测试 `Move To`, `跟随`, `停止移动`，以及 `Wait For`.

{% embed url="<https://www.youtube.com/watch?v=yWqJQRttoEI>" %}
角色动作操作指南
{% 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 玩家` 在玩家 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。在 **Details** 面板中，选择 `Convai 聊天机器人` 组件。
{% endstep %}

{% step %}

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

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

该 **动作** 数组已预填充了 `Move To`, `跟随`, `停止移动`，以及 `Wait For`。在此快速开始中请保留这些条目。
{% endstep %}
{% endstepper %}

### 设置 Pawn 移动

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

{% stepper %}
{% step %}

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

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

{% step %}

#### 运行 Setup Convai Pawn Movement

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

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

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

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

### 添加导航网格

该 `Move To` 是位于 `跟随` 动作依赖 Unreal 内置的导航系统来找到到达目标地点的路径。没有构建 NavMesh，角色将无法计算路线并会停在原地。

{% stepper %}
{% step %}

#### 放置 Nav Mesh Bounds Volume

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

{% step %}

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

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

按 **P** 在视口中切换绿色导航覆盖层。确认角色生成点下方以及任何计划目标位置都有绿色覆盖。
{% endstep %}
{% endstepper %}

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

该 `动作` 数组只声明 Convai 可以要求 NPC 执行什么。NPC 仍然需要匹配的蓝图事件以用于 `Move To`, `跟随`, `停止移动`，以及 `Wait For` 在移动运行之前。

{% 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" %}
如果角色会说话但不会移动，则角色蓝图缺少用于 `Move To`, `跟随`, `停止移动`，以及 `Wait For`记录的警告。请参阅 [内置动作处理器](/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** 或等效的手动设置）。
* A `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:

```
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>
```

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.