> 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/how-the-emotion-system-works.md).

# 情绪系统的工作原理

了解 Emotion 如何解析 Convai 响应中的情绪信号，对其进行平滑处理，并组合角色的面部与情绪。

`ConvaiEmotionController` 将 Convai 随响应发送的情绪信号转换为平滑、合成的面部表情，并单独跟踪角色更持久的静息心境。本页说明该输入来自何处、控制器如何解析并平滑它，以及结果如何到达角色的面部。

***

### 情绪输入来自何处

不同于 Gaze、Body Animation 和 Body Language——它们从场景中已经本地可见的状态决定一切：对话状态、骨骼绑定、附近目标——Emotion 的决策只有一部分是本地的。每一轮都会有两样东西从角色外部到来：

* **瞬时情绪本身。** Convai 会将其作为响应的一部分发出：一个情绪标签和一个强度，由所使用的任意检测提供方选出 `EmotionDetectionMode` 时 `ConvaiEmotionController` 请求。 **Responsive** (`EmotionDetectionMode.Nrclex`（默认）会在回复流式输出时读取它，因此在一次回复过程中，面部可以变化不止一次。 **Accurate** (`EmotionDetectionMode.Llm`）会在回复完成后读取一次，虽然更晚到达，但衡量的是含义而非措辞——对于使用英语以外任何语言说话的角色来说，这是更好的选择。 **关闭** 完全不请求任何信号；没有 `ConvaiEmotionController` 的角色会被视为 `关闭` ，默认如此。此设置位于 Unity 中的角色上——它决定 Convai 运行哪个提供方，而不是 Convai 控制台设置。
* **心境命令。** 当 Convai 的响应包含设置心境或反应指令时，它会通过 `MoodCommandHandlerAdapter` 到达该角色——这是 Convai 自动添加的基础设施， `ConvaiEmotionController` 会自动添加，绝不是你自行添加或配置的组件。该适配器调用的是同样的 `SetMood` 和 `SetEmotionOverride` 方法，你自己的游戏代码也可以调用——见 [心情](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/moods.md).

这两个入口点之后的一切——解析、平滑、混合、微表情生命周期以及输出——都在本地运行，就像其他所有具身模块一样。

***

### 控制器如何解析并平滑一个信号

传入的标签会先通过角色的 `EmotionTaxonomyAsset` 进行解析——例如 `喜悦` 这样的规范标签，以及该词表定义的任何服务器别名。词表无法解析的标签会记录一条警告并回退为中性。

解析后的标签和强度随后会进入一个内部评分累加器，它拥有两个独立、可分别读取的通道：

| 通道   | 公开表面                                                   | 它代表什么                                               |
| ---- | ------------------------------------------------------ | --------------------------------------------------- |
| 瞬时情绪 | `CurrentResolvedEmotion`, `CurrentNormalizedIntensity` | 角色对最新一句话的反应。会随每个传入信号上升和衰减，而一旦反应消退，就会回落到下方的心境。       |
| 心境   | `CurrentMoodLabel`, `CurrentMoodScore`                 | 角色在反应之间停留的状态——由其人格基线或由 `SetMood`设定，并会持续存在，直到有事将其改变。 |

活跃反应绝不会覆盖心境，而心境也不会作为当前瞬时情绪出现——角色可以明显地以 `惊讶` 做出反应，同时静息于 `喜悦` 下方的心境。见 [心情](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/moods.md) ，了解如何从你自己的代码控制第二通道。

在瞬时通道到达面部之前，还有两个额外设置会对其塑形：到达时可选的短暂过冲（micro-burst），让表情的进入更有冲击力；以及可选的混合，它允许主情绪与相关的词表互补项同时显现（`喜悦` 和 `信任`例如）而不是一个情绪直接取代另一个。两者都在 `ConvaiEmotionProfile` 来驱动目标——参见 [情绪配置文件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/emotion-profile.md).

***

### 表情如何到达面部

表情配方命名 *哪些部位应当移动* 从语义层面而言—— `MouthSmileLeft`, `BrowOuterUpRight`以及其余部分——而不是在某个特定网格上命名 blendshape。运行时，这些语义会通过一个精选查找表，映射到角色面部实际拥有的 blendshape 上，该查找表覆盖 ARKit、Reallusion CC3、Reallusion CC4 Extended 和 MetaHuman。因此，一个配置文件就能驱动任何受支持的骨架，无需按角色单独编写；若某个骨架不符合这些约定，则需要一个 `CustomRigConventionMap`.

Emotion 不会直接写入 blendshape。它会把自己合成后的表情，以及——在启用时——连续的微表情生命周期层（空闲漂移加上说话强调），提交给角色共享的面部合成器；LipSync 和其他所有面部贡献者也都是提交给同一个写入者。见 [面部组合](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/facial-composition.md) ，了解合成器如何解析对同一区域的重叠占用，例如说话时的嘴部。

Emotion 还可以通过可选的材质属性绑定，从合成后的分数驱动任意 shader 浮点属性——脸红、泪光、汗光——这与 blendshape 路径完全独立。见 [情绪输出绑定](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/output-bindings.md).

***

### “说话”对表情意味着什么

韵律耦合以及角色由说话驱动的微表情强调，只在角色确实正在执行一次说话轮次时适用，而该信号来自 [对话流程](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/conversation-flow.md) 当角色拥有它时：表情遵循相同的 `说话中` 对话状态，也就是 Body Animation 的 talk 层所读取的内容，而不是原始的 speech-started/speech-stopped 事件。Conversation Flow 会根据本地证据裁定一个轮次何时结束，而原始事件看不到这些证据，因此将表情与其绑定，能让面部的说话偏置与身体在同一时刻释放——见 [说话轮次如何结束](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/conversation-flow.md#how-a-speaking-turn-ends).

如果角色上没有 Conversation Flow 模块，Emotion 会回退到原始的 speech-started/speech-stopped 事件。

***

### 当需要时会自动添加 Conversation Flow

不同于 Gaze 和 Body Language，Emotion 的任何对话驱动行为默认都未开启——聆听抬升、思考姿态，以及两个一次性的反应强调（在进入 `反应中` 和 `被打断`时）在 `ConvaiEmotionProfile`中的强度都为零。提高以下任意一项： **Listening Reaction Strength**, **Thinking Reaction Strength**, **Reacting Accent Strength**，或 **Interrupted Flinch Strength** 高于 `0` 会请求 Convai 添加一个 `ConvaiConversationFlowController` ，如果尚不存在，则在运行时添加到角色上，方式与 Body Animation 的 **自动创建 Conversation Flow** 设置相同。控制台只会记录一次，并指出角色名称，因此你未添加的组件不会悄无声息地出现。见 [对话流程](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/conversation-flow.md#convai-adds-it-automatically-when-needed).

***

### EmotionDimensions：跨模块信号

除了类别标签之外，每个已解析情绪还携带连续的 `EmotionDimensions` — `效价`, `唤醒度`, `能动性`以及 `趋近`，每个都被钳制到 `[-1, 1]`。类别标签仍然作为已编写面部配方的权威依据；这些维度则为 Gaze、Body Language 和 Body Animation 提供一个统一的调制信号来读取，而不必让每个模块都了解 Emotion 的词表。

***

### 关键概念

| 概念                          | 它是什么                                                                                |
| --------------------------- | ----------------------------------------------------------------------------------- |
| `ConvaiEmotionController`   | “ `MonoBehaviour` 它负责一个角色的整个管线。每个角色添加一个。                                            |
| `ConvaiEmotionProfile`      | “ `ScriptableObject` 资源，保存所有可调参数：平滑、micro-burst、混合、心境和微表情生命周期。                      |
| `EmotionTaxonomyAsset`      | “ `ScriptableObject` 定义情绪词汇——规范标签、服务器别名和互补项。内置默认值是 Plutchik 的九种情绪，包括中性。             |
| `MoodCommandHandlerAdapter` | Convai 随 `ConvaiEmotionController` 一起添加的隐藏基础设施，因此 Convai 响应中的心境或反应指令可以到达该角色。绝不直接编写。 |
| `EmotionReading`            | 当前状态的不可变快照：主导标签和分数、所有分数、嘴部影响，以及心境标签和分数。可通过 `ConvaiEmotionController.Current`.       |
| `ConvaiCharacterEventRelay` | 一个对 Inspector 友好的组件，将情绪和心境变化回调暴露为 Unity Events——无需代码。                               |

***

### 组件放置

| 组件                          | 放置位置                                               | 备注                                                      |
| --------------------------- | -------------------------------------------------- | ------------------------------------------------------- |
| `ConvaiEmotionController`   | 在角色的根对象上 `游戏对象`，与角色的其他具身模块一起                       | 每个角色一个                                                  |
| `ConvaiEmotionProfile`      | 在你的 `Assets/` 文件夹中的任意位置，作为一个 `ScriptableObject` 资源 | 如有需要，可在多个角色之间共享；当你第一次在共享角色上编辑它时，Convai 会为你复制一个包中提供的配置文件 |
| `EmotionTaxonomyAsset`      | 在你的 `Assets/` 文件夹                                  | 可选——省略则使用内置的 Plutchik 集                                 |
| `MoodCommandHandlerAdapter` | 随 `ConvaiEmotionController`                        | 切勿自行添加或移除                                               |
| `ConvaiCharacterEventRelay` | 在任何 `游戏对象` 在场景中                                    | 自动解析 `ConvaiCharacter` 在同一个 `游戏对象`上；如有需要，拖入另一个角色        |

***

### 下一步

{% content-ref url="/pages/e4e5139a33824d66acc5af79e26ea948910fdcd0" %}
[情绪快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/f5a3aaba473b4dfb20969b46c9a49bc4b176f223" %}
[心情](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/moods.md)
{% endcontent-ref %}

{% content-ref url="/pages/5a9247365092d958f2d539ae98bdfe69f72df091" %}
[Emotion 配置文件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/emotion-profile.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/emotion/how-the-emotion-system-works.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.