> 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/embodiment-presets.md).

# 具身化预设

将多个具身化模块的配置文件打包为一个可复用预设，并应用到角色上，使每个模块的设置一起随之移动。

具身预设会将每个模块（凝视、身体动画、肢体语言、对话流程和情绪）的一个配置文件打包到单个资源中。这样，角色原型的完整个性就能作为一个整体进行发布和更新，而不必分别分配五个配置文件。请使用本页创建预设并将其应用到角色。

### 前提条件

* 已安装 Convai Unity SDK
* 已添加所需具身模块的角色，并且每个模块都已在 Inspector 中分配了各自的配置文件

### 创建预设资源

选择 **Assets > Create > Convai > Embodiment > Preset**。这会创建一个 `ConvaiEmbodimentPreset` 资源，其中包含一个 **Identity** 部分，用于保存 **Preset ID** （默认为 `default`）和 **Description**.

**Preset ID** 是其他系统引用此预设时使用的简短标识符，例如作为 `ConvaiEmbodimentPresetLibrary` 中的条目。请将其设置为具体名称，例如 `guide-npc` 或 `drill-instructor`，不要保留默认值。

### 向预设添加功能

在 **Features**下，点击 **Add Feature** 以添加一个配置文件槽位。每一行都提供一个 **Feature** 下拉菜单，其中仅列出项目中已有的具身模块—— **身体动画**, **肢体语言**, **对话流程**, **情绪**和 **凝视** ——以及一个 **Settings** 字段，该字段只接受此功能指定的配置文件资源类型，因此无法分配类型不匹配的配置文件。

| 功能   | 模块 ID                      | 配置文件类型                          |
| ---- | -------------------------- | ------------------------------- |
| 身体动画 | `convai.body-animation`    | `ConvaiBodyAnimationProfile`    |
| 身体语言 | `convai.body-language`     | `ConvaiBodyLanguageProfile`     |
| 对话流程 | `convai.conversation-flow` | `ConvaiConversationFlowProfile` |
| 情绪   | `convai.emotion`           | `ConvaiEmotionProfile`          |
| 凝视   | `convai.gaze`              | `ConvaiGazeProfile`             |

要让预设控制哪些模块，就为每个模块添加一行。无需为每个模块都添加一行——仅包含凝视和情绪的预设也是有效的。点击 **移除最后一行** 可删除最近添加的一行；也可以点击某一行上的 **×** 按钮删除该行。

{% hint style="warning" %}
两行具有相同功能属于配置错误： `HasDuplicateModuleIds(out string message)` 会返回 `true`，并且 **设置检查** 部分会将其报告为可修复的问题。运行时只会使用第一个匹配的槽位。
{% endhint %}

在脚本中使用以下方法读取槽位的配置文件： `TryGetProfile(string moduleId, out ScriptableObject profile)`当没有槽位与给定的模块 ID 匹配时，该方法会返回 `false` 。

### 将预设应用到角色

将 **预设** 组件（`Convai/Embodiment/Preset` 可在“添加组件”菜单中找到）添加到角色根对象，并将预设资源分配给其 **预设** 字段。

在 `Awake`时，该组件会查找角色上所有接收具身配置文件的组件，并根据模块 ID 将预设中匹配的槽位应用到每个组件。对于没有匹配槽位的模块，其配置文件将保留检查器中分配的配置文件，或被清除，具体取决于 **保留缺失槽位**:

| `Preserve Missing Slots` | 没有匹配预设槽位时模块的行为      |
| ------------------------ | ------------------- |
| `true` （默认）              | 保留在检查器中已分配给该模块的配置文件 |
| `false`                  | 清除该模块的配置文件          |

从脚本调用 `Apply(ConvaiEmbodimentPreset)` 可在运行时切换预设；该方法会重新扫描角色的接收器并重新应用所有槽位。

### 使用库在运行时切换预设

将 `ConvaiEmbodimentPresetLibrary` 资源（**Assets > Create > Convai > Embodiment > Preset Library**）分配给 **库** 字段，即可启用基于 ID 的运行时切换。库中保存按顺序排列的预设列表，并可按以下方式解析出一个预设 `Find(id)`，将每个预设的 `PresetId` 进行不区分大小写的匹配。

{% hint style="info" %}
分配库本身不会应用任何内容。调用 `ApplyPresetById(string id)` ，在 `Preset` 组件上查找库中的预设并应用它——该库是查找表，而不是活动绑定。
{% endhint %}

### 验证预设是否已应用

打开预设资源的 **设置检查** 部分：其中会列出检查结果，例如重复的功能行、空的设置槽，以及针对使用此预设的角色上不存在的功能的行；大多数问题都可以一键修复。没有检查结果的预设会显示状态正常。

进入播放模式后，在角色的 Inspector 中检查每个模块的配置文件字段：它应显示预设中对应槽位的配置文件；如果 **保留缺失槽位** ，则显示模块自身的配置文件。如果某个槽位的配置文件未能应用， **Preset** 组件会记录一条警告，指出模块 ID 和原因——配置文件类型不匹配、接收器缺失或槽位重复。

### 后续步骤

{% content-ref url="/pages/dddb9a87015e6befbe3c15caf6aa6b2df224fa33" %}
[角色骨架设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/character-rig-setup.md)
{% endcontent-ref %}

{% content-ref url="/pages/526da9bf1ae481254ffde1d02128e23947af7af5" %}
[具身化编辑器窗口](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/embodiment-editor.md)
{% endcontent-ref %}

{% content-ref url="/pages/8eaf58d7e1fc1a2176b0c4b26425f595bc8e8851" %}
[资产所有权与写时复制](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/asset-ownership.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
