> 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/body-animation/build-an-animation-set.md).

# 构建动画集

通过“创建动画集”向导，或逐字段编写条目，从一个动画片段文件夹中组装你自己的动画集。

构建你自己的 `ConvaiBodyAnimationSet` 当 SDK 随附的集合与你的角色不匹配时——例如不同的原型、性别或生物骨骼绑定。等你有了一个准备分配的人形动画片段文件夹后，或当你需要手动编写单独的待机、对话、动作或指向条目时，请使用此页面。

***

### 前提条件

* 适用于你的角色的人形动画片段。使用 Convai 命名约定命名的片段（`Walk`, `Jog`, `WalkStart_90L`, `Point_CF`，以及类似名称）可由下面的向导自动匹配；其他名称的片段仍然可用，但向导不会自动匹配它们。
* 某个 `ConvaiBodyAnimationController` 如果你正在为特定角色构建集合，则已添加——请参见 [身体动画快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/quick-start.md).

***

### 打开创建动画集合向导

向导本身没有独立的菜单项。请从其结果会被使用的任一位置打开它：

* 该 **Body Animation Editor** 窗口的 **内容** 模式——从以下位置打开窗口： **Convai > 身体动画编辑器**粘贴你的密钥，然后选择 **创建动画集合…**.
* 当未分配任何动画内容时，组件检查器中的设置清单——选择 **创建动画集合…** 清单下方的注释。

***

### 匹配片段并构建集合

{% stepper %}
{% step %}

#### 选择目标

将 **现有集合** 留空以创建新的 `ConvaiBodyAnimationSet`，或分配一个以填补你已创建的集合中的空缺。对于新集合，请设置一个 **显示名称** 和一个 **新集合路径**.
{% endstep %}

{% step %}

#### 添加你的片段

分配一个 **文件夹** 并选择 **扫描文件夹** 以导入其下的所有动画片段，或者先在项目窗口中选择单个片段，然后使用 **添加所选片段**.
{% endstep %}

{% step %}

#### 审查匹配建议

选择 **按名称匹配片段**。使用 Convai 命名约定命名的片段会被建议到某个槽位——待机、对话、移动、指向或动作——每个都作为一行可编辑内容，并带有置信度标记（**匹配**, **猜测**, **审查**，或 **未识别**）。目前还不会写入任何资源。匹配器无法识别的片段会被列出，并默认排除；你可以手动分配一个类别以将其包含进来。
{% endstep %}

{% step %}

#### 构建集合

选择 **构建动画集合**。向导会将已确认的建议写入目标集合；当内容需要时，会自动生成上半身叠加遮罩，并对它写入的每个移动片段运行片段运动分析器——这一步可防止脚滑。报告会列出已写入的内容、已跳过的内容以及当前的移动覆盖情况。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**预期结果：** 一个 `ConvaiBodyAnimationSet` 位于你所选路径的资源，其中的待机、对话、移动、动作和指向内容已填充并测量完毕——可随时分配给一个 `ConvaiBodyAnimationController`.
{% endhint %}

***

### 手动编写条目

向导所做的一切也都可以逐字段组装，在 `ConvaiBodyAnimationSet` 资源本身上，或在身体动画编辑器的内容模式中。

#### 待机条目

| 字段    | 作用                                          |
| ----- | ------------------------------------------- |
| `片段`  | 一个循环的人形片段，带有 **循环时间** 已启用的情况下发布。            |
| `权重`  | 相对随机选择权重。 `0` 会禁用该变体。                       |
| `亲和性` | 可选 `EmotionAffinity` 条目会在匹配情绪占主导时，将选择偏向该变体。 |

#### 对话条目

对话条目也会原样用于可选的 Listen 和 Think 池。

| 字段              | 作用                                              |
| --------------- | ----------------------------------------------- |
| `片段`            | 一个循环的人形片段，带有 **循环时间** 已启用的情况下发布。                |
| `权重`            | 相对随机选择权重。                                       |
| `覆盖范围`          | `UpperBody` （移动时安全）或 `FullBody` （仅在静止时生效）。      |
| `叠加`            | 将片段作为叠加差值播放在基础姿势之上，而不是覆盖它。需要在片段导入设置中烘焙一个叠加参考姿势。 |
| `叠加片段`          | 可选的、已叠加烘焙的对应片段，在角色行走时使用，因此手臂摆动仍能保留在手势之下。        |
| `引入片段` / `收尾片段` | 可选的一次性引入和收尾。两者都必须将 **循环时间** 关闭。                 |
| `亲和性`           | 可选的基于情绪的选择偏向，与待机条目相同。                           |

#### 移动片段

该 `LocomotionSection` 包含 26 个命名片段槽位，按其增加的内容分组。只有 **Walk** 是基础移动所必需的——其余每个槽位都会解锁一个各自可选的功能。

| 组       | 槽位                           | 解锁内容                   |
| ------- | ---------------------------- | ---------------------- |
| 移动循环    | Walk, Jog                    | 基础行走和慢跑。               |
| Walk 起始 | 前方、左 90°、右 90°、左 180°、右 180° | 从静止待机开始的定向起始。          |
| Jog 起始  | 前方、左 90°、右 90°、左 180°、右 180° | 进入慢跑的定向起始。             |
| Walk 停止 | 左脚落地、右脚落地、低速、骤停              | 带脚步落地的停止动作，而不是普通的待机混合。 |
| Jog 停止  | 左脚落地、骤停                      | 以慢跑速度进行的带脚步落地停止动作。     |
| 速度变化    | Walk→Jog 左/右，Jog→Walk 左/右    | 混合步态过渡，而不是硬性的速度切换。     |
| 原地转身    | 90° 左、90° 右、180° 左、180° 右    | 动画化转身，而不是横移式旋转。        |

每个槽位都会将一个片段与测得的运动元数据（作者设定的速度、距离和偏航）配对，这些元数据由片段运动分析器自动填充——无论是通过向导构建，还是按下 **测量片段** 集合检查器上的此项会为你运行分析器；你无需手动填写这些元数据。

#### 动作和手势

| 字段                     | 作用                                                                                                                                                         |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `动作名称`                 | 主名称 `PlayAction` 以及 Convai 动作会与其匹配，不区分大小写和分隔符。                                                                                                             |
| `别名`                   | 可解析到同一条目的其他名称。                                                                                                                                             |
| `片段` / `引入片段` / `收尾片段` | 主片段外加可选的一次性引入和收尾片段。                                                                                                                                        |
| `遮罩模式`                 | `FullBody` （播放时暂停移动）， `UpperBody`，或 `CustomMask`.                                                                                                          |
| `循环模式`                 | `PlayOnce`, `LoopCount` （重复 `循环次数` 次），或 `HoldUntilStopped`.                                                                                                |
| `速度`                   | 播放速度倍率。                                                                                                                                                    |
| `暂停移动`                 | 全身动作默认开启。                                                                                                                                                  |
| `可中断`                  | 新请求的动作是否可以在播放中途打断此动作。                                                                                                                                      |
| `提示`                   | 可选语义标签（例如 `肯定`），同级模块无需知道此条目名称即可请求。                                                                                                                         |
| `锚点选项`                 | 用于以下项的默认接近偏移和朝向： `PlayActionAt` ——参见 [播放动作和手势](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/play-actions-and-gestures.md). |
| `允许对话叠加层`              | 对于全身 `HoldUntilStopped` 动作，它会保持对话和指向叠加层继续生效，而不是将它们降为零。                                                                                                     |
| `Ambient`              | 将此条目标记为角色在长时间待机时可自行执行的内容。只有在配置中启用后才会生效。                                                                                                                    |

#### 指向条目

| 字段     | 作用                                    |
| ------ | ------------------------------------- |
| `片段`   | 一个抬起-保持-放下的指向手势片段。                    |
| `偏航角度` | 片段所指向的角色局部偏航（`0` 前方， `+` 右侧， `-` 左侧）。 |
| `俯仰角度` | 角色局部俯仰（`+` 上方， `-` 下方）。               |

`PointAt` 会按角度选择与请求方向最接近的已制作条目，因此你不必编写全部 15 个指向方向——分布在罗盘各处的几个方向已经能提供相当不错的覆盖。

***

### 验证集合

选择 **测量片段** 在集合的检查器中，或在 Body Animation Editor 窗口的内容模式中，在手动更改片段后重新运行片段运动分析器。查看集合的结果——缺少上半身遮罩、非循环待机片段或重复的动作名称，都会作为带有严重级别的列出问题出现。

{% hint style="success" %}
**预期结果：** 不再存在阻塞发布的发现，并且将该集合分配给一个 `ConvaiBodyAnimationController` 会在播放模式下播放待机和对话动画。
{% endhint %}

***

### 故障排除

参见 [排查身体动画](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/troubleshooting.md) 以解决脚滑、缺少上半身遮罩和其他制作问题。

***

### 下一步

{% content-ref url="/pages/0b1776a0ab300843aca8154fbdecf361fa671b9d" %}
[身体动画快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/2f6d4e1228a37a16fdb14e3c1941f0d1c8cf7692" %}
[配置移动](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/configure-locomotion.md)
{% endcontent-ref %}

{% content-ref url="/pages/13dbbe592147612edba60a45974dc24d1b9f3e61" %}
[播放动作和手势](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/body-animation/play-actions-and-gestures.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/body-animation/build-an-animation-set.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.