> 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/quick-start.md).

# 对话动画快速开始

使用捆绑的示例资源为 AI 角色添加手势动画。Dialogue Animation 模块需要三样东西：一个四层 Animator 控制器，包含命名的占位动画片段，一个 `DialogueAnimationLibrary` 包含待机和对话片段，并且有一个 `DialogueAnimationRuntimeConfig` 用于控制时序。本指南将使用捆绑的示例资源带你走最快的路径。

### 先决条件

* `ConvaiRoomManager` 以及至少一个 `ConvaiCharacter` 已经在你的场景中
* 该角色 GameObject 有一个 `Animator` 组件，已配置人形 Avatar
* 你知道 SDK 示例资源的路径： `Packages/`<code class="expression">space.vars.sdk\_package\_id</code>`/SamplesShared/`

***

### 设置

{% stepper %}
{% step %}

#### 复制示例 Animator 控制器

在项目窗口中，导航到：

```
Packages/com.convai.convai-sdk-for-unity/SamplesShared/Art/Animations/Dialogue/Controllers/
```

复制 `ConvaiSample_Animator Controller` 并将其移动到你项目的 `Assets/` 文件夹中。将其分配给你角色根 GameObject 上的 `Animator` 组件。

示例控制器已经包含所需的四层结构和占位动画片段。请参阅 [Animator 控制器要求](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animator-controller-requirements.md) 以了解完整的图层和动画片段契约，或者参阅 [构建兼容的 Animator 控制器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animator-controller-setup.md) 如果你需要自己构建。
{% endstep %}

{% step %}

#### 添加 ConvaiDialogueAnimationController

选择你角色的根 GameObject。在 Inspector 中，单击 **添加组件** 并搜索 **对话动画** （或通过 **Convai → Embodiment → Dialogue Animation**).

进入）组件会出现，且其 `库` 是位于 `配置` 字段为空，并带有一个默认的 `Character Gender` 为 **Neutral**.
{% endstep %}

{% step %}

#### 分配一个库

在项目窗口中，导航到：

```
Packages/com.convai.convai-sdk-for-unity/SamplesShared/Resources/Embodiment/DialogueAnimation/Libraries/
```

有三个捆绑库可供使用：

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

将你选择的库拖到组件上的 **库** 字段中。
{% endstep %}

{% step %}

#### 分配运行时配置

导航到：

```
Packages/com.convai.convai-sdk-for-unity/SamplesShared/Resources/Embodiment/DialogueAnimation/
```

将捆绑的一个 `ConvaiDialogueAnimationProfile_*` 资源拖到 **配置** 字段中——或者直接分配一个 `DialogueAnimationRuntimeConfig` 资源。

{% hint style="danger" %}
将 **配置** 留空会禁用所有动画。未分配配置前，该组件不会播放动画。
{% endhint %}
{% endstep %}

{% step %}

#### 设置角色性别

设置 **Character Gender** 以匹配你的角色骨架：

* **Neutral** ——没有性别标签的片段都可用（默认；适用于大多数骨架）
* **Male** ——将带有 Male 标签的片段添加到可用池中
* **Female** ——将带有 Female 标签的片段添加到可用池中

Neutral 角色只会接收带 Neutral 标签的片段。Male 和 Female 角色会同时接收各自性别专属片段和 Neutral 片段。
{% endstep %}

{% step %}

#### 进入播放模式

按下 Play。你的角色应会立即开始播放待机动画。当对话开始且角色说话时，讲话图层会淡入，并播放与检测到的情绪相匹配的手势动画。

**预期结果：** 待机片段在静止时会以自然的交叉淡化循环播放。当角色说话时，身体讲话和头部讲话图层会淡入。控制器上的 `CurrentTalkLayerWeight` 属性会高于 `0` 在说话期间。
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
发布前需要的 Inspector 截图：请截取 `ConvaiDialogueAnimationController` 角色根对象上的该组件，并按第 3–5 步所述分配 Library、Config 和 Character Gender 字段。
{% endhint %}

***

### 替代方案：使用捆绑的配置文件

你也可以不分别分配 Library 和 Config，而是分配一个 `ConvaiDialogueAnimationProfile` 添加到 **Profile** 插槽。配置文件将 Library、RuntimeConfig、AnimatorContract、CharacterGender 和 FoundationIdleClip 打包到一个资源中。

有三个捆绑配置文件可用，位于：

```
Packages/com.convai.convai-sdk-for-unity/SamplesShared/Resources/Embodiment/DialogueAnimation/
```

分配 `ConvaiDialogueAnimationProfile_Balanced`, `_Expressive`，或 `_Subtle` 到配置文件插槽中。如果两者都已分配，组件上的单独 Library 和 Config 字段将优先生效。

***

### 下一步

现在你的角色会根据对话状态和情绪播放手势动画。阅读 Animation Libraries & Profiles，了解如何编写自定义片段库，或阅读 Animator 控制器要求，以查看完整的四层契约参考。

{% content-ref url="/pages/0f3cbc0e4633317c448740563d0c38854e7725ee" %}
[动画库与配置文件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/dialogue-animation/animation-libraries-and-profiles.md)
{% endcontent-ref %}

{% 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 %}


---

# 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/quick-start.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.