> 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` 在角色上（人形或通用）
* 至少向角色添加了一个具身模块（凝视、身体动画、肢体语言、对话流程或情绪），因为这会触发 Convai 解析骨架绑定

### 让 Convai 自动检测骨架

Convai 会添加 `角色 Rig` 组件（`Convai/Embodiment/Character Rig` 到添加组件菜单）到角色根节点，当某个具身模块首次需要骨架绑定时。在常见情况下，你无需手动添加它。

当组件添加后，它会扫描角色层级中的 `SkinnedMeshRenderer` 带有混合形状的组件，并将其名称与四种内置规范进行匹配： **Apple ARKit**, **Reallusion Character Creator 3**, **Epic MetaHuman**，以及 **Reallusion Character Creator 4（扩展版）**。它还会从角色的人形 Avatar 中解析语义骨骼（`骨盆`, `脊柱`, `头部`，以及另外 15 个），如果存在人形 Avatar；否则会回退到名称匹配。

打开 **角色 Rig** 在检查器中查看组件以查看结果：

* **Character Type** 报告检测到的 **Rig 类型** 和一个 **匹配** 强度 — `强`, `部分`，或 `弱` — 或 `由你设置` 如果你手动选择了某种类型
* **Convai 找到的骨骼** 列出全部 18 个语义骨骼及其对应解析结果
* **Convai 找到的面部形状** 列出每个语义混合形状以及其解析到的网格和索引，或者 `未在此骨架上找到`

{% hint style="success" %}
当以下情况时检测成功 **Character Type** 显示一个已识别的 Rig 类型，并且没有报告骨盆、脊柱或头部骨骼缺失。检查器标题在该状态下显示 **Ready** 。
{% endhint %}

### 修复低置信度检测

如果检查器警告面部形状只被部分识别，或者完全没有匹配任何规范，那么在回退到自定义映射之前，你有两个选项：

1. **你自己选择 Rig 类型。** 打开 **Rig 类型** 字段位于 **Character Type** 下，并选择正确的规范（**Apple ARKit**, **Reallusion Character Creator 3**, **Epic MetaHuman**，或 **Reallusion Character Creator 4（扩展版）**）而不是保持为 **自动检测**。这会跳过检测并直接应用该规范的名称表。
2. **手动分配缺失的骨骼。** 如果 **Convai 找到的骨骼** 报告缺失了 `骨盆`, `脊柱`，或 `头部` 骨骼，展开 **自定义 Rig 设置** 并分配正确的 `Transform` 到对应的覆盖字段。该 Transform 必须属于角色自身的层级。点击 **锁定 Convai 找到的结果** 可将 Convai 已解析出的每个骨骼复制到这些覆盖字段中，这样即使模型被重新导入或重命名，它们也会保持固定。

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

### 映射自定义 Rig 规范

当角色的面部网格使用的混合形状名称与四种内置规范都不匹配时，请使用自定义规范映射。

1. 创建一个 `CustomRigConventionMap` 资源： **Assets > Create > Convai > Embodiment > Custom Rig Convention Map**.
2. 从 `StandardBlendshape` 枚举中你想驱动的每个语义混合形状添加一项，并将每项的混合形状名称设置为你网格上的名称。将某项的名称留空可在该角色上跳过该语义混合形状。
3. 在 **角色 Rig** 组件上，设置 **Rig 类型** 到 **自定义——我会自己映射名称**，然后将资源分配到 **自定义规范映射** 字段。
4. 点击 **重新扫描此角色**.

{% hint style="warning" %}
当 **Rig 类型** 为 `Custom` 时，骨骼解析仍会通过人形 Avatar 或名称匹配进行——只有混合形状解析会读取自定义映射。如果 Avatar 无法解析它们，请在 **自定义 Rig 设置** 下单独分配骨骼覆盖。
{% endhint %}

### 验证骨架设置

检查 **找到的骨骼** 和 **找到的面部形状** 在检查器标题中：一个健康的骨架会显示所有关键骨骼都已解析，并且有一个已识别的 Rig 类型且没有警告框。从脚本中，读取 `DetectedConvention` 和 `DetectionConfidence` 组件上的 `角色 Rig` 组件，或调用 `TryGetBone(StandardBone, out Transform)` 和 `TryGetBlendshape(StandardBlendshape, out SkinnedMeshRenderer, out int)` 以确认某个特定语义标识符能够成功解析。

并非每个骨架都会提供每一根骨骼或每一个混合形状。 `上胸` 和眼部骨骼是可选的——当没有眼部骨骼时，凝视支持仅用头部瞄准——因此仅缺少它们并不表示设置有问题。

### 下一步

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

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

{% content-ref url="/pages/5027f813885b08acbe9044a4bb7b9166e9b01bc2" %}
[排查具身化问题](/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 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/character-rig-setup.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.