> 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/facial-composition.md).

# 面部组合

面部组合配置文件参考，包括按区域的 blend 配置、blend 模式和层级优先级。

`ConvaiFacialCompositionProfile` 是一个 `ScriptableObject` 资源，用于配置角色处于待机和说话状态时，表情、唇形同步和预留的自定义通道分别对面部的控制程度。Convai 会将每个面部混合形状归入六个区域之一，并根据此配置文件合成各区域的最终权重，然后将其写入角色的面部网格。

### `ConvaiFacialCompositionProfile`

`ScriptableObject` — `Convai.Runtime.Animation`

创建菜单： `Assets > Create > Convai > Embodiment > Facial Composition Profile`

#### 返回的结果

| 属性                                                                                  | 类型                  | 说明                                                        |
| ----------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------- |
| `SpeechRampUpDuration`                                                              | `float`             | 语音开始时，将语音混合因子从 `0` 渐变至 `1` 所需的秒数。默认值为 `0.15`。最小值为 `0.01`. |
| `SpeechRampDownDuration`                                                            | `float`             | 语音结束时，将语音混合因子从 `1` 渐变至 `0` 所需的秒数。默认值为 `0.4`。最小值为 `0.01`.  |
| `EnableGlobalNormalization`                                                         | `bool`              | 启用后，在所有层完成贡献后，超过 100 的合成值会被限制为 100。默认值为 `false`.          |
| `MouthConfig`, `BrowConfig`, `EyeConfig`, `CheekConfig`, `JawConfig`, `OtherConfig` | `RegionBlendConfig` | 以只读方式访问各区域的混合配置。                                          |

#### 方法

| 方法                   | 签名                                                                 | 说明                                                                            |
| -------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `GetRegionConfig`    | `RegionBlendConfig GetRegionConfig(FacialBlendshapeRegion region)` | 返回指定面部区域的混合配置。                                                                |
| `ClassifyBlendshape` | `FacialBlendshapeRegion ClassifyBlendshape(string blendshapeName)` | 使用配置文件中设定的名称模式，将混合形状名称归类到相应区域。匹配时不区分大小写，也不考虑分隔符，因此 `Jaw_Open` 也能匹配 `jawOpen`. |
| `CreateDefault`      | `static ConvaiFacialCompositionProfile CreateDefault()`            | 使用随附的默认值创建实例。如果未指定配置文件，内部会使用此方法；返回实例的所有权归调用方，调用方必须销毁该实例。                      |

### 面部区域

每个混合形状都恰好归入六个区域之一。分类时依次检查 Mouth、Jaw、Brow、Eye 和 Cheek；如果混合形状与这些模式均不匹配，则归入 Other。

| 区域      | 默认名称模式                                                                                   | 典型内容                      |
| ------- | ---------------------------------------------------------------------------------------- | ------------------------- |
| `Mouth` | `Mouth`, `Lip`, `Tongue`, `Jaw_Open`                                                     | 嘴唇、舌头和嘴角的形状，主要由说话时的口型同步驱动 |
| `Jaw`   | `Jaw_Forward`, `Jaw_Backward`, `Jaw_L`, `Jaw_R`, `Jaw_Up`, `Jaw_Down`                    | 下颌的方向性形状，与 Mouth 分开       |
| `Brow`  | `Brow`, `Forehead`                                                                       | 眉毛和额头的形状                  |
| `Eye`   | `Eye_Blink`, `Eye_Squint`, `Eye_Wide`, `Eye_Look`, `Eye_L_Look`, `Eye_R_Look`, `Eyelash` | 眨眼、眯眼、睁大眼睛、视线和睫毛的形状       |
| `Cheek` | `Cheek`, `Nose`, `Sneer`                                                                 | 鼓腮、眯起脸颊和鼻子皱起的形状           |
| `Other` | 无（回退项）                                                                                   | 与任何已配置模式都不匹配的 blendshape  |

每个模式列表都是配置文件上的一个分号分隔字符串字段（`Mouth Patterns`, `Jaw Patterns`, `Brow Patterns`, `Eye Patterns`, `Cheek Patterns`），可按项目编辑。网格发现使用一组独立的名称模式（`Head Mesh Patterns`, `Secondary Mesh Patterns`, `Tertiary Mesh Patterns`），以确定优先从哪个 `SkinnedMeshRenderer` 解析 blendshape。

### 按区域组合

`RegionBlendConfig` — `Convai.Runtime.Animation`，可序列化结构体

每个区域都有自己的 `RegionBlendConfig` ，包含六个权重（`0`–`1`）和一个 `FacialBlendMode`。权重使用平滑后的语音混合因子，在 `Idle*` 和 `Speaking*` 值之间插值。

| 字段                      | 类型                | 说明                                     |
| ----------------------- | ----------------- | -------------------------------------- |
| `IdleEmotionWeight`     | `float`           | 未说话时情绪层的权重                             |
| `IdleLipSyncWeight`     | `float`           | 未说话时口型同步层的权重                           |
| `IdleCustomWeight`      | `float`           | 未说话时自定义层的权重                            |
| `SpeakingEmotionWeight` | `float`           | 说话时情绪层的权重                              |
| `SpeakingLipSyncWeight` | `float`           | 说话时口型同步层的权重                            |
| `SpeakingCustomWeight`  | `float`           | 说话时自定义层的权重                             |
| `Mode`                  | `FacialBlendMode` | 此区域内三个图层的组合方式。默认值为 `WeightedAdditive`. |
| `EnableNormalization`   | `bool`            | 启用后，此区域的合成结果将限制在 100 以内，超出的部分会按比例缩减。   |

#### 默认区域权重

| 区域 | 静止时的情绪 | 静止时的口型同步 | 说话时的情绪 | 说话时的口型同步 |
| -- | ------ | -------- | ------ | -------- |
| 嘴部 | `1.0`  | `0.0`    | `0.2`  | `1.0`    |
| 眉毛 | `1.0`  | `0.0`    | `0.85` | `0.15`   |
| 眼睛 | `0.8`  | `0.0`    | `0.7`  | `0.1`    |
| 脸颊 | `1.0`  | `0.0`    | `0.7`  | `0.25`   |
| 下颌 | `0.5`  | `0.0`    | `0.1`  | `1.0`    |
| 其他 | `1.0`  | `0.0`    | `0.8`  | `0.3`    |

`IdleCustomWeight` 和 `SpeakingCustomWeight` 在每个区域中默认设为 `0.0` 。 `Mode` 默认值为 `WeightedAdditive` 。

### 混合模式

`FacialBlendMode` — `Convai.Runtime.Animation`

| 值                  | 整数  | 说明                                                        |
| ------------------ | --- | --------------------------------------------------------- |
| `WeightedAdditive` | `0` | 每个图层的值都会乘以其插值权重，然后求和，最后限制在 0–100 之间。此模式可以保留多个来源的细微贡献。默认值。 |
| `Max`              | `1` | 每个图层的值都会乘以其插值权重；取结果中的最大值。                                 |
| `Override`         | `2` | 优先级最高的非零图层值会按其权重缩放，并取得完全控制权。优先级顺序：LipSync、Emotion、Custom。 |

### 分配覆盖配置文件

如果未分配配置文件，Convai 自动添加的角色上下文会使用包含上述值的内置默认配置文件。若要重新平衡合成效果，或对名称特殊的混合形状进行分类，请将 `ConvaiFacialCompositionProfile` 资源分配给该上下文 Inspector 中 **Face Blending Override** 字段，该字段位于 **Advanced** 部分。

{% hint style="info" %}
如果明确将配置文件指定为 `null`，合成行为会退化为对所有活动图层进行最大值混合，并且只记录一次警告。只有在主动清除配置文件时才会发生这种情况；否则 Convai 会提供内置默认配置文件。
{% endhint %}

### 相关参考

{% content-ref url="/pages/dddb9a87015e6befbe3c15caf6aa6b2df224fa33" %}
[角色骨架设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/character-rig-setup.md)
{% endcontent-ref %}

{% content-ref url="/pages/98cb5fe5ecdb3bff07eface0a87fc2b885cc0704" %}
[具身化脚本参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/scripting-reference.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/facial-composition.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
