对话动画故障排查

针对 Dialogue Animation 模块中的静默说话层、缺失动画、剪辑跳变、层索引错误和语音能量问题的按症状修复方案。

使用下面的诊断分支来确定问题是在配置层还是在 Animator 层，然后参照表格查看具体修复方法。

第一步诊断： 在播放模式下，选择角色并检查 ConvaiDialogueAnimationController。检查 HasValidIdleLibrary ——如果返回 false，则库缺失或为空。如果返回 true 但动画仍然异常，则问题出在 Animator Controller 或配置值上。

---

症状表

症状	可能原因	修复
完全没有待机动画	库 或 配置 字段未赋值	将一个 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 字段中的占位剪辑名称与预期名称不匹配	验证占位剪辑名称是否完全一致（区分大小写）。请参见 所需的占位剪辑名称 表。
两个角色同步播放动画	角色共享一个 DialogueAnimationRuntimeConfig 且使用相同的 DeterministicSeed	为每个角色创建单独的配置资源，并在各自的 Inspector 中设置不同的 DeterministicSeed 值。参见 示例 3.
动画在编辑器中正常，但在构建版本中不工作	示例资源位于 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 页面查看可用属性。

对话动画脚本 API