> 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/plugins-and-integrations/convai-unity-sdk/embodiment/facial-composition.md).

# Facial composition

Reference for the facial composition profile, including per-region blend configuration, blend modes, and layer priority.

`ConvaiFacialCompositionProfile` is a `ScriptableObject` asset that configures how much of a character's face Emotion, LipSync, and a reserved Custom channel each control while idle and while speaking. Convai classifies every facial blendshape into one of six regions and composes each region's final weight from this profile before writing it to the character's face mesh.

### `ConvaiFacialCompositionProfile`

`ScriptableObject` — `Convai.Runtime.Animation`

Create menu: `Assets > Create > Convai > Embodiment > Facial Composition Profile`

#### Properties

| Property                                                                            | Type                | Description                                                                                                 |
| ----------------------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `SpeechRampUpDuration`                                                              | `float`             | Seconds to ramp the speech blend factor from `0` to `1` when speech starts. Default `0.15`. Minimum `0.01`. |
| `SpeechRampDownDuration`                                                            | `float`             | Seconds to ramp the speech blend factor from `1` to `0` when speech ends. Default `0.4`. Minimum `0.01`.    |
| `EnableGlobalNormalization`                                                         | `bool`              | When enabled, composed values exceeding 100 are clamped after all layers contribute. Default `false`.       |
| `MouthConfig`, `BrowConfig`, `EyeConfig`, `CheekConfig`, `JawConfig`, `OtherConfig` | `RegionBlendConfig` | Read-only access to each region's blend configuration.                                                      |

#### Methods

| Method               | Signature                                                          | Description                                                                                                                                                          |
| -------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GetRegionConfig`    | `RegionBlendConfig GetRegionConfig(FacialBlendshapeRegion region)` | Returns the blend configuration for a facial region.                                                                                                                 |
| `ClassifyBlendshape` | `FacialBlendshapeRegion ClassifyBlendshape(string blendshapeName)` | Classifies a blendshape name into a region using the profile's configured name patterns. Matching ignores case and separators, so `Jaw_Open` also matches `jawOpen`. |
| `CreateDefault`      | `static ConvaiFacialCompositionProfile CreateDefault()`            | Creates an instance with the shipped default values. Used internally when no profile is assigned; the caller owns and must destroy the returned instance.            |

### Facial regions

Every blendshape is classified into exactly one of six regions. Classification checks Mouth, then Jaw, then Brow, then Eye, then Cheek, in that order; a blendshape that matches none of those patterns falls into Other.

| Region  | Default name patterns                                                                    | Typical content                                                                  |
| ------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `Mouth` | `Mouth`, `Lip`, `Tongue`, `Jaw_Open`                                                     | Lip, tongue, and mouth-corner shapes, driven primarily by lip sync during speech |
| `Jaw`   | `Jaw_Forward`, `Jaw_Backward`, `Jaw_L`, `Jaw_R`, `Jaw_Up`, `Jaw_Down`                    | Directional jaw shapes, separate from Mouth                                      |
| `Brow`  | `Brow`, `Forehead`                                                                       | Brow and forehead shapes                                                         |
| `Eye`   | `Eye_Blink`, `Eye_Squint`, `Eye_Wide`, `Eye_Look`, `Eye_L_Look`, `Eye_R_Look`, `Eyelash` | Blink, squint, wide-eye, look, and eyelash shapes                                |
| `Cheek` | `Cheek`, `Nose`, `Sneer`                                                                 | Cheek puff, cheek squint, and nose sneer shapes                                  |
| `Other` | None (fallback)                                                                          | Any blendshape that matches no configured pattern                                |

Each pattern list is a semicolon-separated string field on the profile (`Mouth Patterns`, `Jaw Patterns`, `Brow Patterns`, `Eye Patterns`, `Cheek Patterns`), editable per project. Mesh discovery uses a separate set of name patterns (`Head Mesh Patterns`, `Secondary Mesh Patterns`, `Tertiary Mesh Patterns`) to prioritize which `SkinnedMeshRenderer` blendshapes resolve from first.

### Per-region composition

`RegionBlendConfig` — `Convai.Runtime.Animation`, serializable struct

Each region has its own `RegionBlendConfig` with six weights (`0`–`1`) and a `FacialBlendMode`. Weights interpolate between `Idle*` and `Speaking*` values using the smoothed speech blend factor.

| Field                   | Type              | Description                                                                                         |
| ----------------------- | ----------------- | --------------------------------------------------------------------------------------------------- |
| `IdleEmotionWeight`     | `float`           | Emotion layer weight while not speaking                                                             |
| `IdleLipSyncWeight`     | `float`           | LipSync layer weight while not speaking                                                             |
| `IdleCustomWeight`      | `float`           | Custom layer weight while not speaking                                                              |
| `SpeakingEmotionWeight` | `float`           | Emotion layer weight while speaking                                                                 |
| `SpeakingLipSyncWeight` | `float`           | LipSync layer weight while speaking                                                                 |
| `SpeakingCustomWeight`  | `float`           | Custom layer weight while speaking                                                                  |
| `Mode`                  | `FacialBlendMode` | How the three layers combine within this region. Default `WeightedAdditive`.                        |
| `EnableNormalization`   | `bool`            | When enabled, this region's composed result is clamped to 100 and excess is proportionally reduced. |

#### Default region weights

| Region | Idle Emotion | Idle LipSync | Speaking Emotion | Speaking 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`            |
| Other  | `1.0`        | `0.0`        | `0.8`            | `0.3`            |

`IdleCustomWeight` and `SpeakingCustomWeight` default to `0.0` for every region. `Mode` defaults to `WeightedAdditive` for every region.

### Blend modes

`FacialBlendMode` — `Convai.Runtime.Animation`

| Value              | Integer | Description                                                                                                                                                   |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WeightedAdditive` | `0`     | Each layer's value is multiplied by its interpolated weight and summed, then clamped to 0–100. Preserves subtle contributions from multiple sources. Default. |
| `Max`              | `1`     | Each layer's value is multiplied by its interpolated weight; the largest result wins.                                                                         |
| `Override`         | `2`     | The highest-priority non-zero layer value, scaled by its weight, takes full control. Priority order: LipSync, then Emotion, then Custom.                      |

### Assign an override profile

Convai's auto-added character context resolves a built-in default profile with the values above when no profile is assigned. To rebalance composition or classify blendshapes with unusual names, assign a `ConvaiFacialCompositionProfile` asset to the **Face Blending Override** field under the **Advanced** section of that context's Inspector.

{% hint style="info" %}
If a profile is explicitly assigned as `null`, the compositing behavior degrades to a max-blend fallback across all active layers and logs a one-time warning. This only happens when a profile has been deliberately cleared — Convai supplies a built-in default otherwise.
{% endhint %}

### Related reference

{% content-ref url="/pages/4vBSJ7Fjndr7KbLT4hAp" %}
[Character rig setup](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/character-rig-setup.md)
{% endcontent-ref %}

{% content-ref url="/pages/wXUY5JcFcFgANodvaQMM" %}
[Embodiment scripting reference](/api-docs/plugins-and-integrations/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/plugins-and-integrations/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.