> 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.md).

# 核心概念

了解 Convai Unreal Engine 插件的组件模型、各组件的所有权以及它们在运行时如何协同工作。

Convai Unreal Engine 插件围绕一组精简的运行时类型构建，每种类型都各司其职。了解每种类型的作用及其相互关系，有助于你配置角色、处理事件，并根据项目需求扩展插件。

如果你是 **运行时架构** 插件内部机制的新手，可以从这里开始。需要了解特定系统（会话管理、对话状态或蓝图事件）时，再阅读其余页面。

### 运行时模型

关卡中的大多数 Convai 交互都涉及聊天机器人组件和玩家组件。两者都继承自共用的抽象基类 `UConvaiConversationComponent`，因此共享通用的对话事件接口。对象行为和面部同步行为使用不同的组件类型，而 `UConvaiSubsystem` 是一个 `UGameInstanceSubsystem`，而不是 `Actor` 组件。

| 运行时类型                      | 蓝图显示名称           | 职责                                        |
| -------------------------- | ---------------- | ----------------------------------------- |
| `UConvaiChatbotComponent`  | **Convai 聊天机器人** | 表示由 AI 驱动的角色。管理角色 ID、会话状态、情绪状态、环境数据和动作队列。 |
| `UConvaiPlayerComponent`   | **Convai 玩家**    | 表示玩家侧的参与者。管理麦克风采集、音频流传输、按键通话状态和注视注意力。     |
| `UConvaiObjectComponent`   | **Convai 对象组件**  | 注册场景中的对象或道具，使所有聊天机器人都能在动作和上下文中通过名称引用它。    |
| `UConvaiFaceSyncComponent` | **Convai 面部同步**  | 根据角色传入的音频驱动混合变形或视素动画。                     |
| `UConvaiSubsystem`         | **Convai 子系统**   | 游戏实例子系统。管理底层 WebRTC 连接、组件注册表和全局连接状态。      |

该子系统是单例——它会随游戏实例自动启动，并且始终可通过蓝图中的 **Get Game Instance → Get Subsystem (Convai Subsystem)** 节点链访问。

### 各部分如何协同工作

在蓝图中，聊天机器人组件和玩家组件不会直接相互通信。它们都依赖于负责实际传输层的子系统。玩家说话时，音频会从 `UConvaiPlayerComponent` 经由子系统传输到 Convai。角色的音频响应会到达子系统，再转发到当前角色会话。

```mermaid
graph TD
    P["Convai 玩家组件\n（麦克风 → PCM）"]
    C["Convai 聊天机器人组件\n（角色 ID、会话、事件）"]
    S["Convai 子系统\n（WebRTC 传输）"]
    O["Convai 对象组件\n（场景对象）"]
    F["Convai 面部同步组件\n（混合变形）"]
    Convai["Convai"]

    P -->|"音频流"| S
    S -->|"音频 + 数据包"| Convai
    Convai -->|"音频 + 动作 + 情绪"| S
    S -->|"当前角色会话"| C
    C -->|"音频"| F
    O -->|"对象注册表"| S
```

上图展示了运行时数据流。对象组件会在 `BeginPlay` 时向子系统注册，因此每个聊天机器人都能在会话开始时发现它，无需显式连接。

### 对话状态

对话依赖于聊天机器人会话和玩家侧音频通路的初始化。会话通过子系统建立 WebRTC 通道，并保持打开状态，直到调用 `StopSession` 或游戏实例结束。

聊天机器人提供语音状态辅助函数，例如 `GetIsTalking`, `IsListening`, `IsProcessing` （显示为 **正在思考**），以及 `IsInConversation`。在当前插件版本中， `GetIsTalking` 是可靠的播放状态辅助函数；具体行为请参阅 [对话流程](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/conversation-flow.md) 。

### 本节页面

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>运行时架构</strong><br>各组件及子系统的角色、所有权和相互关系。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/runtime-architecture.md">运行时架构</a></td></tr><tr><td><strong>会话生命周期</strong><br>会话如何启动、停止并报告连接状态，以及子系统的蓝图接口。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md">会话生命周期</a></td></tr><tr><td><strong>对话流程</strong><br>聆听、处理和说话状态；转录；以及中断。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/conversation-flow.md">对话流程</a></td></tr><tr><td><strong>事件系统</strong><br>聊天机器人和播放器组件上所有可通过蓝图绑定的委托，按类别整理。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/event-system.md">事件系统</a></td></tr></tbody></table>


---

# 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.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.
