> 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` 和 `OnAttendeeConnectionStateChangedEvent`.

```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 聊天机器人组件

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

* **身份。** `CharacterID` 用于指定要加载的角色，而 `CharacterName` 用于存储已加载角色的名称。更广泛的角色配置由本运行时架构页面之外的部分管理。
* **会话。** 该 `bAutoInitializeSession` 标志以及 `StartSession` / `StopSession` 函数通过子系统管理 WebRTC 通道。详情请参阅 [会话生命周期](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md) 。
* **对话状态。** 只读状态函数，例如 `GetIsTalking`, `IsListening`, `IsProcessing`，以及 `IsInConversation` 用于公开当前的辅助函数接口。在当前 SDK 中， `GetIsTalking` 反映音频播放状态；各辅助函数的具体行为请参阅 [对话流程](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/conversation-flow.md) 。
* **操作队列。** 当 Convai 发送一系列操作时，这些操作会进入 `ActionsQueue` ，作为 `FConvaiResultAction` 条目。蓝图通过调用 `FetchFirstAction`读取当前队首条目，执行操作，然后调用 `HandleActionCompletion`。成功完成后，当前操作会出队，队列随之推进。如果操作发生不可恢复的失败，请调用 `AbortActionSequence` 清空队列。
* **情绪状态。** `EmotionState` （类型为 `FConvaiEmotionState`）会进行复制。 `LockEmotionState` 可防止传入的更新覆盖手动设置的情绪。
* **环境。** `EnvironmentData` （类型为 `FConvaiEnvironmentData`）包含 AI 可以引用的操作模板、对象和角色。运行时请通过以下细粒度方法修改这些数据： `AddObject`, `RemoveObject`, `AddCharacter`以及 `SetObjectInAttention` ，而不要直接写入属性。 `EnvironmentData.Actions` 中的操作模板在 `/connect` 时确定；会话期间只能更新对象和角色。
* **动态上下文。** `UpdateContext`, `SetContextState`, `SetContextStates`, `AddContextEvent`以及 `ResetDynamicContext` 在实时会话期间向 AI 推送实时世界状态。更新会通过防抖时间窗口进行批处理，该窗口由 `ContextDebounceWindow` 和 `ContextMaxDebounceWindow`.
* **会话值重置。** `SessionID` 默认为 `"-1"`，而 `ResetConversation` 会将其重置为 `"-1"`。当前的 WebRTC 连接路径不会将 `SessionID` 作为恢复会话参数提供。
* **注意力目标。** `ConversationPartner`, `LookAtTarget`和 `PointAtTarget` 是复制属性，用于跟踪角色正在与哪位玩家交谈，以及角色正在看向或指向何处。

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

### Convai 玩家组件

`UConvaiPlayerComponent` （蓝图显示名称为 **Convai 玩家**）代表对话中的人类一方。它管理：

* **身份。** `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` 允许设计人员将所属 Actor 上的 `UPROPERTY` 字段绑定到 AI 上下文。所有对象组件共用一个轮询计时器（间隔约为 `0.25` 秒）。每次轮询时，子系统都会评估所有被跟踪的属性，并且仅在值发生变化时向已注册的聊天机器人推送 `SetContextState` 更新，而非每个 Tick 都推送。该组件不再为每个聊天机器人单独生成邻近描述；自 `4.0.0-beta.22`起，每个已注册对象的距离和方向（例如“附近，在前方偏右”）都由 [空间感知](https://docs.convai.com/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 面部同步**）是一个 `USceneComponent` ，实现了 `IConvaiLipSyncInterface`。它接收聊天机器人音频管线预先计算的面部数据，并在每个 Tick 驱动混合变形。

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

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

面部同步组件是被动的——不会主动发起任何网络活动。面部数据会通过聊天机器人的音频流处理管线传递给实现了 `IConvaiLipSyncInterface`的组件，而面部同步组件则会在每个 Tick 将生成的混合变形值提供给角色的 Anim Blueprint。

若要从 Anim Blueprint 应用混合变形，请将 **Convai 面部同步** AnimGraph 节点（`FAnimNode_ConvaiFaceSync`）添加到角色的动画图中。该节点接收一个 `UConvaiChatbotComponent` 引脚（默认显示），并在每个动画 Tick 采样混合变形数据。它支持基于混合变形名称列表控制上脸和下脸的 Alpha 值、通过 `BlendshapeMapping` 表重新映射混合变形名称、设置全局乘数和偏移量，以及在近期未收到面部数据时配置数据缺失期间的渐入和渐出效果。

### Convai 子系统

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

该子系统负责：

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

子系统完整的 Blueprint 接口详见 [会话生命周期](https://docs.convai.com/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" %}
[会话生命周期](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md)
{% endcontent-ref %}

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

{% content-ref url="/pages/ddcceab71734a05a1e99c8599b42f364e146005e" %}
[事件系统](https://docs.convai.com/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.
