> 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-reallusion-cc-character.md).

# 设置 Reallusion（CC）角色

导出 Reallusion CC5 头像，将其导入 Unreal Engine，配置 Convai 组件，并添加 Reallusion 动画 Blueprint 以实现唇形同步。

本指南介绍将 Reallusion Character Creator 5 (CC5) 虚拟形象连接到 Convai Unreal Engine 插件的完整流程。

{% embed url="<https://www.youtube.com/watch?v=nyPNP-S92QI>" %}
Reallusion 角色设置指南
{% endembed %}

### 前提条件

* 已安装 Reallusion Character Creator 5。
* 已安装 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).
* 你已从控制面板获取 Convai 角色 ID。

### 在 Character Creator 5 中准备动画

{% stepper %}
{% step %}

#### 加载角色

打开 Character Creator 5。导航至 **Project > Templates > CC Project** 然后选择要使用的角色。或者，加载现有的 CC 项目。
{% endstep %}

{% step %}

#### 添加待机动画

点击 **Animation** 并找到待机动画。较为轻柔的待机动画（例如 `idle03`）效果不错。将其拖到虚拟形象上以应用动画。确认虚拟形象能够播放该动画。
{% endstep %}

{% step %}

#### 将动画添加到 Perform List

在动画面板中右键点击该动画，然后选择 **Find File**。这会在文件系统中打开动画所在目录。右键点击动画文件并复制其路径。

前往 **Motion > Perform > Perform List Editor**。点击 **Add**，粘贴路径，选择动画，然后点击 **Open**.
{% endstep %}

{% step %}

#### 添加说话动画（可选）

你也可以添加站立说话动画，但不要包含口型同步——插件会单独处理口型同步。对说话动画重复执行 Find File 和 Perform List 中的步骤。选择首帧与末帧相同的动画，这样循环播放时就不会出现明显的跳切。
{% endstep %}
{% endstepper %}

### 从 Character Creator 5 导出虚拟形象

{% stepper %}
{% step %}

#### 开始导出 FBX

在 Character Creator 5 中，前往 **File > Export > FBX > Clothed Character (Closed Character)**.
{% endstep %}

{% step %}

#### 配置导出设置

在导出对话框中：

* 将 **Target Tool Preset** 设置为 **Unreal (UE5)**.
* 将 **FBX Option** 设置为 **Mesh and Motion**.
* 如果需要更高分辨率的纹理，请调高 **Max Texture Size** 。
* 确保 **Custom** 已勾选后，点击图标以 **加载 Perform** 并选择动画。
* 勾选 **删除隐藏面**.
  {% endstep %}

{% step %}

#### 导出文件

点击 **导出**。输入文件名，选择目标文件夹，然后点击 **保存**。导出需要几分钟。
{% endstep %}
{% endstepper %}

### 为 Unreal Engine 安装 Reallusion CC Auto Setup

CC Auto Setup 是由 Reallusion 提供的第三方工具，不属于 Convai 插件。它会为导入 Unreal Engine 的 Reallusion 角色设置正确的材质、着色器和骨架。

{% stepper %}
{% step %}

#### 下载并安装 CC Auto Setup

从以下页面下载 CC Auto Setup： [Reallusion CC Auto Setup for Unreal Engine](https://www.reallusion.com/auto-setup/unreal-engine/default.html) 。双击安装程序，接受许可协议，然后点击 **下一步**。请记下目标文件夹路径，下一步将会用到。
{% endstep %}

{% step %}

#### 复制 Content 和 Plugins 文件夹

安装完成后，打开目标文件夹。进入与 Unreal Engine 版本对应的子文件夹。复制该子文件夹中的 `Content` 和 `Plugins` 文件夹。
{% endstep %}

{% step %}

#### 粘贴到 Unreal 项目中

打开 Unreal 项目的根目录。将复制的 `Content` 和 `Plugins` 文件夹粘贴到项目根目录，并与已有文件夹合并。
{% endstep %}

{% step %}

#### 启动项目

在 Unreal Engine 中打开项目。现在即可使用 Auto Setup 内容和插件。
{% endstep %}
{% endstepper %}

### 将 Reallusion 虚拟形象导入 Unreal Engine

{% stepper %}
{% step %}

#### 创建文件夹并导入 FBX

在 **内容浏览器**中为角色新建一个文件夹。将导出的 FBX 文件从文件系统拖入此文件夹。
{% endstep %}

{% step %}

#### 配置导入设置

在 **FBX 导入选项** 对话框中：

* 启用 **导入动画**.
* 将 **自定义采样率** 设置为 **30 fps** （有些动画的导入帧率非常高，可能会导致播放问题）。
* 展开 **高级** 部分并检查 **导入变形目标**.
* 点击 **全部导入**.

关闭导入过程中出现的所有警告弹窗。
{% endstep %}

{% step %}

#### 验证导入结果

在编辑器中打开导入的骨骼网格体。确认网格体没有变形，并且变形目标显示在变形目标列表中。双击动画资源，确认动画播放流畅，且首帧与末帧一致。
{% endstep %}
{% endstepper %}

### 在 Unreal Engine 中设置 Convai

{% stepper %}
{% step %}

#### 创建角色蓝图

在角色的 **内容浏览器** 文件夹中右键单击，然后选择 **蓝图类 > Actor**。为蓝图命名（例如， `BP_MyReallusionCharacter`).
{% endstep %}

{% step %}

#### 添加骨骼网格体组件

打开蓝图。在 **组件** 面板中，点击 **添加** 并添加一个 **骨骼网格体** 组件。在 **细节** 面板中，将 **骨骼网格体** 设置为导入的 Reallusion 头像。
{% endstep %}

{% step %}

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

点击 **添加** （位于 **组件** 面板中）。搜索 `BP Convai ChatBot Component` 并选择它。在 **细节** 面板中，将 Convai 控制面板中的 **角色 ID** 粘贴到 **角色 ID** 字段中。
{% endstep %}

{% step %}

#### 将角色放置到关卡中

将角色蓝图从 **内容浏览器** 拖入关卡视口并调整其位置。
{% endstep %}
{% endstepper %}

### 将 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).

要在 Play 模式下找到玩家 Pawn，请按 **Shift+F1** 要释放鼠标，请点击 **分离** 在工具栏中，然后点击视口中的玩家角色，再点击 **编辑蓝图**.

### 测试对话

进入 Play 模式，并使用按住说话（默认： **T**）或聊天小组件与角色交谈。此阶段只能预期获得语音和文本回复及音频播放——身体动画和口型同步需要完成下文的动画蓝图和 Face Sync 步骤。

### 添加 Reallusion 动画蓝图

Reallusion 角色需要使用 Convai Reallusion 动画蓝图（`Convai_Reallusion_AnimBP`）来驱动对话期间的待机、说话、专注和行走状态。

{% stepper %}
{% step %}

#### 下载动画蓝图

从 Convai Google Drive 文件夹下载 Reallusion 动画蓝图：

[Convai Reallusion 动画蓝图（Google Drive）](https://drive.google.com/drive/folders/1k3072DH3zJXk2xTg-CJ_najnm0pyvZJS)

{% hint style="info" %}
此 Google Drive 文件夹是 Reallusion 动画蓝图的官方分发渠道。如果链接无法访问，请在 [Convai 开发者论坛](https://forum.convai.com) 发帖申请，团队会直接提供该资源。
{% endhint %}

下载 zip 文件并解压，然后找到动画蓝图资源文件。
{% endstep %}

{% step %}

#### 将资源复制到项目中

将动画蓝图资源复制到磁盘上 Unreal 项目目录中的 `Content` 文件夹——直接复制到文件系统中，而不是通过编辑器复制。然后重启 Unreal Editor，使其检测到新资源。
{% endstep %}

{% step %}

#### 配置动画蓝图

重启后，在 `Convai_Reallusion_AnimBP` 内容浏览器 **中找到它并双击。出现提示时，选择 Reallusion 虚拟形象的骨架。** 并双击。出现提示时，选择 Reallusion 虚拟形象的骨架。

打开 **动画图表** 中的 `Convai_Reallusion_AnimBP`。在 **内容抽屉**中，导航到角色的动作文件夹，找到从 Character Creator 5 导出的动画资源。将每个动画拖放到图表中，并连接到对应状态：

| 状态                | 动画用途         |
| ----------------- | ------------ |
| `BaseAnimation`   | 待机动画——默认静止姿势 |
| `Talk Animation`  | 角色说话时的身体动画   |
| `Focus Animation` | 角色聆听或专注时的动画  |
| `Walk Animation`  | 角色移动时的行走动画   |

* 如果拖放无法建立连接，请在图表中右键点击，输入 `Play`，然后按名称手动选择动画。
* 设置状态之间的过渡混合，以便在适当情况下使用待机动画。
* 确保所有循环动画均设置为 **循环**.

点击 **编译** 并 **保存**.
{% endstep %}

{% step %}

#### 将动画蓝图指定给角色

打开角色蓝图。选择 **骨骼网格体** 组件。在 **详细信息** 面板的 **动画**下，将 **动画类** 设置为 `Convai_Reallusion_AnimBP`.

编译并保存蓝图。
{% endstep %}
{% endstepper %}

### 使用 Convai Face Sync 添加面部动画

{% stepper %}
{% step %}

#### 添加 Convai Face Sync 组件

打开角色蓝图。在 **组件** 面板中，点击 **添加** 并搜索 `Convai Face Sync`。添加 `UConvaiFaceSyncComponent`.
{% endstep %}

{% step %}

#### 设置口型同步模式

选择 **Convai Face Sync** 组件。在 **详细信息** 面板中，将 **口型同步模式**:

* **MetaHuman Blendshapes** —适用于 CC5 角色（使用兼容 MetaHuman 的绑定）。
* **CC4 Extended Blendshapes** —适用于 CC4 角色。
  {% endstep %}

{% step %}

#### 编译、保存并测试

点击 **编译** 并 **保存**。进入游戏模式并与角色交谈。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
设置完成后，Reallusion 角色的嘴唇和面部表情会与其语音回复同步动画。
{% endhint %}

### 故障排查

#### 没有面部动画

**症状：** 音频正常播放，但角色说话时嘴巴没有动作。

**原因：** `UConvaiFaceSyncComponent` 缺失， **唇形同步模式** 设置了错误的混合变形目标，或者导入 FBX 时未启用 **导入变形目标** 。

**修复方法：**

* 确认角色蓝图上已添加 **Convai 面部同步** 组件。
* 确认 **唇形同步模式** 设置为 **MetaHuman 混合变形** （适用于 CC5 角色），或 **CC4 扩展混合变形** （适用于 CC4 角色）。
* 如果问题仍然存在，请重新导入 FBX，并在 FBX 导入选项对话框的 **导入变形目标** 下的 **高级** 部分勾选该选项。

**验证：** 进入播放模式并对角色说话。角色的嘴唇应与语音回复同步动起来。如果没有，请打开 **窗口 > 输出日志**，筛选 `ConvaiFaceSync`，并检查语音播放期间是否出现错误。

#### 身体动画未播放

**症状：** 角色僵立不动——对话期间既不播放待机动画，也不播放说话动画。

**原因：** **骨骼网格体上的动画类** 未设置为 Reallusion 动画蓝图、动画未设置为循环播放，或者首帧与末帧不匹配，导致动画出现跳变。

**修复方法：**

* 确认 **动画类** 已在骨骼网格体组件上设置为 `Convai_Reallusion_AnimBP`.
* 打开 `Convai_Reallusion_AnimBP` 并确认每个状态（`BaseAnimation`, `Talk Animation`, `Focus Animation`, `Walk Animation`）都已分配正确的动画。
* 确认每个设置为循环播放的动画资源都已设为 **循环**.
* 确认每个动画的首帧和末帧完全一致。

**验证：** 进入播放模式，确认角色会播放待机动画，并在回复时切换到说话动画。检查 **窗口 > 输出日志** 如果状态没有变化，请检查动画或 Convai 错误。

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

**症状：** Reallusion 角色已加载到关卡中，但不会响应输入。

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

**解决方法：** 请检查 **角色 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/ddab80eff30a95a57bb3cec04bc4566233e30263" %}
[配置麦克风](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-the-microphone.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-reallusion-cc-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.
