> 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 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。导航到 **项目 > 模板 > CC 项目** 并选择你要使用的角色。或者，加载现有的 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 中，转到 **文件 > 导出 > FBX > 穿衣角色（封闭角色）**.
{% endstep %}

{% step %}

#### 配置导出设置

在导出对话框中：

* 设置 **目标工具预设** 到 **Unreal（UE5）**.
* 设置 **FBX 选项** 到 **网格和运动**.
* 提高 **最大纹理尺寸** ，如果你需要更高分辨率的纹理。
* 确保 **自定义** 已勾选，然后单击图标以 **加载表演** 并选择你的动画。
* 检查 **删除隐藏面**.
  {% 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： [适用于 Unreal Engine 的 Reallusion CC Auto Setup](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 帧/秒** （某些动画以非常高的速率导入，这可能导致播放问题）。
* 展开 **高级** 部分并勾选 **导入变形目标**.
* 单击 **全部导入**.

忽略导入过程中出现的任何警告弹窗。
{% endstep %}

{% step %}

#### 验证导入

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

### 在 Unreal Engine 中设置 Convai

{% stepper %}
{% step %}

#### 创建角色 Blueprint

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

{% step %}

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

打开蓝图。在 **组件** 面板中，点击 **添加** 并添加一个 **骨骼网格** 组件。在 **Details** 面板中，将 **骨骼网格** 中，将其设置为你导入的 Reallusion 角色。
{% endstep %}

{% step %}

#### 添加 Convai Chatbot 组件

单击 **添加** 在 **组件** 面板中。搜索 `BP Convai ChatBot Component` 并选择它。在 **Details** 面板中，粘贴你的 **角色 ID** 来自 Convai 控制面板的 **角色 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).

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

### 测试对话

进入播放模式，并使用按键通话（默认： **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 角色骨骼。

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

| State           | 动画角色         |
| --------------- | ------------ |
| `BaseAnimation` | 待机动画——默认休息姿势 |
| `说话动画`          | 角色说话时的身体动画   |
| `专注动画`          | 角色在倾听或专注时的动画 |
| `行走动画`          | 角色移动时的运动动画   |

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

单击 **编译** 是位于 **保存**.
{% endstep %}

{% step %}

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

打开角色蓝图。选择 **骨骼网格** 组件。在 **Details** 面板，在 **动画**中，设置 **Anim Class** 到 `Convai_Reallusion_AnimBP`.

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

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

{% stepper %}
{% step %}

#### 添加 Convai Face Sync 组件

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

{% step %}

#### 设置唇同步模式

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

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

{% step %}

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

单击 **编译** 是位于 **保存**。进入播放模式并与角色说话。
{% endstep %}
{% endstepper %}

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

### 故障排查

#### 没有面部动画

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

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

**修复：**

* 确认 **Convai 面部同步** 组件存在于角色蓝图中。
* 确认 **口型同步模式** 被设置为 **MetaHuman Blendshapes** 对于 CC5 角色，或 **CC4 Extended Blendshapes** 对于 CC4 角色。
* 如果问题仍然存在，请重新导入 FBX，并将 **导入变形目标** 在 **高级** 部分下勾选。

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

#### 身体动画不播放

**症状：** 角色僵立不动——对话过程中既没有待机动画也没有说话动画播放。

**原因：** **Anim Class** 如果骨骼网格上的动画未设置为 Reallusion 动画蓝图、动画未设置为循环，或者首尾帧不匹配，都会导致动画跳变。

**修复：**

* 确认 **Anim Class** 骨骼网格组件上的设置为 `Convai_Reallusion_AnimBP`.
* 打开 `Convai_Reallusion_AnimBP` 并确认每个状态（`BaseAnimation`, `说话动画`, `专注动画`, `行走动画`）都分配了正确的动画。
* 确认每个循环动画资源都设置为 **循环**.
* 确认每个动画的首尾帧相同。

**验证：** 进入播放模式并确认角色会播放待机动画，并在回应时切换到说话动画。检查 **窗口 > 输出日志** 是否有动画或 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`，并在进入播放模式时查找身份验证或连接错误。

### 下一步

{% 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 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-reallusion-cc-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.