> 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/add-your-first-convai-character.md).

# 添加你的第一个 Convai 角色

我们将把一个 Convai 角色添加到现有的 Unreal Engine 项目中，并与它进行实时语音对话。到最后，你将拥有一个能够倾听、生成回复，并使用你的麦克风回话的角色。

{% embed url="<https://youtu.be/n-UG3nmMeZQ>" %}
添加你的第一个 Convai 角色操作指南
{% endembed %}

### 开始之前

* Convai 插件已安装并启用（参见 [安装 Convai 插件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md)).
* 你的 API 密钥已配置（参见 [配置您的 API 密钥](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md)).
* 你在 Convai 控制台中已经有一个现有角色，或者你会在本教程中创建一个。
* 你的项目已经有一个 NPC Actor 蓝图和一个玩家 Pawn 蓝图。

### 从 Convai 控制台获取角色 ID

{% stepper %}
{% step %}

#### 打开 Convai 控制台

在浏览器中，前往 [convai.com](https://convai.com) 并登录。
{% endstep %}

{% step %}

#### 选择或创建一个角色

从你的角色列表中选择一个现有角色，或者创建一个新的。你可以在控制台中管理角色的资料和行为。无需更改 Unreal Engine 中的任何内容，就能更新控制台配置。
{% endstep %}

{% step %}

#### 复制角色 ID

在角色详情页上，复制 **角色 ID** 字符串。你将在下一节中将其粘贴到编辑器里。
{% endstep %}
{% endstepper %}

### 将 Convai Chatbot 组件添加到你的 NPC

{% stepper %}
{% step %}

#### 打开角色蓝图

在 **大纲视图**，点击你的 NPC Actor。在 **Details** 面板中，点击 **编辑蓝图** 以打开蓝图编辑器。你也可以直接从 **内容浏览器**.
{% endstep %}

{% step %}

#### 添加 Convai Chatbot 组件

在 **组件** 面板中，点击 **添加**。搜索 `BP Convai ChatBot Component` 并选择它。这样会添加经过蓝图封装的聊天机器人组件，该组件已预先连接好按住说话输入和聊天 UI 小部件。
{% endstep %}

{% step %}

#### 设置角色 ID

选择 **Convai 聊天机器人** 组件在 **组件** 面板中。在 **Details** 面板中，找到 **角色 ID** 字段，位于 **Convai** 类别下，并将你的角色 ID 粘贴进去。
{% endstep %}

{% step %}

#### 添加 Convai Face Sync 组件（可选）

如果你的角色有面部骨骼绑定，并且你想要唇形同步，点击 **添加** 再次，搜索 `Convai 面部同步`，并添加它。选择该组件并设置 **唇形同步模式** 以匹配你的骨架：

* **MetaHuman Blendshapes** — 适用于 MetaHuman 和 Reallusion CC5 角色。
* **CC4 Extended Blendshapes** — 适用于 Reallusion CC4 角色。
* **基于 Viseme** — 适用于使用 OVR visemes 的自定义骨架。

如果你的角色没有面部骨骼绑定，请跳过这一步。
{% endstep %}

{% step %}

#### 编译并保存蓝图

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

{% step %}

#### 设置起始表情（可选）

要让角色以特定表情开始，请打开 **事件图表**，添加一个 **Event BeginPlay** 节点，获取对 **Convai 聊天机器人** 组件的引用，并调用 **强制设置情绪**。将 **基本情绪** 到 `开心`, **强度** 到 `基本`，以及 **重置其他情绪** 到 `true`。随着对话推进，情绪会动态更新。参见 [情绪示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/emotion/emotion-examples.md).
{% endstep %}
{% endstepper %}

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

{% stepper %}
{% step %}

#### 找到玩家 Pawn 蓝图

最快的方法是通过 **窗口 > 世界设置**。展开 **游戏模式 > 选定的游戏模式** ，并记下 **默认 Pawn 类**。点击其旁边的浏览图标，在 **内容浏览器**中定位该蓝图，然后打开它。

或者，从播放模式中：按 **Shift+F1** 释放鼠标，点击 **分离** 在工具栏中，点击视口中的玩家角色，然后点击 **编辑蓝图**.
{% endstep %}

{% step %}

#### 添加 Convai Player 组件

在玩家 Pawn 的蓝图编辑器中，点击 **添加** 在 **组件** 面板。搜索 `BP Convai Player Component` 并选择它。这样会添加经过蓝图封装的玩家组件，其中已预先配置好按住说话输入和聊天 UI 小部件。
{% endstep %}

{% step %}

#### 编译并保存

单击 **编译** 然后 **保存**.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
如果你没有现成的玩家 Pawn，插件自带一个现成的： `BP_ConvaiSamplePlayer` 位于 `ConvAI > ConvaiConveniencePack > Sample`。将它拖入关卡，并在 World Settings 中将 `BP_SampleGameMode` （同一文件夹）设置为 **GameMode 覆盖** 。它已经预先配置了 `BP_ConvaiPlayerComponent` 和一个聊天小部件。此设置适合原型开发——用于生产环境时，请如上所述将 `BP Convai Player Component` 直接添加到你自己的玩家 Pawn 蓝图中。
{% endhint %}

### 测试对话

{% stepper %}
{% step %}

#### 进入播放模式

按 **播放** 在 Unreal Editor 工具栏中。视口中会出现一个聊天小部件。
{% endstep %}

{% step %}

#### 与角色对话

按住说话键（默认： **T**），对着麦克风说话，然后松开按键。角色会处理你的语音，生成回复，并说出来。

如果要改用免手持（VAD）模式，请打开玩家 Pawn 蓝图，选择 **Convai 玩家** 组件（`BP_ConvaiPlayerComponent`），展开 **Convai** 类别中的 **Details** 面板，并禁用 **启用按住说话** (`EnablePushToTalk` ——这是蓝图包装器上的变量，不是原始 C++ 组件上的变量）。或者，从 Blueprint 中调用 `UpdateVadBP(true)` 。有关完整的 VAD 调优选项，请参见 [配置对话输入](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-conversation-input.md) 。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
当设置生效时，角色会说出可听见的回复，聊天小部件会显示对话记录。如果角色没有响应，请参见 [验证你的设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/validate-your-setup.md) 以查看常见故障点的检查清单。
{% endhint %}

### 下一步

{% 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 %}

{% content-ref url="/pages/f0a9565e073a000fe0ed7df2961660e00793150b" %}
[设置 MetaHuman 角色](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/set-up-a-metahuman-character.md)
{% endcontent-ref %}

{% 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/98b41781157f6eec98a195dad1b57f66765cf380" %}
[场景组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/scene-components-reference.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/add-your-first-convai-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.