> 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 或 Details 面板进行配置：

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

#### 编辑器工具

“ `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 密钥        | 一个账号，位于 [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 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/convai-unreal-engine-plugin/overview/what-is-the-convai-unreal-engine-plugin.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.