> 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/troubleshooting.md).
# 对话动画故障排除
使用下面的诊断分支来确定问题是在配置层还是在 Animator 层，然后参照表格查看具体修复方法。
{% hint style="info" %}
**第一步诊断：** 在播放模式下，选择角色并检查 `ConvaiDialogueAnimationController`。检查 `HasValidIdleLibrary` ——如果返回 `false`，则库缺失或为空。如果返回 `true` 但动画仍然异常，则问题出在 Animator Controller 或配置值上。
{% endhint %}
***
### 症状表
| 症状 | 可能原因 | 修复 |
| ----------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 完全没有待机动画 | `库` 或 `配置` 字段未赋值 | 将一个 `DialogueAnimationLibrary` 是位于 `DialogueAnimationRuntimeConfig` 分配到该组件 |
| 角色卡在 T 姿势 | Animator Controller 未分配或结构错误 | 验证 `Animator` 组件是否具有包含四个层级以及所需状态名称的控制器 |
| Talk 层从未激活（角色说话时从不做手势） | `AutoCreateConversationFlow` 为 `false` 且没有注册 `IConversationFlowSource` ，或者 `配置` 未赋值 | 设置 **Auto Create Conversation Flow** 到 `true` （默认），或者确保在 `ConnectAsync` |
| Talk 层激活了，但权重始终不变（没有能量变化） | `ConvaiLipSync` 组件缺失 | 添加 `ConvaiLipSync` 到角色上，或者将 `UseLipSyncSpeechEnergy` 到 `false` 在配置中设置为禁用能量调制 |
| 只有头部手势，没有身体动作 | 所有 talk 剪辑都使用 `TalkBodyCoverage = HeadOnly` | 重新制作或重新分配具有 `TalkBodyCoverage = BodyAndHead` 或 `BodyOnly` 的 talk 剪辑，用于你希望在身体层播放的剪辑 |
| 带性别特定标记的剪辑从不播放 | `Character Gender` 组件上的设置与剪辑的 `Gender` 标签 | 设置 `Character Gender` 到 `Male` 或 `Female` 以包含带性别标签的剪辑，或者将剪辑标签改为 `Neutral` |
| 剪辑切换时没有过渡而是直接跳变 | `CrossFadeDurationOverride` 在某个剪辑条目上设置得非常低，或者 `TalkCrossFadeDuration` 在配置中接近于零 | 提高 `CrossFadeDurationOverride` （按每个剪辑），或者提高 `TalkCrossFadeDuration` 在 `DialogueAnimationRuntimeConfig` |
| 待机动画从不变化（卡在同一个剪辑上） | `IdleMaxHoldSeconds` 非常大，或者 `IdleBlendGateNearLoopWrap` 一直无限期地保持门控 | 降低 `IdleMaxHoldSeconds`；如果问题出在门控上，降低 `IdleBlendGateGraceSeconds` |
| 控制台中出现“Layer index out of range”错误 | Animator Controller 的层数少于四层 | 向控制器中添加缺失的层。必须有四个层（索引 0–3）。 |
| 控制台中出现“State 'BaseIdle' not found”（或类似）错误 | 控制器中的状态名称与契约不匹配 | 将 Animator Controller 中的状态重命名为与契约名称一致，或者创建一个 `DialogueAnimatorContract` 并输入正确的名称 |
| 占位剪辑未被覆盖（播放了错误的动画） | 状态的 Motion 字段中的占位剪辑名称与预期名称不匹配 | 验证占位剪辑名称是否完全一致（区分大小写）。请参见 [所需的占位剪辑名称](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animator-controller-requirements.md#required-placeholder-clips) 表。 |
| 两个角色同步播放动画 | 角色共享一个 `DialogueAnimationRuntimeConfig` 且使用相同的 `DeterministicSeed` | 为每个角色创建单独的配置资源，并在各自的 Inspector 中设置不同的 `DeterministicSeed` 值。参见 [示例 3](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/usage-examples.md#example-3--multi-character-corporate-onboarding). |
| 动画在编辑器中正常，但在构建版本中不工作 | 示例资源位于 `SamplesShared/` 中，可能不会包含在构建中 | 将所需的库和配置资源移动到项目的 `Assets/Resources/` 文件夹中，或者确保它们被某个场景对象引用 |
***
### 诊断步骤
验证 Animator Controller 契约
如果看到找不到状态的错误，请将控制器中的状态名称与契约进行比较：
1. 打开你的 Animator Controller（在 Project 窗口中双击它）
2. 检查每个层级是否包含以下状态： `BaseIdle`, `IdleOverlay_A`, `IdleOverlay_B`, `BodyTalk_A`, `BodyTalk_B`, `HeadTalk_A`, `HeadTalk_B`
3. 对于每个状态，选择它并验证 **Motion** 字段显示的是正确的占位剪辑名称
4. 如果任何名称不同，要么在控制器中重命名它，要么创建一个 `DialogueAnimatorContract` 具有正确名称的资源并将其分配给组件上的 **Contract** 字段
验证四层结构
1. 在 Hierarchy 中选择角色并打开 Animator 窗口（**Window → Animation → Animator**)
2. 在 Layers 面板中，确认按顺序存在四个层：Base Idle（索引 0）、Idle Overlay（索引 1）、Body Talk（索引 2）、Head Talk（索引 3）
3. 在播放模式下，检查 `RuntimeBaseIdleLayerIndex`, `RuntimeIdleOverlayLayerIndex`, `RuntimeBodyTalkLayerIndex`，以及 `RuntimeHeadTalkLayerIndex` 属性在 `ConvaiDialogueAnimationController` 分别返回 0、1、2 和 3
4. 如果任何索引错误，说明控制器中的层顺序不对——请重新排序，或者使用一个 `DialogueAnimatorContract` 来映射正确的索引
***
### 下一步
如果你已经解决了问题，并且想在运行时监控层行为，请参阅 Scripting API 页面查看可用属性。
{% content-ref url="/pages/9be0dcfc097dc8444409730b1036b4a2f70ec112" %}
[对话动画脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/scripting-api.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/troubleshooting.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.