> 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 插件](/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).
* 你已从控制台获得一个 Convai 角色 ID。

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

{% stepper %}
{% step %}

#### 加载你的角色

打开 Character Creator 5。导航到 **Project > Templates > CC Project** 并选择你想使用的角色。或者，也可以加载现有的 CC 项目。
{% endstep %}

{% step %}

#### 添加待机动画

点击 **动画** 并找到一个待机动画。一个轻微的待机动作（例如 `idle03`）效果很好。将其拖到头像上以应用。确认动画在头像上播放。
{% endstep %}

{% step %}

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

右键单击动画面板中的动画并选择 **查找文件**。这会在你的文件系统中打开该动画的目录。右键单击该动画文件并复制其路径。

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

{% step %}

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

可选地，添加一个站立并说话的动画，不包含口型同步——插件会单独处理口型同步。对该说话动画重复“查找文件”和“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** 已勾选，然后点击图标以 **Load 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` 和 `插件` 文件夹。
{% endstep %}

{% step %}

#### 粘贴到你的 Unreal 项目中

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

{% step %}

#### 启动项目

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

### 将 Reallusion 头像导入 Unreal Engine

{% stepper %}
{% step %}

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

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

{% step %}

#### 配置导入设置

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

* 启用 **导入动画**.
* 将 **自定义采样率** 为 **30 fps** （某些动画导入时的速率非常高，这可能导致播放问题）。
* 展开 **高级** 部分并勾选 **导入形态目标**.
* 点击 **全部导入**.

在导入期间出现的任何警告弹窗都可忽略。
{% endstep %}

{% step %}

#### 验证导入

在编辑器中打开导入的骨骼网格。确认网格没有变形，并且 morph target 出现在 morph target 列表中。双击一个动画资源并确认其与匹配的首尾帧平滑播放。
{% endstep %}
{% endstepper %}

### 在 Unreal Engine 中设置 Convai

{% stepper %}
{% step %}

#### 创建角色蓝图

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

{% step %}

#### 添加 Skeletal Mesh 组件

打开蓝图。在 **组件** 面板中，点击 **添加** 中并添加一个 **Skeletal Mesh** 组件。在 **Details** 面板中，将 **Skeletal Mesh** 中将其设置为你导入的 Reallusion 头像。
{% endstep %}

{% step %}

#### 添加 Convai Chatbot 组件

点击 **添加** ，位于 **组件** 面板中搜索 `BP Convai ChatBot Component` 并选择它。在 **Details** 面板中，将你的 **角色 ID** 中的 API 密钥粘贴到 **角色 ID** 字段。
{% endstep %}

{% step %}

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

将角色蓝图从 **内容浏览器** 拖到关卡视口中并放置好。
{% endstep %}
{% endstepper %}

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

要在 Play 模式下找到 player pawn：按 **Shift+F1** 释放鼠标，单击 **Detach** 工具栏中的，然后单击视口中的玩家角色并单击 **编辑蓝图**.

### 测试对话

进入 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 %}

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

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

{% step %}

#### 配置动画蓝图

重启后，找到 `Convai_Reallusion_AnimBP` ，位于 **内容浏览器** 并双击它。收到提示时，选择你 Reallusion 头像的骨骼。

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

| State             | 动画角色         |
| ----------------- | ------------ |
| `BaseAnimation`   | 待机动画——默认静止姿势 |
| `Talk Animation`  | 角色说话时的身体动画   |
| `Focus Animation` | 角色在倾听或专注时的动画 |
| `Walk Animation`  | 角色移动时的移动动画   |

* 如果拖放没有连接，请在图表中右键单击，输入 `播放`，然后按名称手动选择该动画。
* 将状态之间的过渡混合设置为在适当时使用待机动画。
* 确保所有循环动画都设置为 **循环**.

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

{% step %}

#### 将动画蓝图分配给角色

打开角色蓝图。选择 **Skeletal Mesh** 组件。在 **Details** 面板，在 **动画**，设置 **动画类** 为 `Convai_Reallusion_AnimBP`.

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

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

{% stepper %}
{% step %}

#### 添加 Convai Face Sync 组件

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

{% step %}

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

选中 **Convai Face Sync** 组件。在 **Details** 面板中，设置 **口型同步模式**:

* **MetaHuman 混合变形** ——适用于 CC5 角色（使用与 MetaHuman 兼容的骨架）。
* **CC4 扩展混合变形** ——适用于 CC4 角色。
  {% endstep %}

{% step %}

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

点击 **编译** 和 **保存**。进入 Play 模式并与角色对话。
{% endstep %}
{% endstepper %}

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

### 故障排除

#### 没有面部动画

**症状：** 尽管音频播放正常，但角色在说话时嘴巴不动。

**原因：** `UConvaiFaceSyncComponent` 缺失， **口型同步模式** 被设置为错误的 blendshape 目标，或者导入 FBX 时未启用 **导入形态目标** 。

**修复：**

* 确认 **Convai Face Sync** 组件存在于角色蓝图中。
* 确认 **口型同步模式** 设置为 **MetaHuman 混合变形** 适用于 CC5 角色，或者 **CC4 扩展混合变形** 适用于 CC4 角色。
* 如果问题仍然存在，请在重新导入 FBX 时 **导入形态目标** 在 **高级** FBX Import Options 对话框的

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

#### 身体动画不播放

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

**原因：** **动画类** Skeletal Mesh 上未设置为 Reallusion 动画蓝图、动画未设置为循环，或者首尾帧不匹配，从而导致动画跳切。

**修复：**

* 确认 **动画类** Skeletal Mesh 组件上的 `Convai_Reallusion_AnimBP`.
* 打开 `Convai_Reallusion_AnimBP` 设置为`BaseAnimation`, `Talk Animation`, `Focus Animation`, `Walk Animation`并确认每个状态（
* 确认每个循环动画资源都设置为 **循环**.
* 确认每个动画的首帧和尾帧完全相同。

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

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

**症状：** Reallusion 角色在关卡中，但对输入没有反应。

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

**修复：** 验证 **角色 ID** 在 **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`，并在进入 Play 模式时查找身份验证或连接错误。

### 下一步

{% content-ref url="/pages/ddab80eff30a95a57bb3cec04bc4566233e30263" %}
[配置麦克风](/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" %}
[配置对话输入](/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-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.