> 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/utilities/dialogue-animation/animation-libraries-and-profiles.md).

# 动画库与配置文件

对话动画模块完全通过 ScriptableObject 资源进行配置。本页涵盖每种资源类型上的每个字段，包括来自 SDK 源码的默认值和有效范围。

***

### DialogueAnimationLibrary

一个 `DialogueAnimationLibrary` 包含两组 `DialogueClipEntry` 对象：空闲片段和讲话片段。该模块会在运行时根据对话状态和情绪从每个池中采样。

**通过以下方式创建：** 资源菜单 → **创建 → Convai → 化身 → 对话动画库**

| 字段         | 类型                    | 默认     | 描述                                    |
| ---------- | --------------------- | ------ | ------------------------------------- |
| `空闲条目`     | `DialogueClipEntry[]` | 空      | 角色未说话时循环播放的空闲片段池                      |
| `讲话条目`     | `DialogueClipEntry[]` | 空      | 角色说话时播放的讲话片段池                         |
| `默认交叉淡化时长` | `float`               | `0.75` | 当片段条目没有逐片段覆盖时使用的交叉淡化时长（秒）。范围：0.05–2.5 |

#### 内置库

SDK 随附三个预构建库，位于 `Packages/`<code class="expression">space.vars.sdk\_package\_id</code>`/SamplesShared/Resources/Embodiment/DialogueAnimation/Libraries/`:

| 资源名称                                               | 风格                |
| -------------------------------------------------- | ----------------- |
| `ConvaiSamplesShared_DialogAnimationLib_Balanced`  | 专业、克制的手势——适合大多数角色 |
| `ConvaiSamplesShared_DialogAnimationLib_Expresive` | 高能量、富有表现力的手势      |
| `ConvaiSamplesShared_DialogAnimationLib_Subtle`    | 克制、低能量的动作         |

***

### DialogueClipEntry

库中的每个 `空闲条目` 或 `讲话条目` 数组项都是一个 `DialogueClipEntry`。这些字段控制哪些片段符合当前角色和情绪的条件，以及它们如何混合。

| 字段         | 类型                          | 默认      | 描述                                     |
| ---------- | --------------------------- | ------- | -------------------------------------- |
| `片段`       | `AnimationClip`             | 无       | 要播放的动画片段                               |
| `性别`       | `CharacterGender`           | `中性`    | 该片段制作时所对应的骨架性别。请参见下方过滤规则。              |
| `首选情绪`     | `DialogueEmotionAffinity[]` | 空       | 会提高该片段被选中概率的情绪标签                       |
| `选择权重`     | `float`                     | `1.0`   | 基础选择权重。数值越高，该片段越可能被选中。范围：0.1–5.0       |
| `交叉淡化时长覆盖` | `float`                     | `0`     | 单个片段的交叉淡化时长（秒）。 `0` 表示使用库的 `默认交叉淡化时长`. |
| `讲话身体覆盖范围` | `DialogueTalkBodyCoverage`  | `身体和头部` | 该片段填充哪些讲话层。仅适用于讲话条目。                   |

#### 角色性别筛选

| 值    | 使用时                        |
| ---- | -------------------------- |
| `中性` | 适用于任何性别的角色。始终在选择池中。        |
| `男性` | 仅适用于以下角色： `角色性别` 设置为 `男性`. |
| `女性` | 仅适用于以下角色： `角色性别` 设置为 `女性`. |

具有以下设置的角色： `角色性别 = 男性` 会从中性和男性片段中同时抽取。具有以下设置的角色： `角色性别 = 中性` 仅从中性片段中抽取。

#### DialogueEmotionAffinity 值

这些标签会将片段选择偏向当前的情绪读数。具有 `PreferredEmotions = [Happy, Energetic]` 在情绪输出为快乐或充满活力时，更有可能被选中。

`中性` · `快乐` · `悲伤` · `愤怒` · `惊讶` · `恐惧` · `好奇` · `充满活力`

情绪偏置强度由 `EmotionBiasStrength` 在 `DialogueAnimationRuntimeConfig`.

#### DialogueTalkBodyCoverage 值

| 值       | 效果                              |
| ------- | ------------------------------- |
| `仅头部`   | 片段仅填充头部讲话层（第 3 层）               |
| `身体和头部` | 片段同时填充身体讲话层（第 2 层）和头部讲话层（第 3 层） |
| `仅身体`   | 片段仅填充身体讲话层（第 2 层）               |

***

### DialogueAnimationRuntimeConfig

一个 `DialogueAnimationRuntimeConfig` 控制所有时序、混合和选择行为。为每个角色分配一个配置资源，或在多个角色之间共享同一个配置。

**通过以下方式创建：** 资源菜单 → **创建 → Convai → 化身 → 对话动画运行时配置**

#### 层权重

| 字段           | 默认     | 范围      | 描述                    |
| ------------ | ------ | ------- | --------------------- |
| `基础层权重`      | `1.0`  | 0–1     | 基础空闲层的恒定权重            |
| `空闲叠加层权重`    | `1.0`  | 0–1     | 空闲时空闲叠加层的权重           |
| `讲话时空闲叠加层权重` | `1.0`  | 0–1     | 讲话期间的空闲叠加层权重          |
| `空闲叠加权重混合秒数` | `0.95` | 0.1–4.0 | 在空闲和讲话值之间混合空闲叠加权重所需时间 |

#### 空闲轮换

| 字段          | 默认      | 范围                 | 描述                          |
| ----------- | ------- | ------------------ | --------------------------- |
| `空闲最短保持秒数`  | `8.0`   | 2–30               | 切换到下一个空闲片段前的最少秒数            |
| `空闲最长保持秒数`  | `20.0`  | ≥ `空闲最短保持秒数` + 0.5 | 切换到下一个空闲片段前的最长秒数            |
| `空闲交叉淡化时长`  | `0.95`  | 0.15–3.0           | 空闲片段之间交叉淡化的持续时间             |
| `讲话时轮换空闲叠加` | `false` | —                  | 当 `true`，即使角色在讲话，空闲叠加片段也会轮换 |

#### 身体讲话层

| 字段          | 默认     | 范围      | 描述               |
| ----------- | ------ | ------- | ---------------- |
| `身体讲话层淡入秒数` | `0.95` | 0.1–4.0 | 语音开始时身体讲话层淡入所需时间 |
| `身体讲话层淡出秒数` | `1.05` | 0.1–4.0 | 语音结束后身体讲话层淡出所需时间 |
| `身体讲话层峰值权重` | `1.0`  | 0–1     | 在完整语音下的最大层权重     |

#### 头部讲话层

| 字段          | 默认     | 范围      | 描述               |
| ----------- | ------ | ------- | ---------------- |
| `头部讲话层淡入秒数` | `0.95` | 0.1–4.0 | 语音开始时头部讲话层淡入所需时间 |
| `头部讲话层淡出秒数` | `1.05` | 0.1–4.0 | 语音结束后头部讲话层淡出所需时间 |
| `头部讲话层峰值权重` | `1.0`  | 0–1     | 在完整语音下的最大层权重     |

#### 讲话交叉淡化

| 字段         | 默认     | 范围       | 描述                |
| ---------- | ------ | -------- | ----------------- |
| `讲话交叉淡化时长` | `0.75` | 0.15–3.0 | 连续讲话片段之间交叉淡化的持续时间 |

#### 语音能量调制

这些字段允许口型同步能量调制讲话层权重，因此在更大声的语音中，手势会显得更强烈。

| 字段               | 默认     | 范围       | 描述                            |
| ---------------- | ------ | -------- | ----------------------------- |
| `使用口型同步语音能量`     | `true` | —        | 当 `true`，口型同步振幅会调制讲话层权重       |
| `语音能量窗口秒数`       | `0.08` | 0.02–0.5 | 能量测量的平滑窗口                     |
| `语音能量增益`         | `1.25` | 0.1–10   | 在应用到层权重之前放大能量信号               |
| `语音能量最小讲话层缩放`    | `0.65` | 0–1      | 下限缩放——在语音期间，讲话层绝不会低于峰值权重的这一比例 |
| `讲话层缩放时忽略面部对话阶段` | `true` | —        | 当 `true`，面部口型同步阶段不会限制手势能量     |

{% hint style="info" %}
`使用口型同步语音能量` 需要一个 `ConvaiLipSync` 组件位于同一个角色上。如果没有口型同步，讲话层将以恒定峰值权重播放。
{% endhint %}

#### 片段选择

| 字段                    | 默认          | 范围  | 描述                                             |
| --------------------- | ----------- | --- | ---------------------------------------------- |
| `EmotionBiasStrength` | `1.5`       | 0–5 | 当片段的 `首选情绪` 与当前情绪匹配时，应用于其权重的乘数。 `0` 完全禁用情绪偏置。  |
| `确定性种子`               | `0xC0B1AEu` | —   | 用于选择随机数生成器的种子。为每个角色的配置资源设置不同的值，以防止多角色场景中的动画同步。 |
| `测试用确定性选择`            | `false`     | —   | 强制完全确定性的片段选择；仅在测试中使用                           |

#### 空闲混合安全

这些设置可防止在接近循环边界请求混合时出现突兀切换。

| 字段              | 默认     | 范围        | 描述                         |
| --------------- | ------ | --------- | -------------------------- |
| `循环包裹附近的空闲混合门控` | `true` | —         | 如果当前片段处于其循环包裹窗口内，则延迟空闲轮换请求 |
| `空闲循环包裹窗口比例`    | `0.12` | 0.02–0.45 | 片段末尾被视为“接近包裹”窗口的长度比例       |
| `空闲混合门控宽限秒数`    | `4.0`  | 0.5–30    | 混合门控在强制切换之前可保持的最长秒数        |

***

### ConvaiDialogueAnimationProfile

一个 `ConvaiDialogueAnimationProfile` 将所有模块配置打包到一个可分配的资源中。

**通过以下方式创建：** 资源菜单 → **创建 → Convai → 化身 → 对话动画配置文件**

| 字段                | 类型                               | 描述                                                    |
| ----------------- | -------------------------------- | ----------------------------------------------------- |
| `库`               | `DialogueAnimationLibrary`       | 片段池                                                   |
| `运行时配置`           | `DialogueAnimationRuntimeConfig` | 时序和选择参数                                               |
| `动画器契约`           | `DialogueAnimatorContract`       | 层和状态名称映射（可选——未分配时使用默认值）                               |
| `基础空闲片段`          | `AnimationClip`                  | 在基础层上播放的固定片段，作为所有叠加层下方的静态基础                           |
| `CharacterGender` | `CharacterGender`                | 片段选择的性别过滤                                             |
| `自动创建对话流`         | `bool` （默认： `true`)              | 当 `true`，如果未注册任何驱动器，模块会自动创建一个内部对话流驱动器，确保讲话层无需显式连接即可激活 |

#### 内置配置文件

SDK 随附三个预构建配置文件，位于 `Packages/`<code class="expression">space.vars.sdk\_package\_id</code>`/SamplesShared/Resources/Embodiment/DialogueAnimation/`:

| 资源名称                                                      | 风格          |
| --------------------------------------------------------- | ----------- |
| `ConvaiSamplesShared_DialogueAnimationProfile_Balanced`   | 平衡库 + 默认配置  |
| `ConvaiSamplesShared_DialogueAnimationProfile_Expressive` | 表现力库 + 默认配置 |
| `ConvaiSamplesShared_DialogueAnimationProfile_Subtle`     | 细腻库 + 默认配置  |

位于 `ConvaiDialogueAnimationController` 优先于配置文件。如果同时分配了配置文件和直接的 Library 字段，则以 Library 字段为准。

***

### 下一步

既然你已经了解这些配置资源，请查看 Animator Controller 对四层契约的要求，或直接前往使用示例，以在上下文中查看完整的配置模式。

{% content-ref url="/pages/9e00cc9c176681b9489a9cd12ee13917fd6f11ea" %}
[Animator Controller 要求](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animator-controller-requirements.md)
{% endcontent-ref %}

{% content-ref url="/pages/b57405f03c1f45cc9e305ce32db7cbe06e914f5b" %}
[对话动画使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/usage-examples.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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animation-libraries-and-profiles.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.