情绪故障排查

修复常见的 Convai Unity SDK 情绪管线故障——从没有面部输出到静默中性回退和 LipSync 冲突。

大多数情绪问题可归为三类之一：完全没有视觉输出、分数在更新但面部不动，或事件和脚本回调未触发。先查看 Current.DominantScore 在 Play Mode 中——这一个信号可以判断问题是在信号路径里，还是在面部输出里。

检查实时状态

ConvaiEmotionController 在 Play Mode 期间，直接在 Inspector 中显示完整的流水线状态，无需任何额外工具。

要看什么	在哪找到它	它告诉你什么
Current → 主导标签	ConvaiEmotionController Play Mode 中的 Inspector	当前占主导的规范情绪是哪一个。 "neutral" 表示没有活跃的瞬时信号。
Current → 主导分数	ConvaiEmotionController Play Mode 中的 Inspector	主导情绪的平滑强度 [0–1]。大于 0 的值可确认流水线正在接收并处理服务器信号。
锁定情绪 复选框	ConvaiEmotionController Inspector（任意模式）	勾选后，服务器信号会被忽略。角色将保持锁定的表情。

要在不进入 Play Mode 的情况下预览表情，请启用 锁定情绪，将 锁定情绪标签 设为一个规范标签，并将 锁定强度 到 1.0。因为 ConvaiEmotionController 继承自 [ExecuteAlways] 继承自其基类，表情会立即在 Scene 视图中更新。 情绪编辑器窗口 可同时为已打开场景中的每个角色提供相同的预览。

锁定情绪 是一个序列化字段。它的值会随场景或 prefab 一起保存。请务必在用于正式发布的构建前将其禁用——一个序列化的 true 会在发布版构建中悄悄禁用所有实时情绪响应。

第一线调查

当情绪表现不符合预期时，请按顺序完成此检查清单。大多数问题在第 1 步或第 2 步就能解决。

1

检查 Profile 字段

选中你的 NPC 根 GameObject。在 ConvaiEmotionController 组件上，确认 配置文件 字段不为空。

• 空 → 流水线将使用 SDK 的运行时默认配置运行，它会为每种受支持的骨骼驱动面部。如果你期望特定的角色类型，请指定一个 ConvaiEmotionProfile 资源。
• 已分配 → 继续下一步。

2

在 Play Mode 中查看 DominantScore

按 播放，对角色说话，并观察 Current → 主导分数 组件上的 ConvaiEmotionController Inspector。

• 分数升至 0 以上 → 流水线正在接收服务器信号。问题出在下游的面部输出。跳到第 4 步。
• 分数保持为 0 → 控制器没有接收到情绪信号。继续第 3 步。

3

检查 Lock Emotion 和组件位置

有两个常见原因会阻止信号到达累加器：

1. Lock Emotion 已勾选 → 将其禁用。控制器在锁定时会丢弃所有服务器事件。
2. 组件挂在了错误的 GameObject 上 → ConvaiEmotionController 必须位于角色的根 GameObject 上，并与其 EmbodimentContext一起。若放在子对象上或另一个 NPC 上，它就无法接收到正确角色会话的情绪事件。

如果都不是，请确认角色已实际连接——在情绪信号到达之前，它应先能在 Console 中对语音作出响应。

4

检查是否有“没有面部输出”警告

打开 Console。如果角色面部没有任何内容可被解析，控制器会记录一条警告： [ConvaiEmotionController] 在 '<name>' 上无法解析任何面部 blendshape，因此情绪状态会更新，但面部不会移动。 这说明问题出在骨骼本身，而不是配置。

• 确认角色拥有带 blendshape 的蒙皮面部网格。
• 确认网格的 blendshape 名称遵循受支持的约定（ARKit、Reallusion CC3/CC4 或 MetaHuman）。
• 对于不符合这些约定的骨骼，请分配一个 CustomRigConventionMap ——参见 角色骨骼设置.

完成检查清单后，如果 Current → 主导分数 在对话过程中升至 0 以上，并且表情有明显变化，则说明流水线正常。

常见问题速查

症状	可能原因	修复方法
面部不动；DominantScore 保持为 0	Lock Emotion 已启用	禁用 锁定情绪 在 ConvaiEmotionController
面部不动；DominantScore 保持为 0	组件位于错误的 GameObject 上	将 ConvaiEmotionController 到角色的根 GameObject 上，与 EmbodimentContext
DominantScore 在更新，但面部没有变化	没有解析到面部网格，或 blendshape 约定不受支持	在 Console 中检查“无法解析任何面部 blendshape”警告；分配一个 CustomRigConventionMap 用于不受支持的骨骼
Shader 效果（脸红、眼泪、汗水）始终不出现	propertyName 在一个 materialBinding 插槽与 Shader 公开的属性不匹配	根据材质核对属性名称——参见 情绪输出绑定
特定情绪从未出现；角色始终保持中性	服务器标签不在分类法中；静默回退为中性	在自定义分类法中将服务器标签添加为最接近的规范条目的别名
角色在整个会话中保持同一个表情	lockEmotion 序列化为 true 在场景或 prefab 中	禁用 锁定情绪；保存场景（Ctrl+S / Cmd+S)
正式构建中没有情绪响应	lockEmotion 在构建前仍保持启用	禁用 锁定情绪 在构建前；在 Inspector 中按每个 prefab 实例进行验证
重新打开项目后，Profile 更改会恢复	正在编辑随包提供的只读 profile 资源	使用 Inspector 的 创建项目副本 按钮，或者手动将资源复制到 Assets/ 并分配该副本——参见 资产所有权和写时复制
OnEmotionChanged 在 ConvaiCharacterEventRelay 从未触发	角色引用未解析	启用 Auto Resolve Character，或分配 ConvaiCharacter 中找到它，位于 Character 字段
SetMood/SetEmotionOverride 静默回退为中性	传入的标签在该角色的分类法中无法解析	用以下方式验证 TryResolveEmotionLabel 后再调用任一方法——参见 情绪脚本 API
[EmotionTaxonomyAsset] 在 Console 中的警告	自定义分类法没有中性条目，或有多个中性条目	将 isNeutral = true 在且仅在一个分类法条目上

未知服务器标签——静默回退为中性

症状： Convai 发送的某个情绪从未出现在角色上。面部会像没有收到信号一样回到中性。

原因： 当 Convai 发送的标签与当前分类法中的任何规范标签或别名都不匹配时， TryResolve 返回 false 控制器会静默使用中性描述符。与未匹配的 shader 属性名不同，此失败 不会产生任何控制台警告 ——流水线仍会正常运行，每帧写入中性分数。

如何检测：

1. 在 Play Mode 中，展开 Current → 所有分数 组件上的 ConvaiEmotionController Inspector。如果你期望看到的某个情绪分数恰好为 0.0，而对话明显需要它，那么服务器标签很可能没有被解析。
2. 启用 锁定情绪，将 锁定情绪标签 到你期望的规范标签（例如 "anticipation"），并确认表情会激活。如果会，问题就在从服务器标签到分类法的解析路径上——信号从未以你分类法识别的标签到达。

解决方法： 打开你的自定义分类法资源（如果使用内置默认值，则创建一个），并将服务器标签作为最接近语义匹配项的别名添加进去。例如，如果 Convai 发送 "excited" 并且它应映射到 "anticipation"，添加 "excited" 到 别名 列表中的 期待 条目。参见 情绪分类法 了解如何创建并分配自定义分类法。

验证： 在 Play Mode 中，查看 Current → 主导标签 和 Current → 所有分数 ——当 Convai 发送先前无法解析的标签时，预期的情绪现在应该会得分高于 0。

面部表情与 LipSync 冲突

症状： 角色说话时，嘴部动作能正确跟随音素，但嘴部区域的情绪表情会消失，直到角色停止说话。

原因： 这是预期行为，不是 bug。共享的面部合成器只对嘴部区域应用固定优先级——LipSync 高于 Emotion，高于任何自定义输出——因此在主动说话期间，口型同步不会与情绪嘴部姿态冲突。在不说话时， MouthInfluence 会将情绪姿态重新混合回来。参见 面部组合 了解合成器的层模型和混合模式。

如果上半张脸（眉毛、眼睛、脸颊）在说话时也停止移动，那就不是预期的优先级规则——这些区域从不会经过嘴部层。请通过在 Console 中检查“无法解析任何面部 blendshape”警告，确认角色的骨骼已分别解析出嘴部和普通面部的 blendshape 目标；如果眉毛和嘴部形状共享同一个 blendshape 名称，就可能导致这种串扰。

表情冻结——角色忽略对话

症状： NPC 在整个会话中保持单一表情，且从不对 AI 情绪信号作出反应。

原因： lockEmotion 被序列化为 true 在场景或 prefab 中——这是从 Inspector 预览中遗留的常见制作痕迹。

解决方法：

1. 选择 NPC 的根 GameObject。
2. 开启 ConvaiEmotionController，请禁用 锁定情绪.
3. 保存场景（Ctrl+S / Cmd+S).

如果你有多个 NPC prefab，请逐个检查——除非显式覆盖，否则该字段会按每个 prefab 实例保留。

验证： 在 Play Mode 中， Current → 主导标签 应随着对话发展而变化。

Profile 更改没有保存

症状： 你在 Emotion Profile 资源上编辑了设置，但在重新打开项目或返回 Inspector 时，更改会恢复。

原因： 你正在编辑 Convai 包内随附的 profile 资源。包内资源不能直接原地修改。

解决方法： 选中该 profile 资源并使用 Inspector 的 创建项目副本 按钮。副本会放在 Assets/Convai/下方，会自动选中，并且角色会重新指向它。参见 资产所有权和写时复制 了解为何不允许原地编辑。

验证： 在副本上修改一个值并重新打开 Inspector——更改应当保留。

ConvaiCharacterEventRelay OnEmotionChanged 未触发

症状： 你将一个 Unity Event 连接到了 On Emotion Changed 在 ConvaiCharacterEventRelay，但它在 Play Mode 中从未触发。

检查清单：

1. 角色引用： 任一 Auto Resolve Character 已启用，并且有一个 ConvaiCharacter 位于同一个 GameObject 上，或者你已手动分配了一个 ConvaiCharacter 中找到它，位于 Character 字段。如果两者都不满足，中继会记录配置警告并保持不活跃。
2. 组件已启用： 确认 ConvaiCharacterEventRelay 组件已启用（Inspector 标题栏中的复选框已勾选）。
3. 订阅时机： 中继只有在 Convai 会话建立后才会触发。请在 OnEnable 并在 OnDisable 中订阅，以便从组件激活的那一刻起捕获所有事件。
4. 会话处于活动状态： 在测试情绪回调之前，确认角色能正常响应语音。

验证： 在 Play Mode 中对角色说话——每当新的情绪信号到达时，UI 或回调目标应当更新。

控制台日志参考

以下消息会从 Emotion 系统出现在 Unity Console 中。

日志消息	组件	含义
[ConvaiEmotionController] 在 '<name>' 上无法解析任何面部 blendshape，因此情绪状态会更新，但面部不会移动。请确认角色拥有带 blendshape 的蒙皮面部网格，并且其 blendshape 名称遵循受支持的约定（ARKit、Reallusion CC3/CC4 或 MetaHuman）。对于不使用这些约定的骨骼，请分配一个 Custom Rig Convention Map。	ConvaiEmotionController	角色骨骼上的网格或 blendshape 都没有匹配受支持的约定。无法解析面部输出。
[MaterialPropertyEmotionBinding] '<name>' 具有已配置的材质属性插槽，但在任何目标材质上都未找到已配置的 shader 属性（<names>）。请确认属性名称（例如 "_EmotionBlush"）与角色所分配材质公开的属性匹配。	MaterialPropertyEmotionBinding	每一个已配置的 propertyName 在 profile 的 Material Binding 列表中的项都未在所有目标材质上命中——很可能是拼写错误。
[ConvaiEmotionController] SetEmotionOverride 收到了 '<label>'，但该角色的情绪词汇表没有定义它，因此面部保持中性。	ConvaiEmotionController	SetEmotionOverride 被调用时传入了当前分类法无法解析的标签。请用以下方式验证 TryResolveEmotionLabel 。
[ConvaiEmotionController] SetMood 收到了 '<label>'，但该角色的情绪词汇表没有定义它，因此角色处于无情绪状态。	ConvaiEmotionController	SetMood 被调用时传入了当前分类法无法解析的标签。
[EmotionTaxonomyAsset] 该情绪词汇表未将任何情绪标记为中性，因此正在使用替代项。	EmotionTaxonomyAsset	自定义分类法资源中没有带有 isNeutral = true。系统会合成一个回退中性项以便流水线继续运行。
[EmotionTaxonomyAsset] 该词汇表中有 N 个情绪被勾选为“Is Neutral”，仅使用第一个。	EmotionTaxonomyAsset	多个分类法条目具有 isNeutral = true。仅使用第一个。

有 没有控制台警告 当 Convai 发送无法识别的情绪标签时—— TryResolve 会静默回退到中性描述符。如果某个预期情绪从未出现在角色上，请参见 未知服务器标签——静默回退为中性 上文。

表情无响应——决策树

情绪输出绑定情绪分类法