> 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/utilities/dialogue-animation/animator-controller-setup.md).
# 构建兼容的 Animator Controller
本页将引导你从头构建一个兼容的 Animator 控制器。如果你想跳过这一步并使用现成的控制器，请从以下位置复制示例 `Packages/`space.vars.sdk\_package\_id`/SamplesShared/Art/Animations/Dialogue/Controllers/ConvaiSample_Animator Controller` 并跳转到 [分配你的控制器](#assign-your-controller).
***
### 先决条件
* 查看 [Animator 控制器要求](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animator-controller-requirements.md) 以查看完整的层结构、所需状态名称、占位剪辑名称，以及 `DialogueAnimatorContract` 字段参考。
* SDK 示例资源位于 `Packages/`space.vars.sdk\_package\_id`/SamplesShared/Art/Animations/Dialogue/` — 包括占位剪辑和 Avatar 遮罩。
***
### 构建兼容的控制器
{% stepper %}
{% step %}
#### 创建 Animator 控制器
在项目窗口中，右键单击 → **创建 → Animator 控制器**。请为你的角色起一个合适的名称。
{% endstep %}
{% step %}
#### 添加四个层
打开 Animator 窗口（**Window → Animation → Animator**）。在层面板中，你会看到一个默认层（通常名为“Base Layer”）。
通过单击以下按钮再添加三个层 **+** 按钮（位于层面板中）。将这些层重命名为： `基础待机`, `待机叠加`, `身体说话`, `头部说话`。该模块使用层 *索引*，而不是名称，除非你通过以下方式覆盖它们： `DialogueAnimatorContract`.
将 Avatar 遮罩分配给第 1–3 层，以防止覆盖下半身。上半身遮罩包含在 SDK 中，位于：
```
Packages/com.convai.convai-sdk-for-unity/SamplesShared/Art/Animations/Dialogue/
```
{% endstep %}
{% step %}
#### 向每个层添加状态
对于 **第 0 层（基础待机）：** 添加一个名为以下名称的状态 `BaseIdle`.
对于 **第 1 层（待机叠加）：** 添加两个名为以下名称的状态 `IdleOverlay_A` 是位于 `IdleOverlay_B`.
对于 **第 2 层（身体说话）：** 添加两个名为以下名称的状态 `BodyTalk_A` 是位于 `BodyTalk_B`.
对于 **第 3 层（头部说话）：** 添加两个名为以下名称的状态 `HeadTalk_A` 是位于 `HeadTalk_B`.
该模块以编程方式驱动过渡——你无需在状态之间添加过渡箭头。
{% endstep %}
{% step %}
#### 分配占位剪辑
为每个状态分配其占位 `AnimationClip` 在该状态的 **Motion** 字段中。请使用 SDK 示例资源中的占位剪辑，或创建最小的 1 帧虚拟剪辑，并使用中列出的精确名称 [Animator 控制器要求](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animator-controller-requirements.md#required-placeholder-clips).
剪辑名称必须完全匹配——这些是模块使用的覆盖键。
{% endstep %}
{% step %}
#### 将你的控制器分配给角色
选择你的角色的根 GameObject。在 `Animator` 组件中，将你的新控制器拖到 **控制器** 字段中。
如果你已经有一个 `ConvaiDialogueAnimationController` 在角色上，它会自动检测同一 `Animator` 在同一个 GameObject 上。若要指定不同的 `Animator`，请将其显式分配给 **Animator 覆盖** 对话动画组件中的字段。
**预期结果：** 进入播放模式，并在选中角色的情况下打开 Animator 窗口——基础待机层应该正在播放。如果模块没有记录错误，并且 `HasValidIdleLibrary` 返回 `true`，则控制器连接正确。
{% endstep %}
{% endstepper %}
***
### 分配你的控制器
如果你正在使用示例控制器，或者刚刚构建了自己的控制器：
1. 选择你角色的根 GameObject
2. 找到 `Animator` 组件
3. 将你的控制器分配给 **控制器** 字段
***
### 下一步
{% content-ref url="/pages/9e00cc9c176681b9489a9cd12ee13917fd6f11ea" %}
[Animator Controller 要求](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animator-controller-requirements.md)
{% endcontent-ref %}
{% content-ref url="/pages/cf0343f3a0b58d2e8e0e7f1a0c9eee9a6c5ecd1d" %}
[对话动画快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/quick-start.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:
```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animator-controller-setup.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.