> 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/overview/what-is-the-convai-unreal-engine-plugin.md).

# 什么是 Convai Unreal Engine 插件

了解 Convai Unreal Engine 插件为项目添加了什么：Blueprint 组件、实时语音管线以及可选功能扩展。

Convai Unreal Engine 插件将 Unreal Engine 5 项目连接到 Convai，使场景内的角色能够实时说话、聆听、推理和行动。玩家可以通过麦克风说话或发送文本；插件捕获输入，将其流式传输到 Convai 进行语音识别和语言理解，使用文本转语音生成响应，并通过与口型同步、面部情绪和可选场景内动作同步的方式在角色上播放。该插件面向正在构建培训模拟、交互式体验和游戏的 Unreal 开发者。

### 包含内容

该插件附带完整的对话流程以及一组可选功能扩展。

#### 对话流程

连接后始终启用：

* **实时语音输入** — 通过以下方式进行麦克风采集： `UConvaiAudioCaptureComponent`，通过 WebRTC 流式传输到 Convai
* **语言理解与生成** — Convai 处理语音并以角色身份回应
* **文本转语音播放** — 由 Convai 生成的语音，通过以下方式回放： `UConvaiChatbotComponent`

#### 功能扩展

可选启用，每项都可通过 Blueprint 或“详细信息”面板配置：

* **角色动作** — 角色执行结构化的场景内命令（`移动到`, `跟随`，自定义）由 Convai 下发
* **动态上下文** — 在运行时将实时世界状态和事件注入角色知识
* **情绪** — Convai 从对话中推断情绪，并驱动角色上的 blendshape 表情
* **长期记忆** — 角色通过终端用户 ID 记住每位玩家的跨会话信息
* **叙事设计** — 从 Blueprint 中按名称触发脚本化的对话分支和章节
* **场景元数据** — 为关卡 Actor 添加标签，使角色能够感知并对其采取行动
* **视觉** — 将摄像机画面流式传输到 Convai，以便角色描述他们所看到的内容
* **凝视关注** — 将玩家凝视方向上的对象作为上下文传递给当前激活的角色
* **口型同步** — Convai 提供的面部动画数据驱动 blendshape 嘴部动作，与语音音频同步，并可选择 `基于音素口型`, `MetaHuman 混合变形`, `ARKit 混合变形`，以及 `CC4 扩展混合变形` 适用于不同骨骼绑定的模式

#### 编辑器工具

该 `ConvaiEditor` 模块为 API 密钥设置、角色仪表板浏览器以及 Blueprint 图表实用工具（例如以下内容）添加了一个编辑器内配置窗口： **Create Convai Action Handler** 右键菜单项。

### 与 Convai 的关系

Convai 托管语言模型、语音合成、叙事设计引擎、长期记忆存储和角色配置。该插件是一个客户端集成层：它从玩家处捕获音频或文本，通过 WebRTC 将其流式传输到 Convai，并将响应传回角色的音频和动画流程。

该插件在游戏进程内运行客户端集成逻辑，包括会话路由、音频播放、动作处理、动态上下文、凝视关注和场景元数据。它不捆绑本地语言模型或 Convai 决策引擎。角色配置和对话决策仍保留在 Convai 中，因此仪表板端的更改无需重新编译 Unreal 项目。

### 语音 → Convai → 角色流程

```mermaid
graph LR
    MIC["麦克风 / 文本"] --> PC["UConvaiPlayerComponent"]
    PC -->|"会话代理"| PProxy["UConvaiConnectionSessionProxy<br/>(玩家)"]
    Chatbot["UConvaiChatbotComponent"] -->|"会话代理"| CProxy["UConvaiConnectionSessionProxy<br/>(角色)"]
    PProxy --> SS["UConvaiSubsystem<br/>(Convai 客户端)"]
    CProxy --> SS
    SS -->|"流式传输"| CV["Convai"]
    CV -->|"音频 + 面部数据 + 动作序列"| SS
    SS --> CProxy
    CProxy --> Chatbot
    Chatbot --> AUD["音频播放"]
    Chatbot --> FS["UConvaiFaceSyncComponent<br/>(唇形同步)"]
    Chatbot --> BH["Blueprint 动作处理器"]
```

`UConvaiPlayerComponent` 捕获麦克风音频并通过玩家会话代理发送。 `UConvaiChatbotComponent` 持有角色会话代理。 `UConvaiSubsystem` 负责底层的 Convai 客户端，并在这些代理与 Convai 之间路由数据。聊天机器人接收响应数据，并协调音频播放、口型同步处理和 Blueprint 动作处理器。

### 以 Blueprint 为先的设计

主要游戏流程都暴露给 Blueprint 图表。可以使用 C++，但它属于次要方式；大多数项目都可以通过 Blueprint 组件、事件和可调用节点构建角色逻辑，然后仅在项目特定扩展时使用 C++。

### 要求

| 要求            | 最低要求                                                            |
| ------------- | --------------------------------------------------------------- |
| Unreal Engine | <code class="expression">space.vars.unreal\_min\_version</code> |
| 平台            | `Win64`, `Android`                                              |
| 网络            | 连接到 Convai 的互联网连接                                               |
| API 密钥        | 在……上的账户 [Convai 仪表板](https://convai.com)                        |

{% hint style="info" %}
Android 需要处理麦克风权限。该插件捆绑了 `AndroidPermission` 引擎插件作为依赖项，并在连接到 Convai 时自动请求 `RECORD_AUDIO` 权限。
{% endhint %}

Convai Unreal Engine 插件可在以下平台获取： [Fab](https://www.fab.com/listings/ba3145af-d2ef-434a-8bc3-f3fa1dfe7d5c)。插件发布版本也会发布在 [GitHub](https://github.com/Conv-AI/Convai-UnrealEngine-SDK-V4/releases).

有关完整的平台和引擎版本支持矩阵，请参阅“兼容性和要求”。

{% content-ref url="/pages/c0b1130cf155d2cf91b5a9d03994277bafb81c6f" %}
[兼容性与要求](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/compatibility-and-requirements.md)
{% endcontent-ref %}

### 下一步

安装插件并添加你的第一个 AI 角色。

{% content-ref url="/pages/fb3a2bacc1ba8d2d274717ebd7a3ac02e56aabb8" %}
[快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started.md)
{% endcontent-ref %}

在开始构建前，要了解模块和组件结构，请参阅架构页面。

{% content-ref url="/pages/27197a3dc9f39c8dc152420a719cf1ad8e9a6be2" %}
[插件架构](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/overview/plugin-architecture.md)
{% endcontent-ref %}

如需在一页内概览所有功能并查看对应指南的链接，请参阅功能地图。

{% content-ref url="/pages/4551a191a6c59cb019973be9f8a2775cdb4a257a" %}
[功能地图](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/overview/feature-map.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/overview/what-is-the-convai-unreal-engine-plugin.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.