> 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/unreal-engine-plugin-beta-overview/installation-and-setup.md).

# 安装与设置 | Unreal Engine

## 简介

该 **Convai Unreal 引擎插件（测试版）** 将强大的实时对话式 AI 直接带入 **Unreal Engine**。\
从零开始重建，提供低延迟对话、感知环境的交互以及免手动通信。

无论你是在构建沉浸式 NPC，还是在玩家套装中打造 AI 伙伴，该插件都能借助 Convai 角色实现自然、语音驱动的体验。

{% embed url="<https://www.youtube.com/watch?v=n-UG3nmMeZQ>" %}

***

### 安装指南

有 **两种安装 Convai Unreal 插件的方法**:

1. **通过 FAB 安装（推荐）** —— 最简单的方法
2. **手动安装（高级）** —— 如果你需要来自 GitHub 的最新版本，请使用此方法

{% hint style="danger" %}

#### Beta 提示

此软件包目前处于 **测试版，**&#x4F60;可能会遇到 **意外的问题或行为**.

如果你遇到任何问题，请通过以下方式报告： [**Convai 开发者论坛**](https://forum.convai.com/).
{% endhint %}

***

### 1. 通过 FAB 安装（推荐）

1. 在 FAB 上打开 Convai 插件页面： <https://www.fab.com/listings/ba3145af-d2ef-434a-8bc3-f3fa1dfe7d5c>
2. 单击 **添加到库**.
3. 在 **Epic Games Launcher → 库**，将插件安装到你的 Unreal Engine 版本。
4. 打开你的 Unreal 项目并继续进行 **启用插件** 下文。

***

### 2. 手动安装（最新版本）

如果你想要 **最新的 SDK 版本**.

#### 步骤 1 — 下载插件

1. 前往 GitHub 发布页面： <https://github.com/Conv-AI/Convai-UnrealEngine-SDK-V4/releases>
2. 下载最新的 `.zip` 文件。
3. 解压压缩包 — 其中将包含一个名为 **Convai**.

***

#### 步骤 2 — 安装插件

你可以安装该插件 **全局于引擎** 或 **按项目**.

**选项 A — 引擎级安装（推荐）**

使插件可供以下内容使用： **所有 Unreal 项目** 使用相同引擎版本。

1. 导航到你的 Unreal Engine 安装文件夹。
2. 复制 **Convai** 文件夹到：

```
Engine/Plugins/Marketplace
```

示例（Windows）：

```
C:\Program Files\Epic Games\UE_5.x\Engine\Plugins\Marketplace
```

***

**选项 B — 项目级安装**

将插件安装到 **单个项目**.

1. 导航到你的项目根目录（即 `.uproject` 文件所在的位置）。
2. 创建一个名为 **Plugins** 的文件夹（如果它不存在）。
3. 复制 **Convai** 将文件夹放在这里：

```
YourProject/Plugins/Convai
```

***

### 3. 在 Unreal 中启用插件

1. 打开你的 Unreal 项目。
2. 前往：

```
编辑 → 插件
```

3. 搜索 **Convai**.
4. 启用该插件。
5. 按提示重启 Unreal。

***

## 配置你的玩家蓝图

启用插件后，你需要向你的 **玩家蓝图** 中添加两个主要组件，以启用 AI 交互。

### 1. 添加玩家组件

1. 打开你的主要玩家蓝图（例如， `BP_FirstPersonCharacter`).
   * 如果不确定，按 **播放**，在 **世界大纲**中选择你的角色，然后点击 **编辑蓝图** 在 **Details** 面板。
2. 在 **组件** 面板中，点击 **+ 添加 → BP\_ConvaiPlayerComponent**.
   * 这负责处理玩家端输入、麦克风控制和聊天 UI 管理。

### 2. 添加聊天机器人组件

1. 打开你的角色蓝图。
2. 单击 **+ 添加** 再次并选择 **BP\_ConvaiChatbotComponent**.
   * 这是 AI 的“思维核心”，负责管理对话逻辑、语音和视觉能力。
3. 打开 [Convai Playground](https://convai.com/dashboard) 并选择或创建一个角色。
4. 复制 **角色 ID**.
5. 回到 Unreal 中，选择 **BP\_ConvaiChatbotComponent** 并将 ID 粘贴到 **角色 ID** 字段中，位于 **Details** 面板。
6. **编译** 是位于 **保存** 你的蓝图中。

{% hint style="info" %}
**注意：** 这是一个最基础的设置，不包含动画、口型同步或面部表情——有专门的教程说明如何与不同类型的 Avatar（例如 Metahumans、Reallusion 等）集成。
{% endhint %}

***

## 测试设置

### 按键通话模式

1. 按 **播放** 在编辑器中。
2. 默认情况下，插件使用 **按住说话** 模式下编辑。
3. 按住 **T** 键即可与 AI 交流。

### 免手动模式

1. 停止游戏并打开你的玩家蓝图。
2. 选择 **BP\_ConvaiPlayerComponent**.
3. 在 **Details** 面板中，在 **默认值** 类别下，取消勾选 **启用按键通话**.
4. 重新编译并再次运行——现在你可以无需按任何键，自由说话。

### 调整聊天 UI

你可以更改聊天界面的外观和位置：

1. 选择 **BP\_ConvaiPlayerComponent**.
2. 在 **Details** 面板中，调整 **聊天小部件样式** （0、1 或 2）以修改外观和位置。

***

## 启用视觉

要让你的 AI 角色“看见”并描述环境，请按以下步骤操作：

1. 在你的角色蓝图中，点击 **+ 添加 → EnvironmentWebcam**.
2. 调整 **EnvironmentWebcam** 的位置和旋转，使其与角色头部对齐。
   * 需要略微位于角色头部前方，以免发生碰撞。
3. 在 **内容浏览器**，右键单击并选择 **Convai → Vision Render Target**.
   * 将其命名为类似 `RT_Vision`.
4. 返回你的蓝图，选择 **EnvironmentWebcam**，并将 **Convai Render Target** 到 `RT_Vision`.
5. 确保 **Auto Start Vision** 已勾选。
6. 按 **播放**，查看世界中的某个物体，并向你的 AI 询问它。

***

## 结论

你已成功完成 **Convai Unreal 引擎插件（测试版）** 的设置，并连接了你的第一个 Convai 角色。\
只需几个步骤，你就已在 Unreal Engine 中启用了基于语音的对话、环境感知和实时交互。

继续探索以自定义你的设置、集成多个角色，或连接高级 Convai 功能。有关反馈和社区讨论，请访问 [Convai 开发者论坛](https://forum.convai.com/).


---

# 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/unreal-engine-plugin-beta-overview/installation-and-setup.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.