> 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 插件围绕一小组运行时类型构建，每个类型各自承担单一职责。了解每种类型的作用——以及它们之间的关系——有助于你配置角色、处理事件，并为你的项目扩展插件。 从 **运行时架构** 如果你刚接触插件内部实现。等你需要了解某个特定系统——会话管理、对话状态或 Blueprint 事件——时，再阅读其余页面。 ### 运行时模型 在关卡中的大多数 Convai 交互都涉及一个 chatbot 组件和一个 player 组件。两者都继承自共享的抽象基类 `UConvaiConversationComponent`，这为它们提供了通用的对话事件接口。对象和面部同步行为使用单独的组件类型，而 `UConvaiSubsystem` 是一个 `UGameInstanceSubsystem`，而不是一个 `Actor` 组件。 | 运行时类型 | Blueprint 显示名称 | 职责 | | -------------------------- | -------------------- | ------------------------------------------- | | `UConvaiChatbotComponent` | **Convai Chatbot** | 表示一个由 AI 驱动的角色。拥有角色 ID、会话状态、情绪状态、环境数据和动作队列。 | | `UConvaiPlayerComponent` | **Convai 播放器** | 表示玩家侧参与者。拥有麦克风采集、音频流传输、按键通话状态和凝视注意力。 | | `UConvaiObjectComponent` | **Convai 对象组件** | 注册场景中的对象或道具，以便所有 chatbot 都能在动作和上下文中通过名称引用它。 | | `UConvaiFaceSyncComponent` | **Convai Face Sync** | 根据角色传入的音频驱动混合形状或 viseme 动画。 | | `UConvaiSubsystem` | **Convai Subsystem** | 游戏实例子系统。管理底层 WebRTC 连接、组件注册和全局连接状态。 | 该子系统是单例——它会随游戏实例自动启动，并始终可通过 Blueprint 的 **获取游戏实例 → 获取子系统（Convai Subsystem）** 调用链。 ### 各部分如何协同工作 chatbot 组件和 player 组件在 Blueprint 中不会直接彼此通信。它们都依赖于子系统，而实际传输层由子系统拥有。当玩家说话时，音频会从 `UConvaiPlayerComponent` 通过子系统传输到 Convai。角色的音频响应会到达子系统，并被转发到当前角色会话。 ```mermaid graph TD P["Convai 玩家组件\n(麦克风 → PCM)"] C["Convai Chatbot 组件\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` 时向子系统注册，因此每个 chatbot 都能在会话开始时发现它，而无需显式连线。 ### 对话状态 对话依赖于 chatbot 会话以及玩家侧音频路径已初始化。会话通过子系统建立 WebRTC 通道，并保持打开状态，直到 `StopSession` 被调用或游戏实例结束。 chatbot 公开了诸如以下的语音状态辅助函数： `GetIsTalking`, `IsListening`, `IsProcessing` （显示为 **是否正在思考**），以及 `IsInConversation`。在当前插件版本中， `GetIsTalking` 是可靠的播放状态辅助函数；请参见 [对话流程](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/conversation-flow.md) 了解确切行为。 ### 本节中的页面
运行时架构
每个组件与子系统之间的职责、归属和关系。		运行时架构
会话生命周期
会话如何启动、停止并报告连接状态——以及子系统 Blueprint 接口。		会话生命周期
对话流程
监听、处理中和交谈状态；转录；以及中断。		对话流程
事件系统
chatbot 和 player 组件上的每个可由 Blueprint 赋值的委托，按类别组织。		事件系统
--- # 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=&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.