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

### 包含内容

该插件附带完整的对话流程以及一组可选启用的功能附加项。

#### 对话流程

连接后始终处于激活状态：

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

#### 功能附加项

可选启用，每项均可通过 Blueprint 或 Details 面板配置：

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

#### 编辑器工具

该 `ConvaiEditor` 模块在编辑器中添加了一个配置窗口，用于设置 API 密钥、角色仪表板浏览器，以及 Blueprint 图表实用工具，例如 **创建 Convai 动作处理器** 右键菜单项。

### 与 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 密钥        | 账户 <code class="expression">space.vars.dashboard\_url</code>    |

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