> 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 Engine 插件（测试版）** 将强大、实时的对话式 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" %}

#### 测试版说明

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

如果你遇到任何问题，请通过以下方式报告： [**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 启动器 → 库**，将插件安装到你的 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。

***

## 配置你的 Player 蓝图

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

### 1. 添加 Player 组件

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

### 2. 添加 Chatbot 组件

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

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

***

## 测试设置

### 按键说话模式

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

### 免手操作模式

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

### 调整聊天 UI

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

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

***

## 启用视觉

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

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

***

## 结论

你已成功设置 **Convai Unreal Engine 插件（测试版）** 并连接了你的第一个 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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.