> 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 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 及更高版本**，MetaHumans 通过 **Fab** 插件而不是 Quixel Bridge 管理。导入体验类似——使用 **窗口 > 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 菜单栏中选择 **窗口 > Quixel Bridge** （UE 5.3 及更早版本）或 **窗口 > 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 Chatbot 组件

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

在 **详细信息** 该组件的面板，粘贴你的 **Character ID** 从 Convai 控制面板获取的 **Character ID** 到以下 **Convai** 类别下的字段中。
{% endstep %}

{% step %}

#### 添加 Convai Face Sync 组件

点击 **Add** 再次在 **Components** 面板。搜索 `Convai 面部同步` 的输出执行引脚拖出并添加 `UConvaiFaceSyncComponent`.

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

### 分配 Convai 动画蓝图

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

{% stepper %}
{% step %}

#### 设置身体动画类

在蓝图编辑器中，选择 **Body** 骨骼网格组件。在 **详细信息** 面板中，找到 **动画类** 下的 **动画**字段。将其设置为 `Convai_MetaHuman_BodyAnim`.
{% endstep %}

{% step %}

#### 设置面部动画类

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

{% step %}

#### 编译并保存

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

### 将 MetaHuman 添加到关卡中

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

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

如果你还没有这样做，请打开你的玩家 Pawn 蓝图并添加 `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` 激活，无需除上述口型同步动画蓝图设置之外的额外蓝图连接。

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

| 资源                          | Content 路径               | 用途                                  |
| --------------------------- | ------------------------ | ----------------------------------- |
| `Convai_MetaHuman_BodyAnim` | `MetaHumans/Animations/` | 身体动画——分配到 **Body** 骨骼网格 **动画类**.    |
| `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_*`）动画序列，以及对应的动画 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**确认 **动画类** 在 **面部** 网格是 `Convai_MetaHuman_FaceAnim` 且在 **Body** 网格是 `Convai_MetaHuman_BodyAnim`.

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

#### 角色对语音或文本没有响应

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

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

**修复：** 请验证 **Character ID** 在 **Convai 聊天机器人** 组件与 Convai 控制面板中的一个角色匹配。确认你的 API 密钥已设置（参见 [配置你的 API 密钥](/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）角色](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.