> 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 插件的四个模块、运行时组件、会话代理和子系统路由模型。

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/>(blendshapes)"]
    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" %}
每个组件的 **显示名称** 是显示在 **添加组件** 面板中的标签。将组件添加到 Blueprint Actor 时，可通过显示名称查找各组件。Convai Subsystem 不是这样添加的——引擎会为每个游戏实例自动创建一个。
{% endhint %}

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

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

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

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

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

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

将某个 Actor 标记为场景对象，使 chatbot 能够在其环境契约中引用它。组件注册到 `UConvaiSubsystem`后，子系统会在共享时钟上轮询其跟踪的属性，并将更改合并为批量动态上下文更新。多个 chatbot 可以共享同一个对象组件。

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

一个将预先计算好的面部动画序列应用到骨骼网格体的场景组件。chatbot/音频流播放器路径会将面部数据转发到活动的口型同步接口，通常是 `UConvaiFaceSyncComponent`。该组件会对 blendshape 帧进行插值，并将结果以 `TMap<FName, float>` 通过位于 `ConvaiAnimGraph` 模块中的 AnimGraph 节点暴露给 Animation Blueprint。它支持 `关闭`, `自动`, `基于音素口型`, `MetaHuman 混合变形`, `ARKit 混合变形`，以及 `CC4 扩展混合变形` 模式。

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

一个 `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 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/plugin-architecture.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.