> 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/plugin-architecture.md).

# 插件架构

Convai Unreal Engine 插件由四个模块、运行时组件、连接会话代理，以及 `UConvaiSubsystem`。每个模块都有明确的作用范围和加载阶段；每个组件都只有单一职责，并通过 Unreal 的组件和子系统模型进行通信。

### 模块

该插件在 `ConvAI.uplugin`.

| 模块                 | 类型           | 平台            | 用途                                                                                                             |
| ------------------ | ------------ | ------------- | -------------------------------------------------------------------------------------------------------------- |
| `Convai`           | 运行时          | Win64、Android | 核心对话流水线：WebRTC 会话管理、音频流传输、聊天机器人和玩家组件、子系统、动态上下文、环境、动作、视觉。                                                       |
| `ConvaiEditor`     | 编辑器          | 全部（仅编辑器构建）    | 仅供编辑器使用的工具。编辑器内的配置窗口、API 密钥设置界面以及角色仪表板浏览器需要 UE 5.2 或更高版本；诸如以下内容的 Blueprint 图工具： `创建 Convai 动作处理器` 右键菜单项是编辑器功能。 |
| `ConvaiAnimGraph`  | UncookedOnly | 全部            | 从 Convai 组件读取实时 blendshape 值并将其应用到 Animation Blueprint 中的动画图节点。                                                |
| `ConvaiVisionBase` | 运行时          | Win64、Android | 视觉功能的基础层：帧捕获和图像编码。 `Convai` 运行时通过活动会话路径发送捕获的帧。                                                                 |

该 `Convai` 模块在 `PreDefault` 阶段加载，因此在游戏玩法系统初始化之前即可用。 `ConvaiEditor` 在 `PostEngineInit` 时加载，以便能够访问完全初始化的编辑器环境。

### 系统图

下图显示了单个玩家-角色对话轮次的运行时流程。

```mermaid
graph TD
    Player["UConvaiPlayerComponent<br/>(音频捕获，凝视)"]
    PlayerProxy["UConvaiConnectionSessionProxy<br/>(玩家)"]
    ChatbotProxy["UConvaiConnectionSessionProxy<br/>(角色)"]
    Chatbot["UConvaiChatbotComponent<br/>(会话、环境、动作)"]
    Subsystem["UConvaiSubsystem<br/>(Convai 客户端、路由)"]
    AudioStreamer["音频流传输器<br/>(音频 + 口型同步接口)"]
    FaceSync["UConvaiFaceSyncComponent<br/>(混合形态)"]
    AnimGraph["ConvaiAnimGraph 节点<br/>(AnimBP)"]
    Object["UConvaiObjectComponent<br/>(场景对象)"]
    Convai["Convai<br/>(LLM、语音、叙事)"]

    Player -->|"音频帧"| PlayerProxy
    PlayerProxy -->|"会话数据"| Subsystem
    Chatbot -->|"角色会话"| ChatbotProxy
    ChatbotProxy -->|"会话数据"| Subsystem
    Subsystem -->|"WebRTC 流"| Convai
    Convai -->|"音频 + 面部数据<br/>动作序列<br/>情绪状态"| Subsystem
    Subsystem -->|"分发到角色会话"| ChatbotProxy
    ChatbotProxy -->|"响应回调"| Chatbot
    Chatbot -->|"音频 + 面部数据"| AudioStreamer
    AudioStreamer -->|"口型同步接口"| FaceSync
    FaceSync -->|"blendshape 值"| AnimGraph
    Object -->|"属性变更"| Subsystem
    Subsystem -->|"批量上下文更新"| Chatbot
    Chatbot -->|"上下文刷新"| Convai
```

`UConvaiSubsystem` 它拥有底层 Convai 客户端，并为当前活动的玩家和角色会话代理路由数据。运行时组件会向子系统注册，以便其将音频、响应数据、对象更新和上下文刷新路由到正确的组件。

### 运行时组件

本页所述架构由四个主要对话组件构成，并像原生 Unreal 组件一样附加到 Actor 上。其他可由 Blueprint 生成的辅助组件支持音频捕获、视觉和诊断工作流。另一个独立的运行时部分， `UConvaiSubsystem`，是一个 `UGameInstanceSubsystem` 由 Unreal 自动创建，而不是你手动添加的组件。

{% hint style="info" %}
每个组件的 **显示名称** 是显示在 **添加组件** Unreal 编辑器中的面板标签。将组件添加到 Blueprint Actor 时，可使用显示名称查找每个组件。Convai Subsystem 不是通过这种方式添加的——引擎会为每个游戏实例自动创建一个。
{% endhint %}

#### `UConvaiChatbotComponent` （显示名称：Convai Chatbot）

AI 角色的核心组件。它保存角色 ID、会话状态、环境契约（动作、对象、场景角色）、动态上下文、情绪状态以及动作队列。每个 AI 角色 Actor 对应一个实例。

`UConvaiChatbotComponent` 为其角色持有一个连接会话代理。当会话开始时，该组件会将代理注册到 `UConvaiSubsystem`，由其通过底层 Convai 客户端路由音频和响应数据。聊天机器人接收音频、面部动画数据和动作序列，然后协调音频播放、口型同步处理以及 Blueprint 动作处理器。

#### `UConvaiPlayerComponent` （显示名称：Convai Player）

表示对话中的人类玩家。它通过 `UConvaiAudioCaptureComponent`捕获麦克风音频，将其流式传输到当前活动的聊天机器人会话，并驱动凝视注意力系统，用于跟踪哪些 `UConvaiObjectComponent` Actor 位于玩家准星下。

#### `UConvaiObjectComponent` （显示名称：Convai Object Component）

将一个 Actor 标记为聊天机器人可在其环境契约中引用的场景对象。当该组件注册到 `UConvaiSubsystem`时，子系统会在共享时钟上轮询其跟踪的属性，并将变更合并为批量的动态上下文更新。多个聊天机器人可以共享同一个对象组件。

#### `UConvaiFaceSyncComponent` （显示名称：Convai Face Sync）

将预先计算的面部动画序列应用到骨骼网格体的场景组件。聊天机器人/音频流传输器路径会将面部数据转发到当前活动的口型同步接口，通常是 `UConvaiFaceSyncComponent`。该组件会对 blendshape 帧进行插值，并公开其结果 `TMap<FName, float>` 通过 `ConvaiAnimGraph` 中的 AnimGraph 节点向 Animation Blueprint 提供 `关闭`, `Auto`, `基于 Viseme`, `MetaHuman Blendshapes`, `ARKit Blendshapes`，以及 `CC4 Extended Blendshapes` 模式。

#### `UConvaiSubsystem` （显示名称：Convai Subsystem）

A `UGameInstanceSubsystem` 充当共享连接管理器和组件注册表的子系统。它维护底层 Convai 客户端，将音频和数据包路由到正确的会话代理，并跟踪路由所需的已注册运行时组件。

### 插件依赖项

插件在 `ConvAI.uplugin`:

| 插件                         | 已启用 | 角色                      |
| -------------------------- | --- | ----------------------- |
| `AudioCapture`             | 是   | 麦克风输入流水线                |
| `AndroidPermission`        | 是   | Android 上的运行时麦克风权限请求    |
| `EditorScriptingUtilities` | 是   | 供 `ConvaiEditor` （仅编辑器） |
| `PropertyAccessEditor`     | 是   | 供 `ConvaiEditor` （仅编辑器） |

### 下一步

了解模块和组件模型后，请安装插件或浏览完整功能集。

{% 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/4551a191a6c59cb019973be9f8a2775cdb4a257a" %}
[功能地图](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/overview/feature-map.md)
{% endcontent-ref %}

{% content-ref url="/pages/cc24f3efcd97e1aad244208204220bfb8a89c7c3" %}
[什么是 Convai Unreal Engine 插件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/overview/what-is-the-convai-unreal-engine-plugin.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/plugin-architecture.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.