> 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 插件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md) 和 [配置你的 API 密钥](/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 进行管理。导入体验类似——使用 **窗口 > Fab** 或 **Fab** 工具栏中的按钮打开面板并导航到 MetaHuman 部分。请参阅 [Unreal Engine MetaHuman 文档](https://dev.epicgames.com/documentation/en-us/metahuman/importing-metahumans-to-unreal-engine-projects) ，了解适用于你当前引擎版本的导入路径。导入后，Convai 的设置步骤无论 MetaHuman 如何导入都相同。
{% endhint %}

{% stepper %}
{% step %}

#### 打开 Quixel Bridge 或 Fab

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

{% step %}

#### 将 MetaHuman 添加到你的项目中

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

{% step %}

#### 打开 MetaHuman Blueprint

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

### 添加 Convai 组件

{% stepper %}
{% step %}

#### 添加 Convai Chatbot 组件

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

在 **详情** 组件的面板中，将你从 **角色 ID** Convai 控制面板中的 **角色 ID** 字段，位于 **Convai** 类别。
{% endstep %}

{% step %}

#### 添加 Convai Face Sync 组件

点击 **添加** 再次在 **组件** 面板。搜索 `Convai Face Sync` 的输出执行引脚拖出并添加 `UConvaiFaceSyncComponent`.

在 **详情** 面板中，确认 **口型同步模式** 被设置为 **MetaHuman Blendshapes**。这是默认值，也是 MetaHuman 角色的正确设置。
{% endstep %}
{% endstepper %}

### 分配 Convai 动画蓝图

MetaHuman 角色对身体和面部分别使用独立的动画蓝图。Convai 插件在 `MetaHumans/Animations/` (`ConvAI > MetaHumans > Animations` 中提供了两个资源（在 Content Browser 中）用于将口型同步数据接入 MetaHuman 骨骼。

{% stepper %}
{% step %}

#### 设置身体动画类

在 Blueprint 编辑器中，选择 **身体** 骨骼网格体组件。于 **详情** 面板，找到 **Anim Class** 字段中，在 **动画**下。将其设置为 `Convai_MetaHuman_BodyAnim`.
{% endstep %}

{% step %}

#### 设置面部动画类

选择 **面部** 骨骼网格体组件。于 **详情** 面板，找到 **Anim Class** 字段。将其设置为 `Convai_MetaHuman_FaceAnim`.
{% endstep %}

{% step %}

#### 编译并保存

点击 **编译** ，然后 **保存** 在 Blueprint 编辑器工具栏中。
{% endstep %}
{% endstepper %}

### 将 MetaHuman 添加到关卡

将 MetaHuman Blueprint 从 **内容浏览器** 拖到关卡视口中，并将其放置到你想要的位置。

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

如果你还没有这么做，请打开你的玩家 Pawn Blueprint 并添加 `UConvaiPlayerComponent`。请参阅 [添加你的第一个 Convai 角色](/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 的嘴巴会与角色的语音回复同步移动，并且在对话过程中面部表情会动态变化。如果角色没有响应，请参阅 [验证你的设置](/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` 激活，无需除上面的口型同步动画蓝图设置之外的额外 Blueprint 连接。

#### 口型同步动画蓝图

| 资源                          | Content 路径               | 作用                                          |
| --------------------------- | ------------------------ | ------------------------------------------- |
| `Convai_MetaHuman_BodyAnim` | `MetaHumans/Animations/` | 身体动画——分配给 **身体** 骨骼网格体 **Anim Class**.      |
| `Convai_MetaHuman_FaceAnim` | `MetaHumans/Animations/` | 面部动画和口型同步——分配给 **面部** 骨骼网格体 **Anim Class**. |

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

| 资源               | 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 在说话时嘴巴没有动

**症状：** 有声音播放，但嘴巴没有进行动画。

**原因：** **口型同步模式** 设置到了错误的目标，或者面部和身体动画类不是 Convai MetaHuman 变体。

**修复：** 确认 **口型同步模式** 位于 `UConvaiFaceSyncComponent` 是 **MetaHuman Blendshapes**请确认 **Anim Class** 在 **面部** 网格体是 `Convai_MetaHuman_FaceAnim` 并且在 **身体** 网格体是 `Convai_MetaHuman_BodyAnim`.

**验证：** 进入播放模式并对角色说话。打开 **Window > Output Log**，按 `ConvaiFaceSync` 或 `ConvaiChatbotComponentLog`，并确认角色说话时没有出现错误。

#### 角色无法响应语音或文本

**症状：** MetaHuman 已在关卡中，但对输入没有反应。

**原因：** 该 **角色 ID** 缺失或不正确，API 密钥未配置，或 `UConvaiPlayerComponent` 未添加到玩家 Pawn 中。

**修复：** 请确认 **角色 ID** 在 **Convai Chatbot** 组件是否与你 Convai 控制面板中的某个角色匹配。确认你的 API 密钥已设置（参见 [配置你的 API 密钥](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md)）。确认玩家 Pawn 已添加 `UConvaiPlayerComponent` 。

**验证：** 打开 **Window > Output Log** 并按 `ConvaiChatbotComponentLog` 或 `ConvaiConnectionManagerLog`过滤。进入播放模式并尝试对话时，查找连接或身份验证错误。

### 下一步

{% content-ref url="/pages/d29e5c59616e0066f5596223946116f5c08bc90d" %}
[设置 Reallusion（CC）角色](/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" %}
[配置对话输入](/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" %}
[验证你的设置](/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.