> 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-unreal-engine-plugin/getting-started/set-up-a-metahuman-character.md).

# 设置 MetaHuman 角色

向 MetaHuman 添加 Convai Chatbot 和 Face Sync 组件，分配 Convai 动画类，并为 MetaHuman blendshape 配置唇形同步。

本指南将介绍如何将 MetaHuman 连接到 Convai Unreal Engine 插件，使其能够进行实时口型同步和面部动画。

{% embed url="<https://youtu.be/4fMCKkrfyaA>" %}
MetaHuman 角色设置指南
{% endembed %}

### 前提条件

* Convai 插件已安装，且 API 密钥已配置——请参阅 [安装 Convai 插件](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md) 和 [配置 API 密钥](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md).
* Unreal Engine 和 **MetaHuman** 插件已在你的项目中启用。
* 你已从控制面板获取 Convai 角色 ID。

### 导入 MetaHuman

{% hint style="info" %}
在 **Unreal Engine 5.4 及更高版本中**，MetaHuman 通过 **Fab** 插件管理，而非 Quixel Bridge。导入流程类似——使用 **Window > Fab** 或点击工具栏中的 **Fab** 按钮打开面板，然后导航到 MetaHuman 部分。请参阅 [Unreal Engine MetaHuman 文档](https://dev.epicgames.com/documentation/en-us/metahuman/importing-metahumans-to-unreal-engine-projects) ，了解适用于你所用引擎版本的当前导入流程。无论以何种方式导入 MetaHuman，导入后的 Convai 设置步骤都相同。
{% endhint %}

{% stepper %}
{% step %}

#### 打开 Quixel Bridge 或 Fab

在 Unreal Editor 菜单栏中，选择 **Window > Quixel Bridge** （UE 5.3 及更早版本）或 **Window > Fab** （UE 5.4 及更高版本）。导航到 **MetaHuman** 部分。
{% endstep %}

{% step %}

#### 将 MetaHuman 添加到项目

选择要使用的 MetaHuman，然后点击将其添加到项目。首次下载可能需要几分钟，因为系统需要下载纹理和资源。下载完成后， `MetaHumans` 文件夹会出现在 **内容浏览器**.
{% endstep %}

{% step %}

#### 打开 MetaHuman 蓝图

在 **内容浏览器**中，打开 `MetaHumans` 文件夹，找到你的 MetaHuman，然后双击蓝图（`.uasset`）文件。如果 Unreal Engine 提示你启用 MetaHuman 所需但尚未启用的插件，请点击 **是** 并重启编辑器。重启后，重新打开 MetaHuman 蓝图。
{% endstep %}
{% endstepper %}

### 添加 Convai 组件

{% stepper %}
{% step %}

#### 添加 Convai 聊天机器人组件

在 MetaHuman 的蓝图编辑器中，点击 **添加** 在 **组件** 面板中，搜索 `BP Convai ChatBot Component` 并选择它。

在该组件的 **细节** 面板中，将你的 **角色 ID** 从 Convai 控制面板复制并粘贴到 **角色 ID** 类别下的 **Convai** 字段中。
{% endstep %}

{% step %}

#### 添加 Convai Face Sync 组件

再次点击 **添加** ，位置在 **组件** 面板中。搜索 `Convai Face Sync` 并添加 `UConvaiFaceSyncComponent`.

在 **细节** 面板中，确认 **口型同步模式** 设置为 **MetaHuman 混合变形**。这是默认值，也是 MetaHuman 角色的正确设置。
{% endstep %}
{% endstepper %}

### 指定 Convai 动画蓝图

MetaHuman 角色的身体和面部使用独立的动画蓝图。Convai 插件在 `MetaHumans/Animations/` (`ConvAI > MetaHumans > Animations` （位于内容浏览器中）提供了两个资源，可将口型同步数据连接到 MetaHuman 骨架。

{% stepper %}
{% step %}

#### 设置身体动画类

在蓝图编辑器中，选择 **身体** 骨骼网格体组件。在 **细节** 面板中，找到 **动画类** 字段，位于 **动画**下方。将其设置为 `Convai_MetaHuman_BodyAnim`.
{% endstep %}

{% step %}

#### 设置面部动画类

选择 **面部** 骨骼网格体组件。在 **细节** 面板中，找到 **动画类** 字段。将其设为 `Convai_MetaHuman_FaceAnim`.
{% endstep %}

{% step %}

#### 编译并保存

点击 **编译** 然后 **保存** （位于蓝图编辑器工具栏中）。
{% endstep %}
{% endstepper %}

### 将 MetaHuman 添加到关卡

将 MetaHuman 蓝图从 **内容浏览器** 拖入关卡视口，并将其放置在所需位置。

### 将 Convai Player 组件添加到玩家 Pawn

如果尚未完成此操作，请打开玩家 Pawn 蓝图并添加 `UConvaiPlayerComponent`。请参阅 [添加你的第一个 Convai 角色](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/add-your-first-convai-character.md) 了解具体步骤。

### 测试设置

进入运行模式。使用按键通话（默认键： **T**），或使用聊天小组件开始对话。

{% hint style="success" %}
设置正常工作时，MetaHuman 的嘴部会与角色的语音回应同步运动，并在对话过程中动态改变面部表情。如果角色没有回应，请参阅 [验证你的设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/validate-your-setup.md).
{% endhint %}

### 手势和注视动画

从插件 4.0.0-beta.20 版本开始，插件附带注视和指向动画蓝图，以及位于 `MetaHumans/Animations/`下的手势动作库。当 Actions 系统发出 LLM 手势命令时，这些资源会通过 `BPI_Convai_Animation` 激活；除了上述唇形同步动画蓝图设置外，无需进行额外的蓝图连线。

#### 唇形同步动画蓝图

| 资源                          | Content 路径               | 用途                                     |
| --------------------------- | ------------------------ | -------------------------------------- |
| `Convai_MetaHuman_BodyAnim` | `MetaHumans/Animations/` | 身体动画 — 分配给 **身体** 骨骼网格体的 **动画类**.      |
| `Convai_MetaHuman_FaceAnim` | `MetaHumans/Animations/` | 面部动画和唇形同步 — 分配给 **面部** 骨骼网格体的 **动画类**. |

#### 注视和指向动画蓝图

| 资源               | Content 路径                      | 用途     |
| ---------------- | ------------------------------- | ------ |
| `A1D_MH_BEye`    | `MetaHumans/Animations/AnimBP/` | 眨眼和注视  |
| `A2D_MH_EyeLook` | `MetaHumans/Animations/AnimBP/` | 眼睛注视方向 |
| `B2D_F_HeadLook` | `MetaHumans/Animations/AnimBP/` | 女性头部注视 |
| `B2D_M_HeadLook` | `MetaHumans/Animations/AnimBP/` | 男性看向头部 |
| `B2D_F_Pointing` | `MetaHumans/Animations/AnimBP/` | 女性指向   |
| `B2D_M_Pointing` | `MetaHumans/Animations/AnimBP/` | 男性指向   |

#### LLM 手势库

每种手势都包含女性（`Anim_F_*`）和男性（`Anim_M_*`）动画序列，以及对应的 Animation Montage（`*_Montage`）。所有路径均位于 `MetaHumans/Animations/Motion/Gestures/`.

| 手势 | 文件夹               | 关键资源（按性别分类）                                                                                                                                                                                         |
| -- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 再见 | `Gestures/Bye/`   | `Anim_F_Bye`, `Anim_F_Bye_Montage` / `Anim_M_Bye`, `Anim_M_Bye_Montage`                                                                                                                             |
| 嗨  | `Gestures/Hi/`    | `Anim_F_Hi`, `Anim_F_Hi_Montage` / `Anim_M_Hi`, `Anim_M_Hi_Montage`                                                                                                                                 |
| 点赞 | `Gestures/Like/`  | `Anim_F_Like`, `Anim_F_Like_Montage` / `Anim_M_Like`, `Anim_M_Like_Montage`                                                                                                                         |
| 否  | `Gestures/No/`    | `Anim_F_No`, `Anim_F_No_Montage` / `Anim_M_No`, `Anim_M_No_Montage`                                                                                                                                 |
| 思考 | `Gestures/Think/` | `Anim_F_Think`, `Anim_F_Think_In`, `Anim_F_Think_Loop`, `Anim_F_Think_Out`, `Anim_F_Think_Montage` /男性对应资源（`Anim_M_Think_*`)                                                                        |
| 眨眼 | `Gestures/Wink/`  | 身体： `Anim_F_Wink_Body`, `Anim_F_Wink_Body_Montage` / `Anim_M_Wink_Body`, `Anim_M_Wink_Body_Montage`。面部： `AnimFace_F_Wink`, `AnimFace_F_Wink_Montage` / `AnimFace_M_Wink`, `AnimFace_M_Wink_Montage` |
| 是  | `Gestures/Yes/`   | `Anim_F_Yes`, `Anim_F_Yes_Montage` / `Anim_M_Yes`, `Anim_M_Yes_Montage`                                                                                                                             |

该插件还随附其他身体动作动画，位于 `MetaHumans/Animations/Motion/Actions/` （Clap、Dance\_Disco、Dance\_Groove、Dance\_GStyle、Jump360），以及位于以下目录的移动资源： `Motion/Idle/`, `Motion/Walk/`, `Motion/Jog/`和 `Motion/Talk/`.

动画接口 `BPI_Convai_Animation` 位于 `Interfaces/BPI_Convai_Animation` 将 Actions 系统与这些资源连接起来。

### 故障排查

#### MetaHuman 在说话时嘴巴不动

**症状：** 音频正常播放，但嘴部没有动画。

**原因：** **Lip Sync Mode** 设置了错误的目标，或者面部和身体动画类不是 Convai MetaHuman 变体。

**解决方法：** 确认 **Lip Sync Mode** 在 `UConvaiFaceSyncComponent` 中设置为 **MetaHuman Blendshapes**。确认 **Anim Class** 在 **Face** 网格体上设置为 `Convai_MetaHuman_FaceAnim` ，并在 **身体** 网格体上设置为 `Convai_MetaHuman_BodyAnim`.

**验证：** 进入运行模式并与角色交谈。打开 **窗口 > 输出日志**，筛选 `ConvaiFaceSync` 或 `ConvaiChatbotComponentLog`，并确认角色说话时没有出现错误。

#### 角色不响应语音或文本

**症状：** 关卡中有 MetaHuman，但它不响应输入。

**原因：** 缺少或错误的 **角色 ID** 、未配置 API 密钥，或者玩家 Pawn 中缺少 `UConvaiPlayerComponent` 。

**解决方法：** 确认 **角色 ID** 与 **Convai 聊天机器人** 组件中的 ID 一致，并且该角色存在于 Convai 控制面板中。确认已设置 API 密钥（请参阅 [配置 API 密钥](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md)）。确认玩家 Pawn 中已添加 `UConvaiPlayerComponent` 。

**验证：** 打开 **窗口 > 输出日志** 并筛选 `ConvaiChatbotComponentLog` 或 `ConvaiConnectionManagerLog`。进入运行模式并尝试对话时，检查是否出现连接或身份验证错误。

### 后续步骤

{% content-ref url="/pages/d29e5c59616e0066f5596223946116f5c08bc90d" %}
[设置 Reallusion（CC）角色](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/set-up-a-reallusion-cc-character.md)
{% endcontent-ref %}

{% content-ref url="/pages/9b983ed32e78e3fecceef1f1ca84663abe05edca" %}
[配置对话输入](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-conversation-input.md)
{% endcontent-ref %}

{% content-ref url="/pages/1f909841a8dc37e6adc6461224d8b1968155a87c" %}
[验证你的设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/validate-your-setup.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-unreal-engine-plugin/getting-started/set-up-a-metahuman-character.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.
