> 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.md). # 情绪 ## 赋予 Convai 角色具备情绪响应的面孔 Emotion 系统会将 Convai AI 的内部情绪状态转换为实时面部动画——驱动 blendshapes、Animator 参数，或两者同时驱动。每当后端判断角色感到喜悦、愤怒、惊讶或任何其他状态时，Emotion 系统都会接收该信号，将其平滑为自然的变化曲线，并实时把结果写入角色的面部。最终效果是角色看起来具有情绪存在感，而不是面无表情。 ## 工作原理 ```mermaid flowchart TD A([Convai 后端]) -->|RTVI 机器人情绪消息\n情绪标签 + 1–3 级别| B[RTVIBotEmotionMessage] B --> C[CharacterEmotionChanged\n领域事件] C --> D[ConvaiEmotionController] D --> E{分类体系\n解析} E -->|别名 → 规范标签| F[EmotionScoreAccumulator\n平滑 · 微爆发] F --> G[NeutralAlternator\n定期淡出至中性] G --> H{输出绑定} H --> I[BlendshapeEmotionBinding\n面部 blendshapes] H --> J[AnimatorParameterEmotionBinding\nAnimator 浮点参数] I & J --> K([EmotionReading\n由你的脚本读取]) ``` 后端发送一个简短的情绪标签（例如 `"快乐"`）以及一个 1–3 级别的强度。 **分类法** 将该标签解析为其规范形式（`"joy"`），并将强度规范化为 0–1 分数，然后交给 **分数累积器**，它会应用指数平滑和可选的微表情爆发。 **中性切换器** 随后会定期将表情逐渐混回中性，以防止面部表情僵住。最后，平滑后的分数会通过可配置的 **输出绑定**. ## 先决条件 {% hint style="info" %} 在将 Emotion 系统添加到角色之前，请确保： * 你的角色网格具有面部 blendshapes，或者你的 Animator Controller 有你希望由情绪驱动的浮点参数。该管线即使没有这些也能运行，但在至少配置一个输出绑定之前，不会产生任何视觉输出。 {% endhint %} ## 各部分放在哪里 | 组件 | 放置位置 | 说明 | | --------------------------- | ------------------------------------------- | --------------------------------------------------- | | `ConvaiEmotionController` | 在 **NPC 的根 GameObject**，与 Embodiment 组件一起 | 每个角色一个 | | `ConvaiEmotionProfile` | 在你的任意 `Assets/` 文件夹中，作为 ScriptableObject 资源 | 如有需要，可在多个 NPC 预制体之间共享 | | `EmotionTaxonomyAsset` | 在你的任意 `Assets/` 文件夹 | 可选——留空则使用内置的 Plutchik 集合 | | `ConvaiCharacterEventRelay` | 场景中的任意 GameObject 上 | 自动解析 `ConvaiCharacter` 到同一个 GameObject；如有需要，可拖入其他角色 | ## 关键概念

概念	是什么
`ConvaiEmotionController`	拥有单个 NPC 整个管线的 MonoBehaviour。每个角色添加一个。
`ConvaiEmotionProfile`	一个 ScriptableObject 资源，包含所有可调参数：平滑、微爆发、中性切换以及输出槽定义。
`EmotionTaxonomyAsset`	一个定义情绪词汇表的 ScriptableObject——规范标签、服务器别名和嘴部影响提示。内置默认值为 Plutchik 的八种基本情绪加中性。
`输出绑定`	`BlendshapeEmotionBinding` 是位于 `AnimatorParameterEmotionBinding` 将每个规范情绪标签映射到网格 blendshape 名称或 Animator 浮点参数。
`EmotionReading`	当前情绪状态的不可变快照：主导标签、主导分数、所有分数，以及用于 LipSync 的嘴部影响提示。可通过以下方式在每一帧获取： `ConvaiEmotionController.Current`.
`微爆发`	当新的情绪到来时应用的短暂过冲，让表情先有一个有力的起势，再稳定到持续水平。
`中性切换`	一个定时器，会周期性地将当前表情淡出到中性再回到原表情，防止角色在长时间发言时面部固定在单一姿态。
`ConvaiCharacterEventRelay`	一个对 Inspector 友好的组件，可将情绪变化回调暴露为 Unity Events——无需编写代码。

## 本节内容


快速入门	挂载 Emotion Controller，分配附带的配置文件，让你的 NPC 对对话产生情绪反应——无需自定义资源。
情绪配置文件	在一个可移植资源中配置平滑速度、微表情爆发、中性切换和输出绑定。
输出绑定	将平滑后的情绪分数映射到面部 blendshapes 和 Animator 浮点参数，并支持每个槽位的权重与 LipSync 控制。
情绪分类体系	了解内置的 Plutchik 词汇、服务器别名如何解析，以及如何编写自定义分类体系。
脚本 API	读取实时情绪状态、注入覆盖、锁定表情，并响应情绪事件——从 Inspector 中转到类型化的 C# 订阅。
使用示例	完整场景涵盖危险触发、锁定问候、困扰分支、分析日志记录以及 Editor 调试。
故障排除与诊断	针对最常见问题的逐步修复方法——从表情不动到 LipSync 冲突，再到正式构建中的坑点。

## 结论 Emotion 系统为 Convai 角色带来可信的情绪存在感——由服务器驱动、经过平滑处理，并且在常见情况下无需编写代码即可完全配置。先从快速开始入手，让角色实时产生反应，然后使用更深入的配置页面，为你的特定骨骼与场景调优行为。 --- # 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.md?ask= ``` 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.