> 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 Unreal Engine 插件将职责划分为五种不同类型：聊天机器人组件、玩家组件、对象组件、面部同步组件和游戏实例子系统。每种类型只负责系统中的一小部分；没有一种会重复另一种的职责。

### 组件层级

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

* `UConvaiAudioStreamer` ——最底层。它管理来自程序化声音波形的音频播放，并将每帧的 blendshape 面部数据传递给任何实现 `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` （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 发送一系列动作时，它们会进入 `ActionsQueue` 作为 `FConvaiResultAction` 条目。Blueprint 通过调用 `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` （Blueprint 显示名称 **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 都推送。启用 `bAutoGenerateProximityState` （默认）时，组件还会为每个聊天机器人合成一段接近度描述——例如“附近、前方偏右”——并将其作为状态键维护，在聊天机器人或对象移动时更新。

该组件公开四个注视事件（`OnGazedIn`, `OnGazedOut`, `OnAttentionGained`, `OnAttentionLost`），这样 Blueprint 就能独立于聊天机器人响应玩家的关注。

### Convai 面部同步组件

`UConvaiFaceSyncComponent` （Blueprint 显示名称 **Convai 面部同步**）是一个 `USceneComponent` ，实现了 `IConvaiLipSyncInterface`IConvaiLipSyncInterface

该 `LipSyncMode` 属性（`EC_LipSyncMode`）选择目标 blendshape 格式：

| 值                 | 显示名称                     | 用于                |
| ----------------- | ------------------------ | ----------------- |
| `关闭`              | 关闭                       | 禁用口型同步            |
| `Auto`            | Auto                     | 让插件选择             |
| `VisemeBased`     | 基于 Viseme                | 通用 viseme 目标      |
| `BS_MHA`          | MetaHuman Blendshapes    | MetaHuman 绑定（默认）  |
| `BS_ARKit`        | ARKit Blendshapes        | 兼容 ARKit 的绑定      |
| `BS_CC4_Extended` | CC4 Extended Blendshapes | Reallusion CC4 绑定 |

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

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

### 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 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/core-concepts/runtime-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.