> 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/unity-plugin-beta-overview/features/emotion/emotion-taxonomy.md).

# Emotion Taxonomy

## 使用 EmotionTaxonomyAsset 定义情绪词汇表

该分类法是将 Convai 后端的原始情绪字符串转换为系统其余部分所使用的标准标签的字典。当服务器发送 `“happy”`时，分类法会将该别名解析为 `“joy”` ，这样以标准标签为键的累加器和输出绑定——就能准确知道要更新哪个分数。SDK 自带一个受 Plutchik 启发的九情绪默认分类；你也可以编写自定义的 `EmotionTaxonomyAsset` ，用于需要不同词汇或额外服务器标签的情况。

## 内置的 Plutchik 分类法

当 `分类法` 字段在一个 `ConvaiEmotionProfile` 中留空时，系统会在运行时合成以下集合。此默认配置涵盖了 Convai 后端当前产生的所有情绪，无需创建任何资源。

| 标准标签 | 服务器别名                    | 默认口部影响 |
| ---- | ------------------------ | ------ |
| `中性` | `平静`, `空闲`               | 0.0    |
| `喜悦` | `高兴`, `快乐`, `狂喜`, `宁静`   | 0.6    |
| `信任` | `接纳`, `钦佩`               | 0.3    |
| `恐惧` | `害怕`, `忧惧`, `惊恐`, `恐惧的`  | 0.4    |
| `惊讶` | `惊奇`, `分神`, `惊讶的`        | 0.5    |
| `悲伤` | `伤心`, `沉思`, `悲痛`         | 0.3    |
| `厌恶` | `厌恶的`, `憎恶`, `无聊`, `厌倦的` | 0.4    |
| `愤怒` | `生气`, `恼怒`, `暴怒`         | 0.55   |
| `期待` | `兴趣`, `警惕`               | 0.45   |

**默认口部影响** 是一个按情绪划分的提示值（0–1），用于告诉面部混合形状合成器：当角色未在说话时，情绪驱动的口型应占多大比重。在主动说话期间，LipSync 会根据音素数据覆盖口部混合形状；在非说话状态下，该值控制情绪姿态对口部区域的影响强度。

## 别名解析的工作方式

每次后端发出情绪时，控制器都会调用 `IEmotionTaxonomy.TryResolve(serverLabel, out EmotionDescriptor descriptor)`。解析器会先检查标准标签，然后再遍历所有条目的完整别名列表。

* 如果标签成功解析，则相应的标准标签和描述符会在整个管线中使用。
* 如果标签未 **上的初始动态信息文本** 解析，情绪事件将被静默忽略，并向 Unity 控制台写入一条警告。这可防止未知标签干扰正在运行的状态。

**示例：** 后端发送 `“happy”` → `TryResolve` 找到 `“happy”` 在 `喜悦` 条目的别名列表中 → 累加器会将目标分数设置为 `“joy”`.

{% hint style="info" %}
如果你看到 `[Taxonomy] 未找到标签` 控制台中的警告，则表示后端发送了一个既不在标准列表中也不在任何别名中的标签。请在自定义分类法资源中，将该新标签作为相应条目的别名添加进去，或者为其创建一个新条目。
{% endhint %}

## 创建自定义分类法资源

在项目窗口中，右键单击你的 `Assets/` 文件夹，并选择：

**Create → Convai → Embodiment → Emotion Taxonomy**

一个名为 `EmotionTaxonomy` 的新资源会出现。选择它即可在检查器中编辑条目列表。

### EmotionTaxonomyEntry 字段

<table><thead><tr><th width="228.49993896484375">字段</th><th width="163">类型</th><th>描述</th></tr></thead><tbody><tr><td><code>label</code></td><td><code>字符串</code></td><td>整个管线中使用的标准小写标签（例如 <code>“joy”</code>）。在分类法中必须唯一。</td></tr><tr><td><code>aliases</code></td><td><code>List&#x3C;string></code></td><td>所有应解析到此条目的服务器端字符串（例如 <code>“happy”</code>, <code>"happiness"</code>).</td></tr><tr><td><code>补充</code></td><td><code>List&#x3C;string></code></td><td>当这些情绪激活时，会抑制中性合成的情绪标准标签。如果某个补充情绪当前分数高于零，则该周期内的中性交替不会向中性衰减。</td></tr><tr><td><code>defaultMouthInfluence</code></td><td><code>float</code> （0–1）</td><td>用于 LipSync 混合的口部影响提示。参考上方内置表中的值。</td></tr><tr><td><code>isNeutral</code></td><td><code>bool</code></td><td>将此条目标记为分类法的中性基线——即累加器的衰减目标，以及中性交替期间的目标状态。</td></tr></tbody></table>

{% hint style="warning" %}
**必须且仅有一个条目具有 `isNeutral = true`.** 累加器使用中性条目作为其衰减锚点。如果没有任何条目标记为中性，或者有多个条目标记为中性，系统的行为将未定义，且表情在运行时不会正确稳定下来。
{% endhint %}

### 为配置文件分配自定义分类法

1. 打开你的 `ConvaiEmotionProfile` 资源。
2. 将自定义的 `EmotionTaxonomyAsset` 到 **分类法** 字段。
3. 控制器会在下次应用该配置文件时获取新分类法——在 Play 模式中会立即生效，而在 Edit 模式中也会立即生效，因为 `ConvaiEmotionController` 为 `[ExecuteAlways]`.

## 何时创建自定义分类法

内置的 Plutchik 集合覆盖了 Convai 后端当前发送的所有情绪。当以下情况时，才值得创建自定义分类法：

* 你的 Convai 配置使用了与内置别名不同的自定义情绪标签。
* 你想使用不同的概念模型——例如 Ekman 的六种基本情绪——并将多个服务器别名映射到更少的标准桶中。
* 你想调整 `defaultMouthInfluence` 值，以更好地适配你的角色绑定。
* 你需要定义 `补充` 关系，以防止中性交替在你的应用流程中打断某些情绪组合。

## 结论

有了分类法，管线就具备了从服务器标签到驱动输出绑定的标准标识符的完整、权威映射。继续 [Scripting API](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/emotion/scripting-api-reference.md) 以了解如何在运行时用 C# 读取和控制情绪状态，或者查看 [故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/emotion/troubleshooting-and-diagnostics.md) 如果控制台中出现了分类法警告消息。


---

# 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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/emotion/emotion-taxonomy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.