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

我们将在现有的 Unreal Engine 项目中添加一个 Convai 角色，并与它进行实时语音对话。完成后，你将拥有一个能够聆听、生成回复并通过麦克风与你交谈的角色。

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

### 开始之前

* 已安装并启用 Convai 插件（请参阅 [安装 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 密钥（请参阅 [配置 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 控制面板中创建角色，或者将在本教程中创建一个角色。
* 你的项目中已包含 NPC Actor Blueprint 和玩家 Pawn Blueprint。

### 从 Convai 控制面板获取角色 ID

{% stepper %}
{% step %}

#### 打开 Convai 控制面板

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

{% step %}

#### 选择或创建角色

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

{% step %}

#### 复制角色 ID

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

### 向 NPC 添加 Convai Chatbot 组件

{% stepper %}
{% step %}

#### 打开角色 Blueprint

在 **Outliner**中，点击你的 NPC Actor。在 **Details** 面板中，点击 **Edit Blueprint** 以打开 Blueprint 编辑器。你也可以直接从 **Content Browser**.
{% endstep %}

{% step %}

#### 打开 Blueprint 资源

在 Blueprint 编辑器中的 **Components** 面板内，点击 **Add**。搜索 `BP Convai ChatBot Component` 并选择它。这会添加由 Blueprint 封装的聊天机器人组件，该组件已预先连接好按住说话输入和聊天 UI 控件。
{% endstep %}

{% step %}

#### 设置角色 ID

在 **Convai Chatbot** 组件中选择 **Components** 面板。在 **Details** 面板中，找到 **Character ID** 字段，该字段位于 **Convai** 类别下，然后将你的角色 ID 粘贴到该字段中。
{% endstep %}

{% step %}

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

如果角色具有面部绑定，并且你想实现口型同步，请再次点击 **添加** ，搜索 `Convai Face Sync`并将其添加。选中该组件，并将 **口型同步模式** 设置为与绑定类型匹配的选项：

* **MetaHuman Blendshapes** — 适用于 MetaHuman 和 Reallusion CC5 角色。
* **CC4 Extended Blendshapes** — 适用于 Reallusion CC4 角色。
* **Viseme Based** — 适用于使用 OVR 视素的自定义绑定。

如果角色没有面部绑定，请跳过此步骤。
{% endstep %}

{% step %}

#### 编译并保存蓝图

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

{% step %}

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

若要让角色以特定表情开始，请打开 **事件图表**，添加一个 **Event BeginPlay** 节点，获取对 **Convai Chatbot** 组件的引用，然后调用 **Force Set Emotion**。将 **基本情绪** 设置为 `Happy`, **强度** 设置为 `Basic`，并将 **重置其他情绪** 设置为 `true`。情绪会随对话进展动态更新。请参阅 [情绪示例](https://docs.convai.com/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 Override** 。它已经预配置了 `BP_ConvaiPlayerComponent` 和聊天控件。此设置适用于原型开发；用于生产环境时，请按照上述说明将 `BP Convai Player Component` 直接添加到你自己的玩家 Pawn 蓝图中。
{% endhint %}

### 测试对话

{% stepper %}
{% step %}

#### 进入播放模式

点击 **播放** 在 Unreal Editor 工具栏中。视口中会出现聊天控件。
{% endstep %}

{% step %}

#### 与角色交谈

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

若要改用免提（VAD）模式，请打开玩家 Pawn 蓝图，选择 **Convai Player** 组件（`BP_ConvaiPlayerComponent`），展开 **Convai** 类别（位于 **细节** 面板，并禁用 **启用按键通话** (`EnablePushToTalk` ——这是 Blueprint 封装器上的变量，而不是裸 C++ 组件上的变量）。或者，调用 `UpdateVadBP(true)` 可在 Blueprint 中调用。请参阅 [配置对话输入](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-conversation-input.md) 了解完整的 VAD 调优选项。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
设置正常工作后，角色会发出可听见的语音响应，聊天小组件也会显示对话记录。如果角色没有响应，请参阅 [验证设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/validate-your-setup.md) 查看常见故障点检查清单。
{% endhint %}

### 后续步骤

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

{% content-ref url="/pages/f0a9565e073a000fe0ed7df2961660e00793150b" %}
[设置 MetaHuman 角色](https://docs.convai.com/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）角色](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)
{% 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/98b41781157f6eec98a195dad1b57f66765cf380" %}
[场景组件参考](https://docs.convai.com/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.
