> 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`

创建菜单： `资源 > 创建 > Convai > 具身 > 面部组合配置文件`

#### 属性

| 属性                                             | 类型       | 描述                                                 |
| ---------------------------------------------- | -------- | -------------------------------------------------- |
| `SpeechRampUpDuration`                         | `float`  | 用于将语音混合因子从 `0` 到 `1` 在语音开始时。默认值 `0.15`。最小值 `0.01`. |
| `SpeechRampDownDuration`                       | `float`  | 用于将语音混合因子从 `1` 到 `0` 在语音结束时。默认值 `0.4`。最小值 `0.01`.  |
| `EnableGlobalNormalization`                    | `bool`   | 启用后，在所有层都参与后，超过 100 的组合值会被截断。默认值 `false`.          |
| `嘴部配置`, `眉部配置`, `眼部配置`, `脸颊配置`, `下颌配置`, `其他配置` | `区域混合配置` | 可只读访问每个区域的混合配置。                                    |

#### 方法

| 方法                   | 签名                                                                 | 描述                                                                              |
| -------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `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。

| 区域   | 默认名称模式                                                                              | 典型内容                     |
| ---- | ----------------------------------------------------------------------------------- | ------------------------ |
| `嘴部` | `嘴部`, `唇`, `舌头`, `Jaw_Open`                                                         | 唇部、舌头和嘴角形状，主要在说话时由口型同步驱动 |
| `下颌` | `Jaw_Forward`, `Jaw_Backward`, `Jaw_L`, `Jaw_R`, `Jaw_Up`, `Jaw_Down`               | 方向性下颌形状，独立于 Mouth        |
| `眉部` | `眉部`, `额头`                                                                          | 眉部和额头形状                  |
| `眼部` | `Eye_Blink`, `Eye_Squint`, `Eye_Wide`, `Eye_Look`, `Eye_L_Look`, `Eye_R_Look`, `睫毛` | 眨眼、眯眼、睁眼、注视和睫毛形状         |
| `脸颊` | `脸颊`, `鼻子`, `皱鼻`                                                                    | 鼓腮、眯脸颊和皱鼻形状              |
| `其他` | 无（回退）                                                                               | 任何与已配置模式都不匹配的 blendshape |

每个模式列表都是配置文件中的一个以分号分隔的字符串字段（`嘴部模式`, `下颌模式`, `眉部模式`, `眼部模式`, `脸颊模式`），可按项目编辑。网格发现使用另一组名称模式（`头部网格模式`, `次级网格模式`, `三级网格模式`）用于优先决定哪个 `SkinnedMeshRenderer` blendshapes 会先从中解析。

### 按区域组合

`区域混合配置` — `Convai.Runtime.Animation`，可序列化结构体

每个区域都有自己的 `区域混合配置` ，包含六个权重（`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`. |
| `启用归一化`                 | `bool`            | 启用后，该区域的组合结果会被截断到 100，超出部分按比例减少。   |

#### 默认区域权重

| 区域 | 待机 Emotion | 待机 LipSync | 说话 Emotion | 说话 LipSync |
| -- | ---------- | ---------- | ---------- | ---------- |
| 嘴部 | `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` 适用于每个区域。 `模式` 默认为 `WeightedAdditive` 适用于每个区域。

### 混合模式

`FacialBlendMode` — `Convai.Runtime.Animation`

| 值                  | Integer | 描述                                                              |
| ------------------ | ------- | --------------------------------------------------------------- |
| `WeightedAdditive` | `0`     | 每一层的值都会乘以其插值权重后求和，然后截断到 0–100。可保留来自多个来源的细微贡献。默认值。               |
| `最大值`              | `1`     | 每一层的值都会乘以其插值权重；结果最大的项获胜。                                        |
| `覆盖`               | `2`     | 经过其权重缩放后，优先级最高的非零层值将完全接管。优先级顺序：LipSync，然后是 Emotion，再然后是 Custom。 |

### 分配覆盖配置文件

Convai 自动添加的角色上下文在未分配配置文件时会解析一个内置默认配置文件，使用上述值。若要重新平衡组合或对名称不寻常的 blendshape 进行分类，请分配一个 `ConvaiFacialCompositionProfile` 资源分配给 **面部混合覆盖** 字段，在该上下文的 **高级** 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.