> 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/actions-editor.md).

# 动作编辑器

Convai Actions Editor 窗口参考——其四种模式、添加动作目录以及一键执行器配置。

Convai 动作编辑器用于定义 Convai 角色可以执行的内容——每个动作的名称、描述和绑定的执行器——而无需直接编辑 `ConvaiActionConfigSource` 。从其目录中添加内置执行器还会同时配置该执行器所需的对应组件，例如 `ConvaiGazeController` 或 `ConvaiBodyAnimationController`，并且都在同一个可撤销步骤中完成。

### 打开窗口

选择 **Convai > 动作编辑器** 来打开窗口。一个 **Character** 工具栏中的字段用于选择窗口显示哪个 `ConvaiCharacter`的动作，并在场景中只有一个角色时自动选中它。

### 模式

角色选择器下方的模式切换器可在同一角色的四种视图之间切换：

| 模式       | 显示                                                                                                 |
| -------- | -------------------------------------------------------------------------------------------------- |
| **动作**   | 默认视图：动作列表和所选动作的详情。                                                                                 |
| **场景知识** | 该角色的已知对象、已知角色以及初始注意力。                                                                              |
| **角色设置** | 该 `ConvaiActionDispatcher` （标记为 **Convai 动作运行器**）和 `ConvaiActionFeedbackRelay` 设置。                 |
| **Live** | 仅在播放模式下显示：当前正在运行的批次、最近批次的时间线，以及每个动作的运行次数。在播放模式开始时会自动选中自身，并将其重新标记为 **会话回顾** 在播放模式结束后、且上一次会话的录制仍可用时。 |

除 **Live** 之外，所有模式都禁用编辑，并显示说明横幅，当编辑器处于播放模式时。

### 动作列表与详情

左侧面板按每个动作一张卡片列出，并分组为 **此角色** （直接在此角色上创建的动作），后面是每个已分配的 `ConvaiActionSet`的一个可折叠组。选择一张卡片会在右侧面板打开其详情，分为四个框：

| 框             | 显示                                                                               |
| ------------- | -------------------------------------------------------------------------------- |
| **Command**   | 动作名称、描述，以及一个实时渲染预览，形式为 `可以向此 Convai 角色提出请求："..."`.                               |
| **场景行为**      | 已绑定的执行器组件及其解析状态，一个下拉列表，列出所有 `IConvaiActionExecutor` 在该角色层级中找到的项，以及一个对象字段备用项。     |
| **试试**        | 在不启动对话的情况下运行该动作——参见 [在不进行对话的情况下测试动作](#test-an-action-without-a-conversation) 下方。 |
| **高级** （默认折叠） | 参数、有效目标、超时、失败策略覆盖以及语音门控。                                                         |

### 添加动作目录

点击 **+ 添加动作 ▾** 在工具栏中打开目录。它列出所有带有 `[ConvaiActionArchetype]` ——随附、示例或项目定义——按固定顺序排列，由 `ConvaiActionArchetypeCatalog.BuildMenuItems()`:

1. **推荐** ——经过筛选的内置执行器，它们声明了一个 `FeaturedOrder`，并按该顺序排序。
2. **更多现成动作** ——其余随附的执行器，按字母顺序排列。
3. **示例动作** ——作为 SDK 示例随附的执行器，位于其自己的子菜单中。
4. **项目与包动作** ——第三方或项目定义的执行器，按系列分组到各自的子菜单中。

某个 **自定义（空白）** 末尾的条目会创建一个空白动作，不预设名称、行为或参数。项目定义的执行器永远不能将精选 **推荐** 部分挤到列表下方——内置项始终排在前面，无论存在多少项目特定执行器。

### 入门卡片

尚未有任何动作的角色会在动作列表位置显示一个“添加你的第一个动作”的引导区，包含四张一键入门卡片。每张都是一个内置执行器，并通过 `FeaturedOrder` 1–4：

| 顺序 | 入门                                       | Executor                           |
| -- | ---------------------------------------- | ---------------------------------- |
| 1  | 走向目标                                     | `ConvaiWalkToActionExecutor`       |
| 2  | 跟随玩家                                     | `ConvaiFollowPlayerActionExecutor` |
| 3  | 注视目标                                     | `ConvaiLookAtActionExecutor`       |
| 4  | 而改为使用——这两个行为驱动同一个 Animator，如果一起使用就会互相冲突。 | `ConvaiPlayGestureActionExecutor`  |

选择一张入门卡片会以与从 **+ 添加动作 ▾** ——参见 [一键配置](#one-click-provisioning) 下方。 **浏览所有现成动作……**，位于入门卡片旁边，打开与工具栏按钮相同的目录。

### 一键配置

添加内置执行器——无论来自入门卡片还是目录——都会作为一个单一的可撤销操作执行：

1. 一个新的 `ConvaiActionDefinition` 基于该执行器的 `[ConvaiActionArchetype]` 属性生成：其动作名称、描述、目标要求以及任何参数。
2. 执行器组件会添加到角色上；如果该角色层级中已存在匹配组件，则会复用它。
3. 如果该执行器声明了一个 `RequiredPeerHint` ——例如 `ConvaiGazeController` 或 `ConvaiNavMeshLocomotion` ——且该角色尚无匹配组件，那么该组件也会一并添加。
4. 新的定义会绑定到已添加或已复用的执行器，并追加到角色的动作列表中。

这正是使 **注视目标** 入门项能够同时添加两者 `ConvaiLookAtActionExecutor` 和 `ConvaiGazeController` 只需一次点击，以及 **走向目标** 同时添加两者 `ConvaiWalkToActionExecutor` 和 `ConvaiNavMeshLocomotion`。若某组件需要位于 *目标* 对象上而不是角色上——例如 `ConvaiActionTargetGroup` Count Target Group 所需的组件——则不会以这种方式配置，因为选择由哪个场景对象拥有它是一个创作决策，窗口无法替你做出。

如果执行器的对应组件可以解析，但未被自动添加——例如，通过 **自定义（空白）** 创建，随后再绑定到某个执行器的动作——则 **场景行为** 框提供一个一键 **添加并绑定** 按钮，并以执行器命名，例如 **添加并绑定观察目标**.

### 在不进行对话的情况下测试动作

所选动作的 **试试** 框会运行真实的分发路径，不会调用后端：

* **在编辑模式下**，这是一个 **预览**：在试运行字段中输入一句话，它会按照运行时使用的相同目标解析层级进行检查，显示它会匹配哪个目标以及在第几步匹配。
* **在播放模式下**，这是一个 **测试运行**：从 **有效目标**中选择一个目标，填写任何参数，然后点击 **立即运行**。运行会经过与真实 Convai 命令完全相同的分发路径，并以 ✓ 或 ✗ 报告结果，同时给出耗时；如果失败，还会给出原因。

### 下一步

{% content-ref url="/pages/7f0d213ddc809cfd39ab2bc41492ddf8e54b6c19" %}
[角色动作快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/quick-start.md)
{% endcontent-ref %}

{% 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/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/actions-editor.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.