> 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/character-rig-setup.md).

# 角色骨架设置

配置角色骨架，使 Convai 自动检测其面部 blendshape 规范和骨骼，并解决低置信度检测。

每个具身角色都需要将其骨架和面部网格映射到具身模块读取的语义骨骼和混合形状。使用此页面查看 Convai 在角色绑定中检测到的内容、修正置信度较低的结果，或映射使用 Convai 无法识别的命名约定的绑定。

### 前提条件

* 一个角色 `GameObject` 带有 `SkinnedMeshRenderer` 面部网格，且该网格包含混合形状
* 一个 `Animator` 组件（位于角色上，类型为 humanoid 或 generic）
* 至少向角色添加一个具身模块（Gaze、Body Animation、Body Language、Conversation Flow 或 Emotion），因为这会触发 Convai 解析绑定

### 让 Convai 自动检测绑定

Convai 会在具身模块首次需要绑定时，将 `Character Rig` 组件（`Convai/Embodiment/Character Rig` 在 Add Component 菜单中）添加到角色根对象。通常情况下，无需手动添加该组件。

添加该组件后，它会扫描角色层级中的 `SkinnedMeshRenderer` 组件，查找包含混合形状的组件，并将其名称与四种内置约定进行匹配： **Apple ARKit**, **Reallusion Character Creator 3**, **Epic MetaHuman**以及 **Reallusion Character Creator 4 (Extended)**。如果角色具有 humanoid avatar，组件还会从中解析语义骨骼（`Hips`, `Spine`, `Head`以及另外 15 个）；否则会改用名称匹配。

在 Inspector 中打开 **Character Rig** 组件即可查看结果：

* **Character Type** 显示检测到的 **Rig type** 以及 **Match** 强度—— `Strong`, `Partial`、或 `Weak` ——或者 `Set by you` （如果你手动选择了类型）
* **Bones Convai Found** 列出全部 18 个语义骨骼及各自解析到的对象
* **Face Shapes Convai Found** 列出每个语义混合形状，以及其解析到的网格和索引；如果未找到，则显示 `not found on this rig`

{% hint style="success" %}
检测成功的条件是 **角色类型** 显示已识别的骨架类型，且未报告缺少 Hips、Spine 或 Head 骨骼。此时，检视器标题显示为 **就绪** 。
{% endhint %}

### 修复低置信度检测结果

如果检视器警告仅识别出部分面部形状，或者完全没有匹配的约定，在使用自定义映射之前，你有两种选择：

1. **自行选择骨架类型。** 打开 **骨架类型** 字段，该字段位于 **角色类型** 下，然后选择正确的约定（**Apple ARKit**, **Reallusion Character Creator 3**, **Epic MetaHuman**，或 **Reallusion Character Creator 4（扩展版）**），而不是保留 **自动检测**选项。这样会跳过检测，直接应用该约定的名称表。
2. **手动指定缺失的骨骼。** 如果 **Convai 找到的骨骼** 报告缺少 `Hips`, `Spine`或 `Head` 骨骼，请展开 **自定义骨架设置** ，并将正确的 `Transform` 指定给对应的覆盖字段。该 Transform 必须属于角色自身的层级结构。点击 **锁定 Convai 的查找结果** ，将 Convai 已识别的所有骨骼复制到这些覆盖字段中，使其即使在模型重新导入或重命名后也保持不变。

进行任何更改后，点击 **重新扫描此角色** 以重建解析表，或从脚本中调用 `Rebuild()` 。

### 映射自定义骨架约定

当角色面部网格使用的混合形状名称不匹配四种内置约定中的任何一种时，请使用自定义约定映射。

1. 创建一个 `CustomRigConventionMap` 资源： **资源 > 创建 > Convai > 具身化 > 自定义骨架约定映射**.
2. 从 `StandardBlendshape` 枚举中为要驱动的每个语义混合形状添加一个条目，并将每个条目的混合形状名称设为网格上的对应名称。将条目的名称留空，即可跳过此骨架上的该语义混合形状。
3. 在 **Character Rig** 组件上，将 **Rig Type** 设置为 **自定义 — 我将自行映射名称**，然后将资源分配给 **Custom Convention Map** 字段。
4. 点击 **重新扫描此角色**.

{% hint style="warning" %}
当 **Rig Type** 为 `Custom` 时，骨骼解析仍会通过 humanoid avatar 或名称匹配进行——只有 blendshape 解析会读取自定义映射。若 avatar 无法解析骨骼，请在 **Custom Rig Setup** 中单独分配骨骼覆盖项。
{% endhint %}

### 验证 Rig 设置

在 Inspector 标题栏中检查 **已找到的骨骼** 和 **已找到的面部形状** ：正常的 Rig 会显示所有关键骨骼均已解析，并识别出 Rig 类型，且没有警告框。在脚本中，读取 `DetectedConvention` 和 `DetectionConfidence` （位于 `Character Rig` 组件上），或调用 `TryGetBone(StandardBone, out Transform)` 和 `TryGetBlendshape(StandardBlendshape, out SkinnedMeshRenderer, out int)` 以确认特定语义标识符是否能够解析。

并非每个 Rig 都包含所有骨骼或 blendshape。 `UpperChest` 和眼部骨骼均为可选项——缺少眼部骨骼时，Gaze 仍支持仅瞄准头部——因此，单凭这些骨骼缺失并不表示设置有问题。

### 后续步骤

{% content-ref url="/pages/528b8780a5fa83913d2d3f95cdbf6b1a0c52b073" %}
[具身化如何运作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/how-embodiment-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/ae138cae5e0a278bc48c79d0ca79ef2ef46609d4" %}
[面部组合](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/facial-composition.md)
{% endcontent-ref %}

{% content-ref url="/pages/5027f813885b08acbe9044a4bb7b9166e9b01bc2" %}
[排查具身化问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/troubleshooting.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/character-rig-setup.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.
