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

# 角色动作快速开始

本指南将引导你连接一个“Move To”动作，使你的 NPC 在玩家请求时导航到场景中的对象。到最后，你的角色将能响应诸如“去箱子那里”这样的自然语言请求，并在场景中实际移动到它——无需代码。

### 先决条件

开始前，请确认：

* [ ] A `ConvaiCharacter` 组件已经位于你的 NPC 的 `GameObject`
* [ ] 你的场景中至少有一个目标对象，NPC 应该能够到达它

### 配置动作管线

{% stepper %}
{% step %}

#### 添加 ConvaiActionConfigSource

选择你的 NPC 的 `GameObject`。在 Inspector 中，点击 **添加组件** 并搜索 **Convai Action Config Source** (`Convai/Convai Action Config Source`).

你应该会在 Inspector 中看到四个新部分： **动作定义**, **可操作对象**, **可操作角色**，以及 **初始注意力**.

<figure><img src="/files/ba72139f2b0dc839a3de9312a2318c2a06a17204" alt="Unity Inspector showing ConvaiActionConfigSource added to the NPC GameObject with the four configuration sections: Action Definitions, Actionable Objects, Actionable Characters, and Initial Attention"><figcaption><p>已将 ConvaiActionConfigSource 添加到 NPC——这四个部分现在可用于配置后端在运行时可引用哪些动作、对象和角色。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 定义 Move To 动作

在 **动作定义** 列表中，点击 **+** 按钮以添加一项，然后填写这三个字段：

| 字段       | 值                   |
| -------- | ------------------- |
| **动作名称** | `Move To`           |
| **目标要求** | `对象`                |
| **执行器**  | *（暂时留空——下一步你会为它分配）* |

留空 **超时秒数** 位于 `0` （无超时）。

<figure><img src="/files/483cc855eb7c8f0e9632d5fee6104eae77d3a68e" alt="Unity Inspector showing a Move To action definition in ConvaiActionConfigSource with Action Name set to Move To and Target Requirement set to Object"><figcaption><p>Move To 动作定义——动作名称与 Convai 发送的命令字符串匹配；目标要求 Object 会告诉分发器在调用执行器之前先解析一个场景对象目标。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 注册一个目标对象

在 **可操作对象** 列表中，点击 **+** 并填写：

| 字段                | 值              |
| ----------------- | -------------- |
| **名称**            | `箱子`           |
| **说明**            | 左侧工作台旁的一个木质储物箱 |
| **GameObject 引用** | 将你的目标对象拖到这里    |

该 **说明** 会发送给 Convai，并帮助后端解析诸如“那个箱子”或“工作台旁边的那个东西”之类的模糊引用。请用一句自然的句子来写，让该对象处于上下文中。

<figure><img src="/files/6a150ac65bb4593625f7d49cf7117121aa7beaff" alt="Unity Inspector showing the Actionable Objects list on ConvaiActionConfigSource with a Crate entry including a descriptive name, description text, and a dragged-in GameObject reference"><figcaption><p>箱子已注册为可操作对象——Description 会发送给 Convai，并用于自然语言引用解析；GameObject Reference 保留在本地，绝不会传输。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 添加 TransformMoveToActionExecutor

在同一个 NPC 上 `GameObject`，点击 **添加组件** 并搜索 **Transform Move To Action Executor** (`Convai/Samples/Transform Move To Action Executor`).

返回到 **动作定义** 你在上一步创建的条目。拖动 `TransformMoveToActionExecutor` 组件到 **执行器** 字段中。

<figure><img src="/files/7c2fb5ad8948f8c9aa3a6f25a8a2fa1872797af1" alt="Unity Inspector showing TransformMoveToActionExecutor added to the NPC and its component reference assigned to the Executor field in the Move To action definition"><figcaption><p>已将 TransformMoveToActionExecutor 分配为 Move To 执行器——这完成了动作到行为的绑定，Convai 选择 Move To 动作时分发器会使用它。</p></figcaption></figure>

<figure><img src="/files/4527de26f357ca32f2ee0a0c6acdfcf1ff7913a1" alt="Executor field on the Move To action definition with TransformMoveToActionExecutor dragged in"><figcaption><p>将 TransformMoveToActionExecutor 拖到 Move To 动作定义中的 Executor 字段。</p></figcaption></figure>

{% hint style="warning" %}
`TransformMoveToActionExecutor` 仅用于原型设计。它会立即将角色传送过去，没有动画或寻路。发布给玩家之前，请将其替换为 `NavMeshMoveToActionExecutor` 或自定义执行器。
{% endhint %}
{% endstep %}

{% step %}

#### 添加 ConvaiActionDispatcher

在同一个 NPC 上 `GameObject`，点击 **添加组件** 并搜索 **Convai Action Dispatcher** (`Convai/Convai Action Dispatcher`).

留空 **批处理策略** 位于 `队列` 是位于 **失败策略** 位于 `停止批处理` ——这些是大多数场景下的正确默认值。

<figure><img src="/files/4a9a49943d0b4471dd99040b879bf6e3d00c0bde" alt="Unity Inspector showing ConvaiActionDispatcher added to the NPC GameObject with Batch Policy set to Queue and Failure Policy set to Stop Batch"><figcaption><p>已添加 ConvaiActionDispatcher——Queue 批处理策略和 Stop Batch 失败策略是大多数场景下的正确默认值，并且在此快速开始中无需进一步配置。</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### 验证设置

你的 NPC 的 `GameObject` 现在应当具备这四个组件：

```
ConvaiCharacter
ConvaiActionConfigSource   ← 动作定义 + 目标对象
ConvaiActionDispatcher     ← 接收并执行批处理
TransformMoveToActionExecutor  ← 执行移动行为
```

进入 Play Mode，并说“去箱子那里”或“移动到箱子”。你的 NPC 应该会传送到箱子的位置。

如果你添加了 `ConvaiActionDebugProbe` （可选——见 [角色动作故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/debugging-and-troubleshooting.md)），你也应该在 Console 中看到这一条：

```
[ConvaiActionDebugProbe] 步骤成功 #1：cmd='Move To crate'，def='Move To'，target=Object:Crate
```

如果 NPC 没有移动，请检查 [角色动作故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/debugging-and-troubleshooting.md) 以查看诊断清单。

### 运行时行为

**动作名称不区分大小写。** `Move To`, `move to`，以及 `MOVE TO` 都匹配同一定义。空格会保留—— `Move To` 是位于 `MoveTO` 不匹配。

**配置会在会话开始时发送一次。** 如果你在 Play Mode 中添加、重命名或移除动作或目标，请结束会话并重新连接，以使更改生效。

### 下一步

{% content-ref url="/pages/f592d9dc3ad261e175159690b86cdd4b50bb4d81" %}
[动作执行器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md)
{% endcontent-ref %}

{% content-ref url="/pages/c5598abd0ddd72fa75a0989ad602a5b4d12e16d7" %}
[编写自定义动作执行器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/writing-custom-executors.md)
{% endcontent-ref %}

{% content-ref url="/pages/111bca064ba7041a987662d038af4d71d58a32cd" %}
[配置角色动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/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-unity-sdk/features/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.