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

# Animator Controller 要求

对话动画模块要求一个特定的四层 Animator 控制器结构，并包含命名状态和命名占位剪辑。本页是这些要求以及用于 `DialogueAnimatorContract` 它允许你使用非默认的层索引或状态名称。

***

### 运行时注入机制

该模块不会将特定剪辑硬编码到你的状态机中。相反，你控制器中的每个状态都会引用一个 **占位剪辑** —— 一个带有特定名称的短小、零权重的虚拟剪辑。运行时，模块会将这些占位剪辑替换为来自你的 `DialogueAnimationLibrary` 使用 Unity 的 `AnimatorOverrideController`。你的状态机过渡保持不变；只会更换各状态中替换进去的剪辑内容。

这种方法可让你在运行时切换整个资源库（例如，从平静的待机集切换到激动的待机集），而无需重新构建控制器。

***

### 四层要求

你的控制器必须按以下顺序恰好包含四个层：

| 层索引 | 名称（推荐） | Avatar 掩码 | 用途             |
| --- | ------ | --------- | -------------- |
| 0   | 基础待机   | 全身        | 持续播放的基础待机      |
| 1   | 待机覆盖层  | 上半身（推荐）   | 在后台循环播放的待机变体剪辑 |
| 2   | 身体对话   | 上半身       | 说话时的身体和手势剪辑    |
| 3   | 头部对话   | 头部和颈部     | 说话时的头部动作对话剪辑   |

第 0 层以恒定权重播放（默认 1.0）。第 1–3 层由模块进行混入和淡出。

{% hint style="warning" %}
控制器至少必须有四层。如果你的 Animator 少于四层，启动时会出现“Layer index out of range”错误。在进入 Play Mode 之前添加缺失的层。
{% endhint %}

***

### 所需的状态名称

每一层都必须包含具有这些精确名称的状态。名称区分大小写。

| 层         | 所需的状态名称                          |
| --------- | -------------------------------- |
| 0 — 基础待机  | `BaseIdle`                       |
| 1 — 待机覆盖层 | `IdleOverlay_A`, `IdleOverlay_B` |
| 2 — 身体对话  | `BodyTalk_A`, `BodyTalk_B`       |
| 3 — 头部对话  | `HeadTalk_A`, `HeadTalk_B`       |

模块对每层使用 A/B 乒乓模式——一个状态播放时，下一个状态会预先交叉淡入。即使你只为该层提供一个剪辑，该层中的两个状态也都必须存在。

***

### 所需的占位剪辑

每个状态都必须引用一个 **占位剪辑** ，其名称必须特定。模块通过匹配这些剪辑名称来识别要覆盖的槽位。

| 状态              | 占位剪辑名称                            |
| --------------- | --------------------------------- |
| `BaseIdle`      | `ConvaiDialogueSlot_BaseIdle`     |
| `IdleOverlay_A` | `ConvaiDialogueSlot_IdleOverlayA` |
| `IdleOverlay_B` | `ConvaiDialogueSlot_IdleOverlayB` |
| `BodyTalk_A`    | `ConvaiDialogueSlot_BodyTalkA`    |
| `BodyTalk_B`    | `ConvaiDialogueSlot_BodyTalkB`    |
| `HeadTalk_A`    | `ConvaiDialogueSlot_HeadTalkA`    |
| `HeadTalk_B`    | `ConvaiDialogueSlot_HeadTalkB`    |

{% hint style="danger" %}
即使状态名称正确，但占位剪辑缺失或名称错误，也会静默失败——模块无法识别覆盖槽位，该层将不会播放动画。务必始终确认占位剪辑名称完全匹配。
{% endhint %}

占位剪辑已包含在 SDK 示例资源中。你可以在示例控制器旁找到它们，或者在自己的项目中创建这些名称的最小 1 帧虚拟剪辑。

***

### DialogueAnimatorContract

如果你的 Animator Controller 使用不同的层顺序或不同的状态名称，请创建一个 `DialogueAnimatorContract` 资源并将其分配给 **契约** 字段上 `ConvaiDialogueAnimationController`.

**通过以下方式创建：** 资源菜单 → **创建 → Convai → Embodiment → 对话动画契约**

该契约将所有层索引和每个状态名称都作为可配置字段公开。默认值与上面列出的要求一致。一个 `DialogueAnimatorContract` 只有当你的 Animator 使用非默认的层索引或状态名称时才有必要——如果你复制了示例控制器，就不需要它。

| 契约字段                    | 默认                                |
| ----------------------- | --------------------------------- |
| `BaseIdleLayerIndex`    | `0`                               |
| `IdleOverlayLayerIndex` | `1`                               |
| `BodyTalkLayerIndex`    | `2`                               |
| `HeadTalkLayerIndex`    | `3`                               |
| `BaseIdleStateName`     | `BaseIdle`                        |
| `IdleOverlayStateA/B`   | `IdleOverlay_A` / `IdleOverlay_B` |
| `BodyTalkStateA/B`      | `BodyTalk_A` / `BodyTalk_B`       |
| `HeadTalkStateA/B`      | `HeadTalk_A` / `HeadTalk_B`       |
| 所有占位名称                  | 见上表                               |

***

### 下一步

{% content-ref url="/pages/547a1c8f364d8b30d06385d1f1f82837227e6c82" %}
[构建兼容的 Animator Controller](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animator-controller-setup.md)
{% endcontent-ref %}

{% content-ref url="/pages/0f3cbc0e4633317c448740563d0c38854e7725ee" %}
[动画库与配置文件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animation-libraries-and-profiles.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-requirements.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.