> 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 角色

通过添加 Chatbot 和 Player 组件、设置 Character ID，并在播放模式下测试，在 Unreal Engine 中构建一个会说话的 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 Face Sync`，并将其添加。选择该组件并设置 **Lip Sync Mode** 以匹配你的绑定：

* **MetaHuman 混合变形** — 适用于 MetaHuman 和 Reallusion CC5 角色。
* **CC4 扩展混合变形** — 适用于 Reallusion CC4 角色。
* **基于音素口型** — 适用于使用 OVR viseme 的自定义绑定。

如果你的角色没有面部骨骼绑定，可以跳过这一步。
{% 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`。将其拖入关卡，并将 `BP_SampleGameMode` （同一文件夹）作为 **游戏模式覆盖** 在世界设置中。它已经预置了 `BP_ConvaiPlayerComponent` 以及一个预先配置好的聊天小部件。此设置适合原型开发——用于正式项目时，请将 `BP Convai Player Component` 按照上文所述直接添加到你自己的玩家 Pawn 蓝图中。
{% endhint %}

### 测试对话

{% stepper %}
{% step %}

#### 进入播放模式

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

{% step %}

#### 与角色对话

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

若要改用免提（VAD）模式，请打开玩家 Pawn 蓝图，选择 **Convai Player** 组件（`BP_ConvaiPlayerComponent`），展开 **Convai** 该面板中的类别 **Details** 面板，并禁用 **启用按键通话** (`EnablePushToTalk` ——这是蓝图包装器上的一个变量，不是底层的 C++ 组件）。或者调用 `UpdateVadBP(true)` 在蓝图中。参见 [配置对话输入](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-conversation-input.md) 以了解完整的 VAD 调整选项。
{% 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 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/add-your-first-convai-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.