> 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/output-bindings.md).

# Output Bindings

## 从情绪分数驱动面部和 Animator

输出绑定是 Emotion 系统平滑后的分数表与角色视觉表现之间的桥梁。SDK 提供两种绑定类型—— `BlendshapeEmotionBinding` 用于直接网格控制，以及 `AnimatorParameterEmotionBinding` 用于基于 Mecanim 的骨骼绑定——两者可同时启用。每个绑定都是一个 `EmotionSlotBinding` 条目列表，每个输出通道中的每种情绪各一项，全部在 `ConvaiEmotionProfile` 资源。

## EmotionSlotBinding 字段

两种绑定类型中的每个槽位都共享同一组字段：

<table><thead><tr><th width="208">字段</th><th width="86.49993896484375">类型</th><th width="148.5">范围 / 格式</th><th width="96.5">默认值</th><th>说明</th></tr></thead><tbody><tr><td><code>emotionLabel</code></td><td><code>string</code></td><td>规范分类标签</td><td>—</td><td>该槽位所驱动的情绪。必须与当前分类体系中定义的标签匹配（例如 <code>"joy"</code>, <code>"anger"</code>, <code>"neutral"</code>).</td></tr><tr><td><code>blendshapeNames</code></td><td><code>string</code></td><td>以逗号或换行分隔</td><td>—</td><td>角色的一个或多个 blendshape 名称 <code>SkinnedMeshRenderer</code>。列表中的所有形状会同时接收相同的计算权重。用于 <code>BlendshapeEmotionBinding</code> 仅此而已。</td></tr><tr><td><code>animatorParameterName</code></td><td><code>string</code></td><td>Animator 浮点参数名</td><td>—</td><td>一个 <code>float</code> Animator Controller 中的参数名称。留空可跳过该槽位的 Animator 输出。用于 <code>AnimatorParameterEmotionBinding</code> 仅此而已。</td></tr><tr><td><code>weightMultiplier</code></td><td><code>float</code></td><td>0 – 2</td><td><strong>1</strong></td><td>在写入输出之前应用于分数的每槽缩放因子。大于 1 会增强情绪的视觉影响；小于 1 会减弱它。</td></tr><tr><td><code>fullBlendshapeWeight</code></td><td><code>float</code></td><td>0 – 100</td><td><strong>100</strong></td><td>情绪分数达到 1.0 时写入的 blendshape 值。将 SDK 归一化的 0–1 范围映射到 Unity 的 0–100 网格单位。</td></tr><tr><td><code>isMouthShape</code></td><td><code>bool</code></td><td>—</td><td><code>false</code></td><td>为 true 时，该 blendshape 会被视为口部区域形状，并通过一个单独的合成层路由，供 LipSync 在语音期间调制。</td></tr></tbody></table>

## Blendshape Binding

`BlendshapeEmotionBinding` 直接写入 `SkinnedMeshRenderer`的 blendshapes，每帧都会写入。它是最直接的路径，无需 Animator Controller。

### Blendshape 名称格式

该 `blendshapeNames` 字段接受以逗号分隔或换行分隔的列表。列表中的所有名称会同时获得相同权重，这在单个情绪姿态需要多个 blendshape 时很有用——例如，一个微笑同时激活嘴角上扬和脸颊鼓起：

```
Facial_LipCornerPull_L, Facial_LipCornerPull_R, Facial_CheekPuff
```

要为角色找到正确的名称：在 Hierarchy 中选择角色的网格，查看 Inspector 里的 **Skinned Mesh Renderer** 组件，并展开底部的 **BlendShapes** 部分。那里列出的名称就是你要在槽位中输入的名称。

### 权重计算

每一帧，最终的 blendshape 值按以下方式计算：

`finalWeight = score × weightMultiplier × fullBlendshapeWeight`

其中 `score` 是来自累加器的平滑、经 burst 调整后的值（0–1）。在默认设置下，完全激活的情绪会将 blendshape 驱动到 100（Unity 网格单位）。

### 该 `isMouthShape` 标记

{% hint style="warning" %}
仅对 `isMouthShape = true` 会变形嘴唇、下颌或口部周围区域的 blendshape 设置。Emotion 系统会将带有口部标记的形状路由到面部 blendshape 合成器中，在语音播放期间 LipSync 系统可以在其上进行混合。将非口部形状（眉毛上扬、眯眼）标记为口部形状，会导致这些形状在语音播放时被错误地抑制或调制。
{% endhint %}

## Animator 参数绑定

`AnimatorParameterEmotionBinding` 将平滑后的情绪分数写入为 `float` 参数到一个 `Animator` 组件，位于同一个 GameObject 上。当角色使用 Mecanim 绑定，且由情绪驱动的姿势以动画状态或 blend tree 的形式制作时，这是正确的选择。

### 要求

* 每个槽位中的参数名称必须与一个 **Float** Animator Controller 中定义的参数完全一致（区分大小写）。
* Animator 组件必须与 `ConvaiEmotionController`位于同一个 GameObject 上，或者可通过骨骼绑定访问到。

### 推荐命名约定

使用一致的前缀可以让参数在 Animator 窗口中更容易识别，并避免与其他系统冲突：

```
Emotion_Joy
Emotion_Anger
Emotion_Sadness
Emotion_Fear
Emotion_Surprise
```

{% hint style="info" %}
两者 `BlendshapeEmotionBinding` 是位于 `AnimatorParameterEmotionBinding` 可以同时填充。系统会在每帧向两个通道写入，这对于将直接 blendshape 控制与 Animator 驱动的次级运动（布料、头发、身体倾斜）结合起来的绑定很有用。
{% endhint %}

## 通过 RealisticEmotionSlots 提供的预置槽位

如果你的角色使用 Reallusion CC3、CC4 或兼容 ARKit 的绑定，SDK 包含一个工厂，可生成受 FACS 启发的槽位列表，覆盖全部八种非中性情绪。这些槽位使用多形状组合（Duchenne 微笑、斜向皱眉、眉毛上扬等），比单一 blendshape 映射产生更可信的表情。

该工厂通过代码调用——例如从 Editor 工具或设置脚本中：

```csharp
using Convai.Modules.Emotion.Authoring;
using Convai.Modules.Emotion.Outputs;
using Convai.Domain.Embodiment;

// 为 CC4 Extended 绑定构建一个槽位列表
IReadOnlyList<EmotionSlotBinding> slots = RealisticEmotionSlots.Build(RigConvention.ReallusionCC4Extended);

// 在制作时分配给配置文件的 blendshape 绑定
myProfile.BlendshapeBinding.SetSlots(slots);
```

支持的 `RigConvention` 值：

<table><thead><tr><th width="246.5">值</th><th>说明</th></tr></thead><tbody><tr><td><code>ReallusionCC4Extended</code></td><td>Reallusion Character Creator 4 Extended 面部配置文件</td></tr><tr><td><code>ReallusionCC3</code></td><td>Reallusion Character Creator 3 基础配置文件</td></tr><tr><td><code>ARKit</code></td><td>Apple 的 52-blendshape ARKit 规范</td></tr></tbody></table>

对于其他任何绑定，请以上述字段参考为指南手动创建槽位，并参考你的绑定的 blendshape 文档以获取正确的形状名称。

## 结论

配置好的绑定在 AI 的情绪信号与角色面部之间形成闭环。继续查看 Emotion Taxonomy，了解服务器情绪标签如何解析为槽位中使用的规范标签；如果你需要从代码中读取或覆盖当前情绪状态，则可直接跳到 Scripting API。


---

# 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/output-bindings.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.