> 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 中，点击 **Add Component** 并搜索 **Convai Action Config Source** (`Convai/Convai Action Config Source`).

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

{% step %}

#### 定义 Move To 动作

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

| 字段       | 值                    |
| -------- | -------------------- |
| **动作名称** | `移动到`                |
| **目标要求** | `对象`                 |
| **执行器**  | *（现在先留空——你会在下一步分配它）* |

留空 **超时时间（秒）** 在 `0` （无超时）。
{% endstep %}

{% step %}

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

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

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

该 **描述** 会发送给 Convai，并帮助后端解析像“那个箱子”或“工作台旁边的那个东西”这样的模糊指代。请用一句自然的句子来写，说明该对象所处的上下文。
{% endstep %}

{% step %}

#### 添加 TransformMoveToActionExecutor

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

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

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

{% step %}

#### 添加 ConvaiActionDispatcher

在同一个 NPC 上 `GameObject`，点击 **Add Component** 并搜索 **Convai Action Dispatcher** (`Convai/Convai Action Dispatcher`).

留空 **批处理策略** 在 `队列` 和 **失败策略** 在 `停止批处理` —— 这些是大多数场景下正确的默认值。
{% 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` 都会匹配同一个定义。空格会被保留—— `移动到` 和 `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, and the optional `goal` 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>&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.