> 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).
# 快速开始
你第一个可工作的 Convai Action 的分步演练——从添加组件到在 Play 模式中测试实时命令。
## 让你的第一个动作运行起来
本指南将带你完成一个完整且可运行的示例：当玩家提出请求时，一个角色会移动到木箱旁。你将添加所需组件、定义一个动作、注册一个对象目标，并在播放模式中测试一切。
{% hint style="info" %}
**前置条件**
* 一个 Unity 场景，其中有一个 `ConvaiCharacter` 该组件已设置完毕并正常工作（在添加 Actions 之前，角色应能对语音做出响应）。
* 你的 Convai API 密钥已在以下位置配置： **工具 → Convai → 配置**.
* 场景中用作目标的一个 GameObject（立方体或任何对象都可以——请将其重命名为 `木箱` ，以便配合本指南）。
{% endhint %}
## 逐步配置
{% stepper %}
{% step %}
**添加 ConvaiActionConfigSource**
在以下位置中选择你的 NPC 的 GameObject： **层级**。在 **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` 组件的 Inspector 中：
1. 在 **动作定义**，点击 **+** 按钮以添加新条目。
2. 设置 **动作名称** 为 `移动到`.
3. 设置 **目标要求** 为 `对象`.
4. 将 `Transform Move To Action Executor` 组件（来自同一个 GameObject）拖入 **执行器** 字段。
保持 **超时时间（秒）** 在 `0` （无超时）。
你的定义应如下所示：
| 字段 | 值 |
| ------- | ------------------------------------------------- |
| 动作名称 | `移动到` |
| 目标要求 | `对象` |
| 执行器 | `TransformMoveToActionExecutor` （从 Inspector 中拖拽） |
| 超时时间（秒） | `0` |
{% endstep %}
{% step %}
**将 Crate 注册为对象目标**
仍在 `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" %}
如果角色移动到了木箱，你的动作系统就正常工作了。 `ConvaiActionDispatcher` 接收到了命令，将“Crate”解析为目标，并调用了 `TransformMoveToActionExecutor`.
{% endhint %}
{% endstep %}
{% endstepper %}
## 刚刚发生了什么
当你与角色对话时，发生了以下情况：
1. 你的语音已发送到 Convai Cloud。
2. 后端识别出意图并选择了 `移动到` 带有 `木箱` 作为目标的动作。
3. `ConvaiActionDispatcher` 接收到了命令，查找了你的 `移动到` 定义，并将 `木箱` 解析为场景中的 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 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/unity-plugin-beta-overview/features/actions/quick-start.md?ask=&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.
