> 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/embodiment/emotion/troubleshooting-and-diagnostics.md). # 排查情绪问题 修复 Unity SDK 中常见的情绪管线问题，从完全没有面部输出到静默回退和口型同步冲突。 大多数情感问题可归入三类之一：完全没有视觉输出、分数在更新但面部不动，或者事件和脚本回调未触发。首先观察 `Current.DominantScore` 在播放模式中——这一信号可判断问题出在信号路径还是面部输出。 ### 检查实时状态 `ConvaiEmotionController` 无需额外工具，即可在播放模式下通过 Inspector 查看完整的管线状态。 | 观察什么 | 在哪里找到 | 它告诉你的信息 | | ---------------------------- | ------------------------------------------ | ----------------------------------------- | | **Current → Dominant Label** | `ConvaiEmotionController` 播放模式下的 Inspector | 当前占主导地位的规范情感。 `“neutral”` 表示没有活动的瞬时信号。 | | **Current → Dominant Score** | `ConvaiEmotionController` 播放模式下的 Inspector | 主导情感的平滑强度 \[0–1]。大于 0 的值确认管线正在接收和处理服务器信号。 | | **锁定情感** 复选框 | `ConvaiEmotionController` Inspector（任意模式） | 勾选后将忽略服务器信号。角色会保持锁定的表情。 | 若要在不进入播放模式的情况下预览表情，请启用 **锁定情感**，请设置 **锁定情感标签** 为一个规范标签，并将 **锁定强度** 移动到 `1.0`。由于 `ConvaiEmotionController` 继承 `[ExecuteAlways]` 自其基类，表情会立即在场景视图中更新。 [情感编辑器窗口](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/emotion-editor.md) 可同时为所有打开场景中的每个角色提供相同的预览。 {% hint style="danger" %} **锁定情感** 是一个序列化字段。其值会随场景或预制体保存。构建生产版本前务必将其禁用——一个序列化的 `是` 会在发布版本中悄然禁用所有实时情感响应。 {% endhint %} ### 第一线排查 当情感行为不符合预期时，请按顺序完成此检查清单。大多数问题会在第 1 或第 2 步解决。 {% stepper %} {% step %} #### 检查 Profile 字段 选择 NPC 的根 GameObject。在 `ConvaiEmotionController` 组件上，确认 **Profile** 字段不为空。 * **空** → 管线将使用 SDK 的运行时默认 Profile，该 Profile 会驱动每个受支持绑定的面部。如果你期望特定角色类型，请分配一个 `ConvaiEmotionProfile` 资源。 * **已分配** → 继续下一步。 {% endstep %} {% step %} #### 在播放模式中观察 DominantScore 按 **播放**，与角色交谈，并观察 **Current → Dominant Score** 在 `ConvaiEmotionController` Inspector。 * **分数升至 0 以上** → 管线正在接收服务器信号。问题位于下游的面部输出。跳至第 4 步。 * **分数保持为 0** → 控制器未接收情感信号。继续第 3 步。 {% endstep %} {% step %} #### 检查锁定情感和组件位置 有两个常见原因会阻止信号到达累加器： 1. **已勾选锁定情感** → 将其禁用。锁定期间，控制器会丢弃所有服务器事件。 2. **组件位于错误的 GameObject 上** → `ConvaiEmotionController` 必须与其一起位于角色的根 GameObject 上 `EmbodimentContext`。若位于子对象或其他 NPC 上，它不会接收正确角色会话的情感事件。 如果两者均不适用，请确认角色已主动连接——在情感信号到达前，它应能在 Console 中对语音作出响应。 {% endstep %} {% step %} #### 检查“无面部输出”警告 打开 Console。如果无法解析角色面部上的任何内容，控制器会记录一条警告： `[ConvaiEmotionController] 无法解析“”上的任何面部混合形状，因此情感状态会更新，但面部不会移动。` 这表示问题在于绑定本身，而非 Profile。 * 确认角色具有带混合形状的蒙皮面部网格。 * 确认网格的混合形状名称遵循受支持的约定（ARKit、Reallusion CC3/CC4 或 MetaHuman）。 * 对于不符合上述任何约定的绑定，请分配一个 `CustomRigConventionMap` 来驱动目标——参见 [角色 Rig 设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/character-rig-setup.md). {% endstep %} {% endstepper %} {% hint style="success" %} 完成检查清单后，如果 **Current → Dominant Score** 在交谈期间升至 0 以上且表情明显移动，则管线工作正常。 {% endhint %} ### 常见问题快速参考 | 症状 | 可能原因 | 修复方法 | | ---------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **面部不动；DominantScore 保持为 0** | 已启用锁定情感 | 禁用 **锁定情感** 时 `ConvaiEmotionController` | | **面部不动；DominantScore 保持为 0** | 组件位于错误的 GameObject 上 | 将 `ConvaiEmotionController` 到角色的根 GameObject，并与其一起放置 `EmbodimentContext` | | **DominantScore 更新但面部未改变** | 未解析到面部网格，或混合形状约定不受支持 | 在 Console 中检查“无法解析任何面部混合形状”警告；为不受支持的绑定分配一个 `CustomRigConventionMap` 用于不受支持的绑定 | | **着色器效果（腮红、泪水、汗水）从不出现** | `propertyName` 在一个 `materialBinding` 槽位中的属性与着色器公开的属性不匹配 | 根据材质验证属性名称——请参阅 [情绪输出绑定](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/output-bindings.md) | | **特定情感从不出现；角色保持中性** | 服务器标签不在分类体系中；静默回退为中性 | 在自定义分类体系中，将服务器标签作为别名添加到最接近的规范条目 | | **角色在整个会话期间保持一种表情** | `lockEmotion` 被序列化为 `是` 在场景或预制体中 | 禁用 **锁定情感**；保存场景（**Ctrl+S** / **Cmd+S**) | | **生产版本中没有情感响应** | `lockEmotion` 构建前保持启用 | 禁用 **锁定情感** 构建前；在 Inspector 中按预制体实例验证 | | **重新打开项目后，Profile 更改被还原** | 正在编辑软件包附带的只读 Profile 资源 | 使用 Inspector 的 **Create A Project Copy** 按钮，或者手动将资源复制到 `Assets/` 并分配该副本——请参阅 [资源所有权和写时复制](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/asset-ownership.md) | | **`OnEmotionChanged` 时 `ConvaiCharacterEventRelay` 始终不触发** | 角色引用未解析 | 启用 **Auto Resolve Character**，或分配 `ConvaiCharacter` 的 **角色** 字段 | | **`SetMood`/`SetEmotionOverride` 会静默回退为中性** | 传入的标签无法在此角色的分类体系中解析 | 使用以下方法验证： `TryResolveEmotionLabel` 再调用任一方法之前——请参阅 [情绪脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/scripting-api.md) | | **`[EmotionTaxonomyAsset]` Console 中的警告** | 自定义分类体系没有中性条目，或有多个中性条目 | 设置 `isNeutral = true` 恰好在一个分类体系条目上 | ### 未知服务器标签——静默中性回退 **症状：** Convai 发送的某种情感从未在角色身上出现。面部会恢复中性，仿佛没有收到信号。 **原因：** 当 Convai 发送的标签与活动分类体系中的任何规范标签或别名都不匹配时， `TryResolve` 返回 `否` 并且控制器会静默使用中性描述符。与不匹配的着色器属性名称不同，此故障 **不会产生 Console 警告** ——管线会继续正常运行，每帧写入中性分数。 **如何检测：** 1. 在播放模式中，展开 **Current → All Scores** 在 `ConvaiEmotionController` Inspector。如果你预期出现的情感分数恰好为 0.0，而对话显然需要该情感，服务器标签很可能未能解析。 2. 启用 **锁定情感**，请设置 **锁定情感标签** 为你预期的规范标签（例如 `“anticipation”`），并确认表情激活。如果激活，问题就在从服务器标签到分类体系的解析路径上——信号从未以你的分类体系可识别的标签到达。 **解决方法：** 打开你的自定义分类体系资源（如果使用内置默认项，则创建一个），并将服务器标签作为别名添加到最接近的语义匹配项。例如，如果 Convai 发送 `"兴奋"` 且它应映射到 `“anticipation”`上，添加 `"兴奋"` 至 **别名** 的列表中 `期待` 条目。请参阅 [情绪分类体系](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/emotion-taxonomy.md) 了解如何创建和分配自定义分类体系。 **验证：** 在播放模式中，观察 **Current → Dominant Label** 和 **Current → All Scores** ——当 Convai 发送此前未解析的标签时，预期情感的分数现在应高于 0。 ### 面部表情与 LipSync 冲突 **症状：** 角色说话时，嘴部运动会正确遵循音素，但嘴部区域的情感表情会消失，直到角色停止说话。 **原因：** 这是预期行为，并非错误。共享面部合成器仅对嘴部区域应用固定优先级——LipSync 高于 Emotion，高于任何自定义输出——因此在主动说话期间，唇形同步绝不会与情感嘴部姿势冲突。在非说话期间， `MouthInfluence` 会将情感姿势混合回来。请参阅 [面部组合](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/facial-composition.md) 了解合成器的图层模型和混合模式。 **如果上半脸（眉毛、眼睛、脸颊）在说话时也停止移动**，这不是预期的优先级规则——这些区域绝不会通过嘴部图层路由。请在 Console 中检查是否有“无法解析任何面部混合形状”警告，以确认角色绑定是否解析出独立的嘴部和通用面部混合形状目标；眉毛和嘴部形状共用同一混合形状名称的绑定可能导致这种串扰。 ### 表情冻结——角色忽略对话 **症状：** NPC 在整个会话期间保持单一表情，且从不响应 AI 情感信号。 **原因：** `lockEmotion` 被序列化为 `是` 在场景或预制体中——这是 Inspector 预览遗留的常见创作痕迹。 **解决方法：** 1. 选择 NPC 的根 GameObject。 2. 开启 `ConvaiEmotionController`，禁用 **锁定情感**. 3. 保存场景（**Ctrl+S** / **Cmd+S**). 如果有多个 NPC 预制体，请逐个检查——除非显式覆盖，否则该字段会按预制体实例保留。 **验证：** 在播放模式中， **Current → Dominant Label** 应随对话的发展而变化。 ### Profile 更改未保存 **症状：** 你在 Emotion Profile 资源上编辑设置，但重新打开项目或返回 Inspector 后更改会被还原。 **原因：** 你正在编辑 Convai 软件包内附带的 Profile 资源。软件包资源无法直接修改。 **解决方法：** 选择 Profile 资源并使用 Inspector 的 **Create A Project Copy** 按钮。副本会放在 `Assets/Convai/`下，会自动选中，并且角色会重新指向该副本。请参阅 [资源所有权和写时复制](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/asset-ownership.md) 了解为何拒绝直接编辑。 **验证：** 编辑副本中的一个值并重新打开 Inspector——该更改应会保留。 ### ConvaiCharacterEventRelay OnEmotionChanged 未触发 **症状：** 你将 Unity Event 连接到 **On Emotion Changed** 时 `ConvaiCharacterEventRelay`，但它在播放模式中从不触发。 **检查清单：** 1. **角色引用：** 二者之一 **Auto Resolve Character** 已启用，且一个 `ConvaiCharacter` 位于同一 GameObject 上，或者你已手动分配一个 `ConvaiCharacter` 的 **角色** 字段。若两者皆非，转发器会记录配置警告并保持非活动状态。 2. **组件已启用：** 确认 `ConvaiCharacterEventRelay` 组件已启用（Inspector 标题中的复选框已勾选）。 3. **订阅时机：** 转发器仅会在 Convai 会话建立后触发。请在 `OnEnable` 并在 `OnDisable` 中订阅，以从组件激活时刻起捕获所有事件。 4. **会话处于活动状态：** 在测试情感回调前，确认角色能够正常响应语音。 **验证：** 在播放模式中与角色交谈——每当新的情感信号到达时，UI 或回调目标应更新。 ### 控制台日志参考 以下消息会由 Emotion 系统显示在 Unity Console 中。 | 日志消息 | 组件 | 含义 | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------- | | `[ConvaiEmotionController] 无法解析“”上的任何面部混合形状，因此情感状态会更新，但面部不会移动。请检查角色是否具有带混合形状的蒙皮面部网格，以及其混合形状名称是否遵循受支持的约定（ARKit、Reallusion CC3/CC4 或 MetaHuman）。对于不使用上述任何约定的绑定，请分配 Custom Rig Convention Map。` | `ConvaiEmotionController` | 角色绑定上的任何网格或混合形状均未匹配受支持的约定。无法解析面部输出。 | | `如果在任何目标材质上都找不到已编写的属性名，则该绑定会记录一条警告：` | `MaterialPropertyEmotionBinding` | 每个已创作的 `propertyName` 在 Profile 的 Material Binding 列表中均未命中任何目标材质——很可能是拼写错误。 | | `[ConvaiEmotionController] 为 SetEmotionOverride 提供了“