> 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 覆盖，以及一个已注册的对象目标，供你测试 `移动到`, `跟随`, `停止移动`，以及 `等待`.

{% 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。在 **Details** 面板中，选择 `Convai 聊天机器人` 组件。
{% endstep %}

{% step %}

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

在 **Convai | 操作**，展开 **Environment** 并确认 **启用操作** 已勾选。它在新的 `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` ，并使用 Convai 调优后的默认值。 |
| `APawn` （不是 `Character`) | 添加 `Floating Pawn Movement` 如果缺失，并应用调优后的默认值。                    |
| `Character`              | 调整现有的 `Character Movement` 组件（最大步行速度、加速度、制动）。                   |
| Custom `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 仍需要匹配的 Blueprint 事件来处理 `移动到`, `跟随`, `停止移动`，以及 `等待` 之前，才能运行移动。

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

### 测试默认移动动作

以 Play 模式运行关卡并等待会话连接。尝试这些口头提示：

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

玩家会被自动注册，当 `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 | Actions > Environment > Objects** 并点击 **+**.

设置：

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

保持 **对象为** 在 **整个 Actor** ，用于此快速开始。
{% endstep %}

{% step %}

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

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

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

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

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

{% 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)).
* 至少有一个对象已在 **环境 > 对象** 中注册，并且具有有效的 **引用**.

### 下一步

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