> 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（任意模式）  | 勾选后将忽略服务器信号。角色会保持锁定的表情。                     |

若要在不进入播放模式的情况下预览表情，请启用 **锁定情绪**，将 **Locked Emotion Label** 设为规范标签，并将 **Locked Intensity** 设为 `1.0`。由于 `ConvaiEmotionController` 继承了基类中的 `[ExecuteAlways]` ，表情会立即在场景视图中更新。使用 [情绪编辑器窗口](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/emotion-editor.md) 还可以同时预览所有已打开场景中的每个角色。

{% hint style="danger" %}
**锁定情绪** 是一个序列化字段，其值会随场景或预制件一起保存。面向生产环境构建前，请务必将其禁用——序列化值为 `true` 会在发布的构建中悄然禁用所有实时情绪响应。
{% endhint %}

### 初步排查

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

{% stepper %}
{% step %}

#### 检查 Profile 字段

选择 NPC 的根 GameObject。在 `ConvaiEmotionController` 组件上，确认 **Profile** 字段不为空。

* **为空** → 管线会使用 SDK 的运行时默认配置文件，为所有受支持的绑定驱动面部表情。如果你预期使用特定角色类型，请指定一个 `ConvaiEmotionProfile` 资源。
* **已分配** → 继续下一步。
  {% endstep %}

{% step %}

#### 在播放模式下观察 DominantScore

按下 **播放**，与角色交谈，并观察 **Current → Dominant Score** 上的 `ConvaiEmotionController` 检查器。

* **分数升至 0 以上** → 管线正在接收服务器信号。问题出在下游的面部输出。跳至第 4 步。
* **分数仍为 0** → 控制器未收到情绪信号。继续第 3 步。
  {% endstep %}

{% step %}

#### 检查 Lock Emotion 和组件位置

有两个常见原因会导致信号无法到达累加器：

1. **Lock Emotion 已勾选** → 禁用此选项。锁定期间，控制器会丢弃所有服务器事件。
2. **组件位于错误的 GameObject 上** → `ConvaiEmotionController` 必须与角色的 `EmbodimentContext`一起挂载在角色的根 GameObject 上。如果将其放在子对象或其他 NPC 上，它就无法接收正确角色会话的情绪事件。

如果以上情况都不适用，请确认角色已建立连接——在情绪信号到达之前，角色应能在控制台中对语音做出响应。
{% endstep %}

{% step %}

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

打开控制台。如果无法解析角色面部上的任何内容，控制器会记录一条警告： `[ConvaiEmotionController] No facial blendshapes could be resolved on '<name>', so emotion state will update but the face will not move.` 这表示问题出在绑定本身，而非配置文件。

* 确认角色具有带有混合形状的蒙皮面部网格。
* 确认网格的混合形状名称符合受支持的命名规范（ARKit、Reallusion CC3/CC4 或 MetaHuman）。
* 如果绑定不符合上述任何规范，请指定 `CustomRigConventionMap` ——请参阅 [角色绑定设置](https://docs.convai.com/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**                               | Lock Emotion 已启用                                   | 禁用 **Lock Emotion** 上的 `ConvaiEmotionController`                                                                                                                                       |
| **面部不动；DominantScore 始终为 0**                               | 组件位于错误的 GameObject 上                               | 将 `ConvaiEmotionController` 移至角色的根 GameObject，与 `EmbodimentContext`                                                                                                                    |
| **DominantScore 更新，但面部没有变化**                               | 未解析出面部网格，或混合形状约定不受支持                               | 检查控制台中是否有“无法解析任何面部混合形状”警告；为不受支持的绑定指定一个 `CustomRigConventionMap` 。                                                                                                                      |
| **着色器效果（腮红、泪水、汗水）始终不显示**                                   | `propertyName` 中的 `materialBinding` 插槽与着色器公开的属性不匹配 | 请对照素材核实属性名称，参见 [情绪输出绑定](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/output-bindings.md)                                               |
| **特定情绪始终不出现；角色一直保持中性**                                     | 服务器标签不在分类体系中；静默回退为中性                               | 在自定义分类体系中，将服务器标签添加为最接近的规范条目的别名                                                                                                                                                         |
| **角色在整个会话期间始终保持同一种表情**                                     | `lockEmotion` 序列化为 `true` 在场景或预制件中                 | 禁用 **锁定情绪**；保存场景（**Ctrl+S** / **Cmd+S**)                                                                                                                                               |
| **生产构建中不会响应情绪**                                            | `lockEmotion` 在构建前保持启用                             | 禁用 **锁定情绪** 构建前；在 Inspector 中逐个预制件实例进行验证                                                                                                                                               |
| **重新打开项目后，配置文件更改会还原**                                      | 正在编辑随软件包提供的只读配置文件资源                                | 使用 Inspector 中的 **创建项目副本** 按钮，或手动将资源复制到 `Assets/` 并指定该副本——请参阅 [资源所有权与写时复制](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/asset-ownership.md) |
| **`OnEmotionChanged` 开启 `ConvaiCharacterEventRelay` 从不触发** | 未解析角色引用                                            | 启用 **自动解析角色**，或分配 `ConvaiCharacter` 中的 **角色** 字段                                                                                                                                       |
| **`SetMood`/`SetEmotionOverride` 会静默回退到中性状态**              | 传入的标签无法在此角色的分类体系中解析                                | 调用任一方法前，请使用 `TryResolveEmotionLabel` 进行验证 — 请参阅 [情绪脚本 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/scripting-api.md)              |
| **`[EmotionTaxonomyAsset]` 控制台警告**                         | 自定义分类体系中没有中性条目，或存在多个中性条目                           | 将 `isNeutral = true` 设置在且仅设置在一个分类条目上                                                                                                                                                   |

### 未知的服务器标签 — 静默回退到中性状态

**症状：** Convai 发送的某种情绪不会显示在角色身上。即使信号已经到达，面部也会恢复为中性状态。

**原因：** 当 Convai 发送的标签与当前分类体系中的任何规范标签或别名都不匹配时， `TryResolve` 会返回 `false` ，控制器则会静默使用中性描述符。与未匹配的着色器属性名称不同，此类失败 **不会生成控制台警告** — 管线会照常继续运行，并在每一帧写入中性分数。

**检测方法：**

1. 在播放模式下，展开 **当前 → 所有分数** ，位置在 `ConvaiEmotionController` 检查器中。如果你预期出现的某种情绪分数恰好为 0.0，而对话内容显然应触发该情绪，那么服务器标签很可能无法解析。
2. 启用 **锁定情绪**，将 **锁定的情绪标签** 设为你预期的规范标签（例如 `"anticipation"`），并确认表情是否激活。如果激活了，问题就出在从服务器标签到分类体系的解析路径上 — 信号到达时使用的标签不受你的分类体系识别。

**修复方法：** 打开自定义分类体系资源（如果使用内置默认值，则创建一个），并将服务器标签添加为最接近的语义匹配项的别名。例如，如果 Convai 发送 `"excited"` ，而你希望将其映射到 `"anticipation"`，请将 `"excited"` 添加到 **别名** 列表中的 `anticipation` 条目。请参阅 [情绪分类体系](https://docs.convai.com/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，Emotion 又优先于任何自定义输出——因此在说话期间，唇形同步不会与情绪嘴型发生冲突。停止说话后， `MouthInfluence` 会将情绪姿势混合回来。请参阅 [面部合成](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/facial-composition.md) ，了解合成器的图层模型和混合模式。

**如果说话期间上半张脸（眉毛、眼睛、脸颊）也停止运动**，这就不符合预期的优先级规则——这些区域从未通过嘴部图层进行处理。请在 Console 中检查是否出现“无法解析任何面部 blendshape”警告，以确认角色的绑定是否解析出了独立的嘴部和一般面部 blendshape 目标；如果眉毛和嘴部形状共用同一个 blendshape 名称，可能会导致这种串扰。

### 表情冻结——角色对话时毫无反应

**症状：** NPC 在整个会话中保持同一种表情，从不响应 AI 的情绪信号。

**原因：** `lockEmotion` 在场景或预制件中被序列化为 `true` ——这是常见的创作遗留问题，通常是 Inspector 预览后留下的。

**修复方法：**

1. 选择 NPC 的根 GameObject。
2. 在 `ConvaiEmotionController`中，取消选中 **Lock Emotion**.
3. 保存场景（**Ctrl+S** / **Cmd+S**).

如果有多个 NPC 预制件，请逐一检查——除非显式覆盖，否则该字段会为每个预制件实例单独保留。

**验证：** 在播放模式下， **Current → Dominant Label** 应随着对话进展而变化。

### 配置文件更改未保存

**症状：** 你修改了 Emotion Profile 资源中的设置，但重新打开项目或返回 Inspector 时，更改又恢复了。

**原因：** 你正在编辑 Convai 软件包中自带的配置文件资源。软件包资源无法直接修改。

**修复方法：** 选择配置文件资源，然后使用 Inspector 中的 **Create A Project Copy** 按钮。副本会创建在 `Assets/Convai/`，会自动选中该副本，并将角色重新指向它。请参阅 [资源所有权与写时复制](https://docs.convai.com/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`上），但它在 Play Mode 下始终不会触发。

**检查清单：**

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

**验证：** 在 Play Mode 下与角色对话——每当收到新的情绪信号时，UI 或回调目标都应更新。

### 控制台日志参考

以下消息会由情绪系统输出到 Unity Console。

| 日志消息                                                                                                                                                                                                                                                                                                                                                                                     | 组件                               | 含义                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| `[ConvaiEmotionController] No facial blendshapes could be resolved on '<name>', so emotion state will update but the face will not move. Check that the character has a skinned facial mesh with blendshapes, and that its blendshape names follow a supported convention (ARKit, Reallusion CC3/CC4, or MetaHuman). For a rig using none of those, assign a Custom Rig Convention Map.` | `ConvaiEmotionController`        | 角色的骨骼绑定中没有网格或 blendshape 符合受支持的命名规范，无法解析面部输出。                                |
| `[MaterialPropertyEmotionBinding] '<name>' has authored material-property slot(s) but none of the authored shader properties (<names>) were found on any target material. Verify the property name(s) (e.g. "_EmotionBlush") match a property exposed by the character's assigned material(s).`                                                                                          | `MaterialPropertyEmotionBinding` | 配置文件 Material Binding 列表中填写的每个 `propertyName` 在所有目标材质中都未匹配到——很可能是拼写错误。       |
| `[ConvaiEmotionController] SetEmotionOverride was given '<label>', which this character's emotion vocabulary does not define, so the face stays neutral. Pass a label the vocabulary defines, or add it to that emotion's other words on the vocabulary asset.`                                                                                                                          | `ConvaiEmotionController`        | `SetEmotionOverride` 调用时传入的标签无法由当前分类体系解析。请先使用 `TryResolveEmotionLabel` 进行验证。 |
| `[ConvaiEmotionController] SetMood was given '<label>', which this character's emotion vocabulary does not define, so the character rests at no mood. Pass a label the vocabulary defines, or add it to that emotion's other words on the vocabulary asset.`                                                                                                                             | `ConvaiEmotionController`        | `SetMood` 调用时传入的标签无法由当前分类体系解析。                                               |
| `[EmotionTaxonomyAsset] This emotion vocabulary marks no emotion as the neutral one, so a stand-in will be used at runtime. Tick 'Is Neutral' on exactly one emotion — it is what the face relaxes to between feelings.`                                                                                                                                                                 | `EmotionTaxonomyAsset`           | 自定义分类体系资源中没有 `isNeutral = true`的条目。系统会生成一个备用中性项，以确保流程正常运行。                   |
| `[EmotionTaxonomyAsset] N emotions in this vocabulary are ticked 'Is Neutral' and only the first is used. Untick the others, so it is clear which one the face relaxes to.`                                                                                                                                                                                                              | `EmotionTaxonomyAsset`           | 多个分类体系条目都设置了 `isNeutral = true`。系统只使用第一个。                                    |

当 Convai 发送无法识别的情绪标签时， **不会显示控制台警告** —— `TryResolve` 会静默回退到中性描述符。如果预期的情绪始终没有在角色上显示，请参阅上文的 [未知服务器标签——静默回退到中性状态](#unknown-server-labels-silent-neutral-fallback) 。

### 表情无响应——决策树

```mermaid
flowchart TD
    A[表情未对情绪做出响应] --> B{对话期间\nDominantScore 是否上升？}
    B -- 否 --> C{是否启用了 Lock Emotion？}
    C -- 是 --> D[在 ConvaiEmotionController 上\n禁用 Lock Emotion]
    C -- 否 --> E{控制器是否位于角色\n根 GameObject 上？}
    E -- 否 --> F[将控制器移至角色根节点，\n与 EmbodimentContext 并列]
    E -- 是 --> G[确认角色会话处于\n活动状态——先测试语音]
    B -- 是 --> H{"无法解析任何面部混合\n变形"警告？}
    H -- 是 --> I[检查绑定规则；\n指定 Custom Rig Convention Map]
    H -- 否 --> J{说话时是否只有\n嘴部区域无法移动？}
    J -- 是 --> K[这是预期行为：说话期间\n嘴部区域由 LipSync 控制]
    J -- 否 --> L[检查 Material Binding 插槽上的\n着色器属性名称]
```

{% content-ref url="/pages/931fe5969b6c7b83aac82771a8aedc0f94f896d1" %}
[Emotion 输出绑定](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/output-bindings.md)
{% endcontent-ref %}

{% content-ref url="/pages/830c8a41ce176512408273566b88a4c868c56a59" %}
[Emotion 分类体系](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/emotion-taxonomy.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/troubleshooting-and-diagnostics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
