> 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-unreal-engine-plugin/features/emotion/troubleshoot-emotion.md).

# 排查情绪问题

修复常见情绪问题——表情不显示、状态被意外锁定、morph target 不匹配，以及偏移更改没有可见效果。

大多数情感问题属于三类之一：没有 `情绪状态已更改` 事件根本没有触发、事件触发了但面部没有移动，或者由于锁定导致状态卡住。先在你的 `Print String` 你的……里面 `情绪状态已更改` 处理器中添加一个——这个信号可以判断问题是在会话/信号路径，还是在 morph target 应用阶段。

### 检查实时状态

该 `UConvaiChatbotComponent` 会显示情感状态，你可以在 Play In Editor 期间随时从 Blueprint 查询，无需额外工具。

| 检查内容        | 如何检查                             | 它告诉你什么                                   |
| ----------- | -------------------------------- | ---------------------------------------- |
| 事件是否触发      | 添加 `Print String` 在……中 `情绪状态已更改` | 如果它从未触发，则会话未传递情感数据，或者 `锁定情感状态` 正在阻止服务器更新 |
| 某个特定情感的当前分数 | 调用 `获取情绪分数` 并连接到 `打印浮点数`         | 高于……的值 `0.0` 证明情感处于活动状态                  |
| 状态是否被锁定     | 打印 `锁定情感状态` bool 属性              | `true` 表示服务器更新和服务器驱动的事件被抑制               |

要在不依赖实时对话的情况下验证 morph target 映射，请调用 `Force Set Emotion` 来自 `BeginPlay`，一个临时 Blueprint 输入或测试事件，或者一个调用……的可由编辑器调用的自定义包装函数 `Force Set Emotion`。然后检查是否 `获取情绪分数` 返回预期值，并且你的 `Set Morph Target` 节点有响应。

{% hint style="danger" %}
`锁定情感状态` 是一个复制属性。如果你将其设为 `true` 在测试期间，请确认它已重置为 `false` 在发布前——锁定状态会悄无声息地抑制所有实时情感响应，不会产生运行时错误。
{% endhint %}

### 第一线排查

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

{% stepper %}
{% step %}

#### 确认会话处于活动状态

该 `Convai Chatbot` 组件必须具有有效的 **角色 ID** 并且能够连接到 Convai。如果没有活动会话，情感数据就不会发送。

* 正常与角色对话并确认它会用音频回应。如果没有音频，先修复会话。
* 如果音频正常，但情感事件仍然从未触发，请导出诊断信息并查看连接日志，然后再将角色配置问题上报给 Convai 支持。
  {% endstep %}

{% step %}

#### 检查 On Emotion State Changed 是否触发

添加一个 `Print String` 节点在……中 `情绪状态已更改` 事件处理器。进入 Play In Editor 并与角色对话。

* **Print String 触发** → 信号路径正常。跳到第 4 步。
* **Print String 从未触发** → 事件没有到达你的处理器。继续第 3 步。
  {% endstep %}

{% step %}

#### 检查 Lock Emotion State

当 `锁定情感状态` 是 `true`，服务器驱动的更新会被丢弃 **和** `情绪状态已更改` 不会针对这些更新触发。

* **`锁定情感状态` 是 `true`** → 将其设为 `false` 以恢复服务器更新和事件。
* **`锁定情感状态` 是 `false`** → 问题在上游。确认聊天机器人组件具有有效的 Character ID，并且插件能够连接到 Convai。
  {% endstep %}

{% step %}

#### 检查情感分数

在你的事件处理器中，调用 `获取情绪分数` 获取你期望的情感，并打印返回值。确认：

1. 分数升至高于 `0.0` 当角色说出带有情感内容的话时。如果分数始终保持在 `0.0`, `Emotion Offset` 可能在抑制数值——参见 [偏移更改没有可见效果](#offset-changes-have-no-visible-effect).
2. Convai 发送的服务器标签与已识别标签之一匹配——参见 [情绪系统如何工作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/emotion/how-the-emotion-system-works.md#server-emotion-labels).
   {% endstep %}

{% step %}

#### 确认 Set Morph Target 目标指向的是正确的网格

如果分数高于 `0.0` 但面部没有移动：

1. 确认 **Morph Target Name** 在每个……上的 `Set Morph Target` 节点名称与角色的 Skeletal Mesh 上的名称完全一致。打开 Skeletal Mesh 资源并检查 **Morph Targets** 选项卡。名称不匹配会导致 `Set Morph Target` 悄无声息地什么也不做。
2. 如果角色使用多个 Skeletal Mesh 组件（身体、头部、头发），请确认每个 `Set Morph Target` 调用都指向拥有 morph targets 的网格。
   {% endstep %}
   {% endstepper %}

{% hint style="success" %}
完成检查清单后，如果 `Print String` 在……上触发 `情绪状态已更改`, `获取情绪分数` 返回高于……的值 `0.0`，并且 morph targets 在正确的网格上更新，则管线正常。
{% endhint %}

### 常见问题速查

| 症状                         | 最可能的原因                                                          | 修复                                                                  | 验证                                    |
| -------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------- |
| `情绪状态已更改` 从未触发             | 没有活动的 Convai 会话、响应没有情感数据包，或者 `锁定情感状态` 是 `true`                  | 检查 Character ID、API 密钥、连接诊断信息和锁定状态                                  | 与角色对话——事件触发，分数升至高于 `0.0`              |
| 事件触发；面部没有变化                | morph target 名称不匹配                                              | 比较 `Set Morph Target` 名称与……对照 **Morph Targets** Skeletal Mesh 上的选项卡 | 当分数上升时，Details 面板中的 morph target 值会变化 |
| 事件触发； `获取情绪分数` 始终保持在 `0.0` | `Emotion Offset` 抑制分数、未识别的服务器标签，或者 `Reset Emotion State` 没有新的更新 | 检查 `Emotion Offset` 值；与角色对话以触发新的更新；验证服务器标签                          | `获取情绪分数` 返回高于……的值 `0.0` 在下一次服务器更新时    |
| 角色始终显示相同的表情                | `锁定情感状态` 是 `true`                                               | 设置 `锁定情感状态` 到 `false`                                               | 解锁后，随着新的发言表情会变化                       |
| `Force Set Emotion` 没有可见结果 | morph target 不匹配，或处理器未应用分数                                      | 确认处理器会在……情况下运行 `Print String`；验证 `获取情绪分数` 以及 morph target 名称        | 强制分数与强度乘数匹配，且面部会更新                    |
| 偏移更改没有可见效果                 | 偏移仅在新的服务器更新到达时生效                                                | 更改偏移后，与角色对话以触发新的情感更新                                                | `获取情绪分数` 在下一次更新中反映新的偏置                |

***

### 对话期间表情从不变化

**症状：** 角色在说话，但面部没有任何情绪表情变化。 `情绪状态已更改` 从未触发。

**原因：** 没有活动的 Convai 会话、Convai 没有为该角色发送情感数据，或者 `锁定情感状态` 正在阻止服务器驱动的更新和事件。

**修复：**

1. 确认 `Convai Chatbot` 组件具有有效的 **角色 ID** 并且插件能够连接到 Convai。
2. 设置 `锁定情感状态` 到 `false`.
3. 添加一个 `Print String` 节点在……中 `情绪状态已更改` 处理器，以确认事件是否到达你的图表。
4. 如果音频正常，但事件仍然从未触发，请导出诊断信息并查看连接日志。

**验证：** 与角色对话—— `情绪状态已更改` 触发并 `获取情绪分数` 返回高于……的值 `0.0` 对于活动的情感。

***

### On Emotion State Changed 事件触发了，但面部没有变化

**症状：** 该 `Print String` 处理器中的……触发了，但网格上的 morph targets 没有更新。

**原因：** 分数为零、morph target 名称与 Skeletal Mesh 不匹配，或者 `Set Morph Target` 指向了错误的网格组件。

**修复：**

1. 调用 `获取情绪分数` 在处理器中……并打印返回值。如果分数是 `0.0`，请检查 `Emotion Offset` 以及是否有一个 `Reset Emotion State` 在会话早期调用将分数清零，而之后没有随后的服务器更新。
2. 确认 **Morph Target Name** 在每个……上的 `Set Morph Target` 节点与 Skeletal Mesh 上的 morph target 名称一致。打开 Skeletal Mesh 资源，切换到 **Morph Targets** 选项卡，并比较列出的名称。
3. 确认 `Set Morph Target` 指向拥有 morph targets 的 Skeletal Mesh 组件。

**验证：** 当 `获取情绪分数` 上升到高于 `0.0`，则在 Play In Editor 期间，Details 面板中 Skeletal Mesh 上对应的 morph target 值会变化。

***

### 情感状态卡住，服务器更新无效

**症状：** 无论角色说什么，它始终显示相同的表情。服务器驱动的更新似乎没有效果。

**原因：** `锁定情感状态` 是 `true`，或者重复的 `Force Set Emotion` 调用会覆盖每一次服务器更新。

**修复：**

1. 设置 `锁定情感状态` 到 `false` 在 `Convai Chatbot` 组件。在 Blueprint 中打印该布尔值以确认运行时的值。
2. 在你的 Blueprint 图表中搜索 `Force Set Emotion` 在 Tick 或每次响应时触发的调用。移除这些调用或对其加条件，以便服务器更新可以生效。

**验证：** 设置 `锁定情感状态` 到 `false`，与角色对话，并确认 `情绪状态已更改` 会随着分数变化而触发。

***

### Force Set Emotion 没有明显更新面部

**症状：** `Force Set Emotion` 虽然从 Blueprint 调用了，但角色的表情没有变化。

**原因：** 事件处理器没有将分数应用到 morph targets， `重置其他情感` 意外地被设置了，或者 morph target 名称与网格不匹配。

**修复：**

1. 添加一个 `Print String` 在……中 `情绪状态已更改` 以确认处理器在运行。调用 `获取情绪分数` 对于强制情感——返回值应与强度乘数匹配（`0.25`, `0.60`，或 `1.00`).
2. 确认 **重置其他情感** 是否按预期设置。如果 `false`，则强制分数会与现有分数合并，可能不会产生可见变化。
3. 确认你的 `Set Morph Target` 节点使用了 Skeletal Mesh 上存在的 morph target 名称。

**验证：** 在……之后 `Force Set Emotion`, `获取情绪分数` 返回预期值，并且映射的 morph target 在视口中更新。

***

### 偏移更改没有可见效果

**症状：** 更改 `Emotion Offset` 组件上的……不会明显改变表情强度。

**原因：** `Emotion Offset` 仅在新的服务器驱动更新到达时生效，不会回溯生效。它也不适用于通过 `Force Set Emotion`.

**修复：**

1. 更改偏移后，与角色对话以触发新的服务器情感更新。
2. 确认偏移值合理。分数会被限制在 `0.0`–`1.0` — 过大的偏移可能会使所有分数饱和或清零。
3. 要测试强制表情，请使用 `Force Set Emotion` 使用更高的强度级别，而不是依赖偏移。

**验证：** 更改偏移后与角色对话—— `获取情绪分数` 在下一次服务器更新时反映新的偏置。

***

### 诊断流程图

当文本检查清单无法定位问题时，请使用此流程图。从症状开始，然后按照与您在 Play In Editor 中观察到的情况相符的分支继续。

```mermaid
flowchart TD
    A([表情没有变化]) --> B{On Emotion State Changed 是否触发？}
    B -- 否 --> C{Lock Emotion State 是否为 true？}
    C -- 是 --> D[将 Lock Emotion State 设为 false]
    C -- 否 --> E{是否有活动的 Convai 会话？}
    E -- 否 --> F[修复会话：检查 Character ID\n和 API 密钥]
    E -- 是 --> G[导出诊断信息并查看\n连接日志]
    B -- 是 --> H{Get Emotion Score\n返回值是否高于 0.0？}
    H -- 否 --> I[检查 Emotion Offset 值；\n与角色对话以触发新的更新]
    H -- 是 --> J{morph target 名称是否与\nSkeletal Mesh 匹配？}
    J -- 否 --> K[修复 morph target 名称：\n从 Morph Targets 选项卡复制精确名称]
    J -- 是 --> L{Set Morph Target 是否指向\n正确的网格组件？}
    L -- 否 --> M[重新指向拥有\nmorph targets 的网格]
    L -- 是 --> N[管线正常——按更新检查\n处理器连接]
```

***

### 相关页面

{% content-ref url="/pages/c3081281b873e1a1b00439a147d3db6877743003" %}
[情绪系统的工作原理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/emotion/how-the-emotion-system-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/9ac48061a03a0400ae6e1769df358c2fb2a82536" %}
[情绪 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/emotion/emotion-blueprint-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/760d975e7440e1f0f9fb57d5477018161e976844" %}
[情绪快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/emotion/emotion-quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/83566839f3555aa1855858bb1bc0c20ed5a973cc" %}
[情绪示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/emotion/emotion-examples.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-unreal-engine-plugin/features/emotion/troubleshoot-emotion.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.