> 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.md).

# Actions

## 什么是动作？

Convai 动作为你的 AI 角色提供了 **做事**，而不仅仅是说话。当玩家说“去箱子那里”或“挥手打招呼”时，Convai 后端会从你定义的菜单中选择合适的行为和目标。随后 SDK 会直接在你的 Unity 场景中执行该行为——常见用例无需编写脚本。

动作是对话与玩法之间的桥梁。你无需编写关键词检测逻辑，也无需为每一种可能的 NPC 回复都写脚本，只需一次性声明一组可能的行为。剩下的交给 AI 处理。

## 工作原理

当玩家与 Convai 角色对话时，以下过程会自动发生：

```mermaid
flowchart LR
    A([玩家发言\n或输入]) --> B[Convai\n选择动作 + 目标]
    B --> C[ConvaiActionDispatcher\n接收命令批次]
    C --> D{根据动作名称\n查找定义}
    D -->|找到| E[解析场景中的\n目标]
    E --> F[执行器运行\n该行为]
    F --> G([结果：\n成功 / 失败])
    D -->|未找到| H([步骤跳过\n或批次中止])
```

整个流程——从接收命令到执行行为——都由 SDK 处理。你只需定义哪些动作可用，并为每个动作分配正确的执行器组件。

## 关键概念

| 概念             | 它是什么                                       |
| -------------- | ------------------------------------------ |
| **Action**     | 角色可以执行的一个命名行为（例如， `Move To`, `挥手`, `拾取`)   |
| **目标**         | 动作所指向的场景对象或角色（例如， `箱子`, `守卫`)              |
| **执行器**        | 在你的 Unity 场景中执行该行为的 MonoBehaviour 组件       |
| **分发器**        | `ConvaiActionDispatcher` ——接收动作命令并调用正确的执行器 |
| **批次**         | 一次后端响应中返回的动作列表（例如，走到架子旁，然后拾起头盔）            |
| **Definition** | 在 Inspector 中将动作名称映射到执行器和目标要求的条目           |
| **锚定**         | 后端借助描述和当前注意对象，将模糊指代（“它”“那个”）解析为具体场景对象的过程   |

## 什么放在哪里

你的 NPC GameObject 上有两个组件协同工作：

| 组件                         | 用途                 |
| -------------------------- | ------------------ |
| `ConvaiActionConfigSource` | 在这里定义可用的动作、对象和角色   |
| `ConvaiActionDispatcher`   | 接收来自后端的命令并运行匹配的执行器 |

这两个组件都必须位于 **同一个 GameObject** 作为 `ConvaiCharacter`.

## 本节内容

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>快速入门</strong></td><td>通过一步一步的讲解，在几分钟内让你的第一个动作运行起来。</td></tr><tr><td><strong>配置动作</strong></td><td>在 Inspector 中定义动作、注册目标并微调行为。</td></tr><tr><td><strong>动作执行器</strong></td><td>了解 SDK 自带的每一种执行器，并学习何时使用它们。</td></tr><tr><td><strong>分发器与批次策略</strong></td><td>控制分发器在运行时如何排序和处理动作批次。</td></tr><tr><td><strong>编写自定义执行器</strong></td><td>使用 C# 构建你自己的执行器，以创建你需要的任何游戏行为。</td></tr><tr><td><strong>注意力与指代锚定</strong></td><td>了解对象描述和注意对象如何帮助 AI 解析玩家的模糊指代。</td></tr><tr><td><strong>调试与故障排查</strong></td><td>使用内置调试探针和逐步检查清单诊断问题。</td></tr></tbody></table>

## 结论

Convai Actions 将自然对话与游戏内行为连接起来。你定义角色 *可以* 能做什么——AI 决定 *当* 是位于 *为什么* 要这样做。本节页面将带你从第一个可用动作一直学到用 C# 编写完全自定义的执行器。


---

# 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.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.