> 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/core-concepts/runtime-architecture.md).

# 运行时架构

了解 Convai Chatbot、Player、Object、Face Sync 组件与 Convai Subsystem 之间的角色、所有权和关系。

Convai Unreal Engine 插件将职责分为五种不同类型：聊天机器人组件、玩家组件、对象组件、面部同步组件，以及游戏实例子系统。每种类型只负责系统中的一小部分；彼此之间没有重复职责。

### 组件层级

所有具备对话能力的组件都共享一个两层基础：

* `UConvaiAudioStreamer` ——最底层。它负责管理来自程序化声音波形的音频播放，并向任何实现了 `IConvaiLipSyncInterface`的组件传递逐帧混合形状面部数据。它还提供一个视觉插槽（`IConvaiVisionInterface`）用于摄像头或渲染目标输入。这两个接口都是扩展点： `IConvaiLipSyncInterface` 是 `UConvaiFaceSyncComponent` （以及任何自定义口型同步驱动）接收面部数据的方式，而 `IConvaiVisionInterface` 是摄像头视频流或渲染目标组件向 AI 提供视觉上下文的方式。聊天机器人和玩家都从该类继承音频和面部能力。
* `UConvaiConversationComponent` ——扩展自 `UConvaiAudioStreamer`。它添加了共享的对话名称辅助函数（`GetConversationalName`）以及聊天机器人和玩家都继承的两个委托： `OnTranscriptionReceivedDelegate` 和 `参与者连接状态变化事件`.

```mermaid
graph TD
    Streamer["UConvaiAudioStreamer\n(音频播放、面部数据、\n口型同步、视觉接口)"]
    Base["UConvaiConversationComponent\n(抽象基类——转写委托、\n参与者状态事件、对话名称)"]
    Chatbot["UConvaiChatbotComponent\n(Convai 聊天机器人)\n角色 ID、会话、情感、动作、语音"]
    Player["UConvaiPlayerComponent\n(Convai 玩家)\n麦克风、流式传输、凝视"]
    Streamer --> Base
    Base --> Chatbot
    Base --> Player
```

### Convai Chatbot 组件

`UConvaiChatbotComponent` (Blueprint 显示名称 **Convai 聊天机器人**）是面向 AI 驱动角色的核心组件。它负责：

* **身份。** `CharacterID` 用于标识要加载的角色，而 `CharacterName` 保存已加载的角色名称。更广泛的角色配置管理不在本运行时架构页面中处理。
* **会话。** 该 `bAutoInitializeSession` 标志位和 `StartSession` / `StopSession` 函数通过子系统管理 WebRTC 通道。详见 [会话生命周期](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md) 了解详情。
* **对话状态。** 诸如 `GetIsTalking`, `IsListening`, `IsProcessing`，以及 `IsInConversation` 之类的只读状态函数会暴露当前的辅助函数集合。在当前 SDK 中， `GetIsTalking` 反映音频播放；请参见 [对话流程](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/conversation-flow.md) 了解每个辅助函数的确切行为。
* **动作队列。** 当 Convai 发送一系列动作时，它们会进入 `动作队列` 为 `FConvaiResultAction` 条目中。Blueprint 通过调用 `获取第一个动作`读取当前队首条目，执行该动作，然后调用 `处理动作完成`。成功完成后会将当前动作出队，并推进队列。当某个动作发生无法恢复的失败时，请调用 `中止动作序列` 来清空队列。
* **情感状态。** `情绪状态` （类型 `FConvaiEmotionState`）会被复制。 `锁定情绪状态` 可防止传入更新覆盖手动设置的情感。
* **环境。** `EnvironmentData` （类型 `FConvaiEnvironmentData`）保存 AI 可引用的动作模板、对象和角色。请在运行时通过更细粒度的方法修改它 `AddObject`, `RemoveObject`, `AddCharacter`，以及 `设置注意对象` ——而不是直接写入该属性。动作模板位于 `EnvironmentData.Actions` 在 `/connect` 创建时固定；只有对象和角色可以在会话中途更新。
* **动态上下文。** `UpdateContext`, `SetContextState`, `SetContextStates`, `AddContextEvent`，以及 `ResetDynamicContext` 在实时会话期间将实时世界状态推送给 AI。更新会使用由 `ContextDebounceWindow` 和 `ContextMaxDebounceWindow`.
* **会话值重置。** `SessionID` 默认为 `"-1"`，以及 `ResetConversation` 将其重置为 `"-1"`。当前的 WebRTC 连接路径不提供 `SessionID` 作为恢复参数。
* **注意目标。** `ConversationPartner`, `注视目标`，以及 `指向目标` 是已复制的属性，用于跟踪角色正在与哪位玩家交谈，以及它正在注视或指向什么。

聊天机器人组件还实现了 `IConvaiConnectionInterface`，子系统正是通过它将传入的音频、动作、情感数据和面部数据路由到正确的组件。

### Convai Player 组件

`UConvaiPlayerComponent` (Blueprint 显示名称 **Convai Player**）代表对话中的人类一侧。它负责：

* **身份。** `PlayerName` 通过 `SetPlayerName` 及其对应的服务器 RPC 进行复制。 `EndUserID` 和 `EndUserMetadata` 都有 setter 函数及其对应的服务器 RPC，但在当前 SDK 构建中未注册用于复制。
* **会话。** 同样的 `bAutoInitializeSession`, `StartSession`, `StopSession`，以及 `IsPlayerConnected` 接口与聊天机器人相同，但面向玩家端的 WebRTC 通道。
* **麦克风。** `UnmuteStreamingAudio` / `MuteStreamingAudio` 控制实时流式传输。 `StartRecording` / `FinishRecording` 将完整的一段话捕获为一个 `USoundWave`。可通过 `SetCaptureDeviceByIndex`, `SetCaptureDeviceByName`以及相关查询函数进行设备选择。
* **凝视注意力。** 当 `bEnableGazeAttention` 是 `true`时，该组件会在每个 tick 从玩家摄像机进行射线检测。持续凝视某个 `UConvaiObjectComponent` 会通过对象组件转发给符合条件的已注册聊天机器人，而每个聊天机器人都可将其接纳为当前注意对象。
* **按住说话和 VAD。** `bMute` 会静音麦克风提交。 `UpdateVadBP` 切换语音活动检测。

玩家组件实现了两个接口： `IConvaiConnectionInterface` （与聊天机器人相同——供子系统用于会话路由和事件分发）以及 `IConvaiProcessedAudioReceiver`。音频处理中间件实现了 `IConvaiAudioProcessingInterface`；玩家组件是已处理音频的接收端，会在这些帧转发给子系统之前接收它们。

### Convai 对象组件

`UConvaiObjectComponent` 会将任何 `Actor` 关卡中的对象注册为所有聊天机器人都可引用的命名对象。将其放到门、拉杆、房间或道具上，并填写 `ObjectEntry` （名称和描述）。该组件会在 `BeginPlay`时向子系统注册自身。 `AddOrUpdateObjectFromComponent`.

可选地， `TrackedProperties` 使设计者能够绑定 `UPROPERTY` 字段到拥有者 Actor 的 AI 上下文中。所有对象组件共享一个轮询时钟（大约每 `0.25` 秒一次）。每次轮询时，子系统都会评估每个被跟踪的属性，并推送一个 `SetContextState` 更新，仅在值发生变化时才发给已注册的聊天机器人——而不是每个 tick 都发。该组件不再自行生成针对每个聊天机器人的邻近描述；自从 `4.0.0-beta.22`，每个已注册对象的距离和方向——例如“附近、前方并偏右”——都由 [空间感知](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness.md) 子系统集中计算，并连同其他上下文一起交付给每个聊天机器人。

该组件暴露四个凝视事件（`OnGazedIn`, `OnGazedOut`, `OnAttentionGained`, `OnAttentionLost`），这样 Blueprint 就可以独立于聊天机器人响应玩家焦点。

### Convai 面部同步组件

`UConvaiFaceSyncComponent` (Blueprint 显示名称 **Convai Face Sync**）是一个 `USceneComponent` 实现了 `IConvaiLipSyncInterface`。它接收来自聊天机器人音频管线的预计算面部数据，并在每个 tick 驱动混合形状。

该 `LipSyncMode` 属性（`EC_LipSyncMode`）用于选择目标混合形状格式：

| 值                 | 显示名称           | 用于                  |
| ----------------- | -------------- | ------------------- |
| `关闭`              | 关闭             | 禁用口型同步              |
| `自动`              | 自动             | 让插件选择               |
| `基于视素`            | 基于音素口型         | 通用视素目标              |
| `BS_MHA`          | MetaHuman 混合变形 | MetaHuman 骨骼绑定（默认）  |
| `BS_ARKit`        | ARKit 混合变形     | 兼容 ARKit 的骨骼绑定      |
| `BS_CC4_Extended` | CC4 扩展混合变形     | Reallusion CC4 骨骼绑定 |

面部同步组件是被动的——它不会发起任何网络活动。面部数据通过聊天机器人的音频流管线路由到实现 `IConvaiLipSyncInterface`的组件，而面部同步组件会在每个 tick 将得到的混合形状值暴露给角色的 Anim Blueprint。

若要从 Anim Blueprint 应用混合形状，请添加 **Convai Face Sync** AnimGraph 节点（`FAnimNode_ConvaiFaceSync`）到角色的动画图中。该节点接收一个 `UConvaiChatbotComponent` 引脚（默认显示），并在每个动画 tick 采样混合形状数据。它支持基于混合形状名称列表的上/下面部 alpha 控制，以及通过一个 `BlendshapeMapping` 表进行混合形状名称重映射、全局乘数和偏移，以及在最近没有面部数据到达时可配置的饥饿淡入/淡出。

### Convai 子系统

`UConvaiSubsystem` 是一个 `UGameInstanceSubsystem` ——它随游戏实例启动和停止。它是插件 Unreal 层与底层 WebRTC 传输（`convai::ConvaiClient`).

该子系统负责：

* **连接管理。** `ConnectSession` 和 `DisconnectSession` 由组件会话代理调用；无需 Blueprint 交互。
* **组件注册表。** 子系统维护已注册聊天机器人、玩家和对象组件的列表，以便将运行时数据转发给当前会话及相关组件回调。
* **跟踪属性轮询。** 子系统运行一个共享轮询时钟（大约每 0.25 秒一次），用于评估所有已注册的 `UConvaiObjectComponent` 跟踪属性，并同步执行。只有在值发生变化时才会将其推送给已注册的聊天机器人，从而避免不必要的上下文流量。
* **全局连接状态。** `GetServerConnectionState` 返回当前 `EC_ConnectionState` 值。该枚举包含 `已断开连接`, `连接中`, `已连接`，以及 `重新连接中`，但当前运行时路径驱动 `已断开连接`, `连接中`，以及 `已连接`. `OnServerConnectionStateChangedEvent` 在被驱动状态发生变化时触发。
* **空闲管理。** `ResetIdleTimer` 和 `InvalidateOrphanedConnection` 让 Blueprint 在子系统检测到空闲或失效连接时介入。 `OnUserIdleWarning` 会在空闲超时到期前触发，以便游戏有机会阻止断开连接。

子系统的完整 Blueprint 接口在 [会话生命周期](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md).

### 所有权与生命周期

| 组件                         | 所有者                            | 生命周期       |
| -------------------------- | ------------------------------ | ---------- |
| `UConvaiChatbotComponent`  | NPC `Actor`                    | 与 Actor 相同 |
| `UConvaiPlayerComponent`   | 玩家 `Actor` （Pawn 或 Controller） | 与 Actor 相同 |
| `UConvaiObjectComponent`   | 场景中的任意 `Actor`                 | 与 Actor 相同 |
| `UConvaiFaceSyncComponent` | NPC `Actor` （与聊天机器人组件一起）       | 与 Actor 相同 |
| `UConvaiSubsystem`         | 该 `UGameInstance`              | 整个游戏会话     |

聊天机器人、玩家和对象组件在 `BeginPlay` 并在 `EndPlay`中向子系统注册，并在中注销，因此在游戏中途被销毁的组件（例如被击杀的角色）会干净地从子系统注册表中移除自身。面部同步组件附加在角色上，但不会向子系统注册。

### 相关概念

当你需要控制连接时序时，请接着阅读生命周期页面；当你需要回合级行为时，请阅读流程页面；当你需要 Blueprint 委托详情时，请阅读事件页面。

{% content-ref url="/pages/a8878427b216a80d6b385f1a342c440aa9b398c9" %}
[会话生命周期](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md)
{% endcontent-ref %}

{% content-ref url="/pages/422d78b3fb4f61a00785b876137cbfde618d7baa" %}
[对话流程](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/conversation-flow.md)
{% endcontent-ref %}

{% content-ref url="/pages/ddcceab71734a05a1e99c8599b42f364e146005e" %}
[事件系统](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/event-system.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/core-concepts/runtime-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.