> 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/quick-start.md).

# 快速开始

## 让你的第一个情绪响应 NPC 运行起来

本指南将带你走完搭建可工作的情绪系统的最快路径。你将挂接控制器，分配内置示例配置文件，并在播放模式下看到角色的脸部对实时 AI 情绪信号作出反应——无需提前进行任何配置。

{% hint style="info" %}
**前提条件**

* 一个带有 `ConvaiCharacter` 组件已设置并正常工作（角色应能对语音作出响应）。
* 你的 Convai API 密钥已在 **工具 → Convai → 配置**.
  {% endhint %}

## 逐步设置

{% stepper %}
{% step %}
**添加情绪控制器**

在 Hierarchy 中选中你的 NPC 根 GameObject。在 Inspector 中，单击 **添加组件** 并搜索 **Emotion Controller**，或者导航到 **Convai → Embodiment → Emotion Controller**.

该组件会显示一个 **Profile** 字段，目前为空。

<figure><img src="/files/e834c78c4a301dd5d234620242ff7d57656832cc" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**找到内置示例配置文件**

在 Project 窗口中，导航到：

{% code overflow="wrap" %}

```
Packages / Convai SDK for Unity / SamplesShared / Resources / Embodiment / Modules / Emotion
```

{% endcode %}

你会找到两个资源：

| 资源                                    | 用途                                         |
| ------------------------------------- | ------------------------------------------ |
| `ConvaiSamplesShared_EmotionProfile`  | 为 Reallusion 角色预先配置好的表情槽位，平滑、微爆发和中性轮换都已调好。 |
| `ConvaiSamplesShared_EmotionTaxonomy` | 默认情绪词汇表（上面的配置文件已引用）。                       |

{% hint style="info" %}
内置配置文件已针对以下对象配置： **Reallusion** 角色开箱即用。如果你的角色使用不同的骨骼绑定，流程仍然可以运行——但你需要更新配置文件槽位中的 blendshape 名称，使其与角色匹配。有关如何操作，请参见 Emotion Profile。
{% endhint %}
{% endstep %}

{% step %}
**分配配置文件**

拖动 `ConvaiSamplesShared_EmotionProfile` 从 Project 窗口到 **Profile** 上的 `ConvaiEmotionController` 组件。

<figure><img src="/files/ef51f792df1ee5e09263f05f80a049a735b27ad2" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
该内置资源是 **只读的** ——它位于包内。若要调整任何设置，请先复制它（**Ctrl+D** 在 Windows 上 / **Cmd+D** 在 macOS 上），将副本移动到你自己的 `Assets/` 文件夹中，然后改为分配该副本。
{% endhint %}
{% endstep %}

{% step %}
**进入播放模式并说话**

按下 **Play**。使用你已配置的麦克风与角色对话。当 AI 进行回应时，观察 `ConvaiEmotionController` 在 Inspector 中—— **Current** 读数会实时更新。

{% hint style="success" %}
**预期结果：** 随着对话展开，NPC 的面部表情会变化——在轻松友好的交流中会出现细微微笑，在严肃话题中则会呈现更严肃的表情。如果你使用的是带默认骨骼绑定的 Reallusion 角色，你会立即看到这些形状在角色脸上生效。
{% endhint %}
{% endstep %}
{% endstepper %}

## 刚刚发生了什么

当你与角色对话时，以下内容会自动发生：

1. Convai 后端处理了你的语音，并为角色决定了一个情绪状态。
2. 它发送了一条包含如下标签的简短消息： `“happy”` 以及 1 到 3 的强度值。
3. `ConvaiEmotionController` 接收到了这个信息，并通过 `“happy”` 将其解析为规范标签 `“joy”` ，并通过分类体系对强度分数进行平滑处理。
4. 配置文件中预先设置的 blendshape 槽位会在每一帧将平滑后的分数写入角色的面部 blendshape。
5. `EmotionReading.Current` 控制器上的值始终反映实时状态。

这一切都会在会话生命周期内自动运行。

## 使用非 Reallusion 角色

如果你的角色有不同的 blendshape 名称，请打开复制后的配置文件并更新 **Blendshape Names** 字段中的每个槽位，使其与角色的形状匹配。槽位结构和所有其他设置仍然有效——只需更改形状名称。

有关槽位如何工作以及如何为任何骨骼绑定进行配置的演示，请参见 Emotion Profile 和 Output Bindings。

{% hint style="info" %}
借助 AI 编程助手，可以快速为新角色映射 blendshape。分享角色的 blendshape 列表，并让它生成槽位配置——槽位格式很直接，并且可直接对应 Inspector 字段。
{% endhint %}

## 下一步

* **将配置文件适配到你自己的骨骼绑定** → [Emotion Profile](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/emotion/emotion-profile.md)
* **了解槽位映射的工作方式** → [Output Bindings](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/emotion/output-bindings.md)
* **自定义情绪词汇** → [Emotion Taxonomy](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/emotion/emotion-taxonomy.md)
* **从脚本读取情绪状态或触发覆盖** → [Scripting API](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/emotion/scripting-api-reference.md)
* **有什么地方不工作吗？** → [故障排查与诊断](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/emotion/troubleshooting-and-diagnostics.md)

## 结论

现在，你的角色上已经运行着完整的情绪管线——由服务器驱动、经过平滑处理，并对实时 AI 决策作出反应。如果你的角色基于 Reallusion，表情已经启用；如果不是，请更新配置文件中的 blendshape 名称，其余配置将保持不变。


---

# 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/quick-start.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.