> 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` 用于配置角色在待机和说话时，Emotion、LipSync 以及一个保留的 Custom 通道各自控制角色面部多少部分的资源。Convai 会将每个面部 blendshape 归类到六个区域之一，并在写入角色面部网格之前，根据此配置文件组合每个区域的最终权重。

### `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 的组合值会被钳制。默认 `false`.                   |
| `MouthConfig`, `BrowConfig`, `EyeConfig`, `CheekConfig`, `JawConfig`, `OtherConfig` | `RegionBlendConfig` | 可只读访问每个区域的混合配置。                                            |

#### 方法

| 方法                   | 签名                                                                 | 说明                                                                                |
| -------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `GetRegionConfig`    | `RegionBlendConfig GetRegionConfig(FacialBlendshapeRegion region)` | 返回某个面部区域的混合配置。                                                                    |
| `ClassifyBlendshape` | `FacialBlendshapeRegion ClassifyBlendshape(string blendshapeName)` | 使用配置文件中设置的名称模式将一个 blendshape 名称归类到某个区域。匹配时忽略大小写和分隔符，因此 `Jaw_Open` 也会匹配 `jawOpen`. |
| `CreateDefault`      | `static ConvaiFacialCompositionProfile CreateDefault()`            | 使用随附的默认值创建一个实例。在未分配配置文件时会在内部使用；调用方拥有该实例并且必须销毁返回的实例。                               |

### 面部区域

每个 blendshape 都会被精确归类到六个区域之一。分类顺序依次检查 Mouth、Jaw、Brow、Eye、Cheek；若 blendshape 与这些模式都不匹配，则归入 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`                                                                 | 脸颊鼓起、脸颊眯起和鼻翼皱起形状         |
| `其他`    | 无（回退）                                                                                    | 任何与已配置模式都不匹配的 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`           | 未说话时 Emotion 层的权重                  |
| `IdleLipSyncWeight`     | `float`           | 未说话时 LipSync 层的权重                  |
| `IdleCustomWeight`      | `float`           | 未说话时 Custom 层的权重                   |
| `SpeakingEmotionWeight` | `float`           | 说话时 Emotion 层的权重                   |
| `SpeakingLipSyncWeight` | `float`           | 说话时 LipSync 层的权重                   |
| `SpeakingCustomWeight`  | `float`           | 说话时 Custom 层的权重                    |
| `模式`                    | `FacialBlendMode` | 此区域内三层如何组合。默认 `WeightedAdditive`.  |
| `EnableNormalization`   | `bool`            | 启用后，此区域的组合结果会被钳制到 100，并按比例减少超出的部分。 |

#### 默认区域权重

| 区域    | 待机 Emotion | 待机 LipSync | 说话 Emotion | 说话 LipSync |
| ----- | ---------- | ---------- | ---------- | ---------- |
| Mouth | `1.0`      | `0.0`      | `0.2`      | `1.0`      |
| Brow  | `1.0`      | `0.0`      | `0.85`     | `0.15`     |
| Eye   | `0.8`      | `0.0`      | `0.7`      | `0.1`      |
| Cheek | `1.0`      | `0.0`      | `0.7`      | `0.25`     |
| Jaw   | `0.5`      | `0.0`      | `0.1`      | `1.0`      |
| 其他    | `1.0`      | `0.0`      | `0.8`      | `0.3`      |

`IdleCustomWeight` 和 `SpeakingCustomWeight` 默认都为 `0.0` ，适用于每个区域。 `模式` 默认值为 `WeightedAdditive` ，适用于每个区域。

### 混合模式

`FacialBlendMode` — `Convai.Runtime.Animation`

| 值                  | 整数  | 说明                                                           |
| ------------------ | --- | ------------------------------------------------------------ |
| `WeightedAdditive` | `0` | 每个层的值都会乘以其插值后的权重并求和，然后钳制到 0–100。保留来自多个来源的细微贡献。默认。            |
| `Max`              | `1` | 每个层的值都会乘以其插值后的权重；结果最大的那个获胜。                                  |
| `覆盖`               | `2` | 按权重缩放后，优先级最高的非零层值将完全接管。优先级顺序：LipSync，然后是 Emotion，然后是 Custom。 |

### 分配一个覆盖配置文件

Convai 自动添加的角色上下文在未分配配置文件时会使用上述值解析出一个内置默认配置文件。若要重新平衡组合或按异常名称分类 blendshape，请分配一个 `ConvaiFacialCompositionProfile` 资源到 **Face Blending Override** 字段，位于 **高级** 该上下文 Inspector 的部分中。

{% hint style="info" %}
如果显式将配置文件设置为 `null`，组合行为会退化为在所有活动层上使用最大混合回退，并记录一次性警告。只有在配置文件被故意清除时才会发生这种情况——否则 Convai 会提供一个内置默认值。
{% endhint %}

### 相关参考

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

{% content-ref url="/pages/98cb5fe5ecdb3bff07eface0a87fc2b885cc0704" %}
[具身化脚本参考](/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.