> 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/unity-plugin-beta-overview/features/actions/quick-start.md).
# 快速开始
## 让你的第一个动作运行起来
本指南将带你完成一个完整且可运行的示例：当玩家发出请求时，一个角色会移动到一个箱子旁。你将添加所需的组件，定义一个动作，注册一个对象目标，并在播放模式下测试全部功能。
{% hint style="info" %}
**先决条件**
* 一个 Unity 场景，其中有一个 `ConvaiCharacter` 组件已经设置好并可正常工作（在添加 Actions 之前，角色应能对语音做出响应）。
* 你的 Convai API 密钥已在以下位置配置： **工具 → Convai → 配置**.
* 场景中一个用作目标的 GameObject（立方体或任何对象都可以——将其重命名为 `箱子` 供本指南使用）。
{% endhint %}
## 逐步设置
{% stepper %}
{% step %}
**添加 ConvaiActionConfigSource**
在 **层级**中， **Inspector**点击 **添加组件** 并搜索 `Convai Action Config Source`.
你可以在此组件中定义可用动作，并将场景对象注册为目标。
{% endstep %}
{% step %}
**添加 ConvaiActionDispatcher**
在选中同一个 NPC GameObject 的情况下，点击 **添加组件** 再次点击并搜索 `Convai Action Dispatcher`.
该组件接收来自 Convai 后端的动作命令，并运行匹配的执行器。
{% hint style="info" %}
这两个组件都必须位于 **同一个 GameObject** 作为 `ConvaiCharacter`上，否则分发器将无法工作。
{% endhint %}
{% endstep %}
{% step %}
**添加 TransformMoveToActionExecutor**
仍然在同一个 NPC GameObject 上，点击 **添加组件** 并搜索 `Transform Move To Action Executor`.
该执行器会通过瞬间将角色位置对齐到目标来移动角色。这里使用它是为了让设置保持简单。
{% hint style="warning" %}
`Transform Move To Action Executor` 会瞬间传送角色，不带动画或寻路。它适用于 **仅用于原型开发**。用于正式产品时，请将其替换为 `NavMesh Move To Action Executor` ，或替换为使用你游戏移动系统的自定义执行器。
{% endhint %}
{% endstep %}
{% step %}
**定义“Move To”动作**
在 `Convai Action Config Source` 组件的检查器中：
1. 在 **动作定义**下，点击 **+** 按钮以添加新条目。
2. 设置 **动作名称** 到 `Move To`.
3. 设置 **目标要求** 到 `对象`.
4. 将 `Transform Move To Action Executor` 组件（来自同一个 GameObject）拖到 **执行器** 字段中。
留空 **超时秒数** 位于 `0` （无超时）。
你的定义应如下所示：
| 字段 | 值 |
| ---- | ----------------------------------------- |
| 动作名称 | `Move To` |
| 目标要求 | `对象` |
| 执行器 | `TransformMoveToActionExecutor` （从检查器中拖拽） |
| 超时秒数 | `0` |
{% endstep %}
{% step %}
**将箱子注册为对象目标**
仍在 `Convai Action Config Source`:
1. 在 **可操作对象**下，点击 **+** 按钮。
2. 设置 **名称** 到 `箱子`.
3. 设置 **说明** 到 `仓库地板上放着一个木箱`.
4. 将你的 `箱子` GameObject 从层级中拖到 **游戏对象引用** 字段中。
{% hint style="info" %}
该 **说明** 会告诉 Convai 后端这个对象是什么，并帮助 AI 解析诸如“它”或“那个东西”之类的模糊指代。请将其写成一句简短的话，在上下文中描述该对象。参见 [注意力与指代锚定](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/actions/attention-and-reference-grounding.md) 获取提示。
{% endhint %}
{% endstep %}
{% step %}
**在播放模式下测试**
按 **播放**。与你的角色对话（或使用 Convai 文本输入）：
> *“去箱子那里。”* *“移动到箱子那里。”* *“走到箱子那里。”*
角色的位置应瞬间对齐到箱子的位置。
{% hint style="success" %}
如果角色移动到了箱子旁，你的动作系统就工作正常。The `ConvaiActionDispatcher` 接收到了命令，将“箱子”解析为目标，并调用了 `TransformMoveToActionExecutor`.
{% endhint %}
{% endstep %}
{% endstepper %}
## 刚刚发生了什么
当你对角色说话时，发生了以下过程：
1. 你的语音被发送到了 Convai Cloud。
2. 后端识别出意图并选择了 `Move To` 带有以下内容的动作： `箱子` 作为目标。
3. `ConvaiActionDispatcher` 接收到了命令，查找了你的 `Move To` 定义，并将 `箱子` 解析到场景中的 GameObject。
4. `TransformMoveToActionExecutor` 运行，并将角色的位置瞬间对齐到箱子。
这一切都是自动发生的——无需编写代码。
## 接下来做什么
既然你已经有了一个可用的动作，不妨继续查看其余文档：
* 配置动作——学习如何添加更多动作、使用角色目标，并了解所有可用选项。
* 动作执行器——将 `TransformMoveToActionExecutor` 替换为类似以下的可用于生产的执行器： `NavMeshMoveToActionExecutor`.
* 编写自定义执行器——构建任何内置执行器未涵盖的行为。
## 结论
只需几个步骤，你就搭建起了一条完整的动作管线：一个角色会响应自然对话并移动到场景对象。接下来，你可以添加更多动作，替换为更复杂的执行器，并构建复杂的多步骤行为——所有这些都无需改变角色的通信方式。
---
# 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/unity-plugin-beta-overview/features/actions/quick-start.md?ask=
```
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.