> 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/getting-started/scene-components-reference.md).

# 场景组件参考

Convai Chatbot、Player、Object 和 Face Sync 组件的参考——它们的字段、运行时属性以及在场景中的连接方式。

本页介绍 Convai 插件提供的四个组件，供你在构建或调试场景时参考。有关添加组件的分步说明，请参阅 [添加你的第一个 Convai 角色](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/add-your-first-convai-character.md).

Convai Unreal Engine 插件为 Unreal Engine 添加了四个组件。每个组件都有独特的用途——了解它们各自的职责，可以避免最常见的连接错误。

### 组件用途

| 组件           | 类                          | 在“添加”菜单中搜索的名称                 | 附加到                 |
| ------------ | -------------------------- | ----------------------------- | ------------------- |
| Convai 聊天机器人 | `UConvaiChatbotComponent`  | `BP Convai ChatBot Component` | NPC 角色蓝图            |
| Convai 玩家    | `UConvaiPlayerComponent`   | `BP Convai Player Component`  | 玩家 Pawn 蓝图          |
| Convai 对象    | `UConvaiObjectComponent`   | `Convai Object`               | AI 应在场景中了解的任意 Actor |
| Convai 面部同步  | `UConvaiFaceSyncComponent` | `Convai Face Sync`            | NPC 角色蓝图            |

{% hint style="info" %}
**BP 与基础组件：** 搜索 `BP Convai ChatBot Component` 或 `BP Convai Player Component` 会添加封装在蓝图中的版本，该版本已预先接好按键通话输入和聊天 UI 控件。搜索 `Convai Chatbot` 或 `Convai Player` 会添加基础 C++ 组件——虽然可以正常使用，但你需要自行接好按键通话、聊天控件和音频采集。
{% endhint %}

### 组件如何连接

```mermaid
graph TD
    A["玩家 Pawn"] --> B["UConvaiPlayerComponent\n采集麦克风音频"]
    B -->|"传输音频 / 接收响应"| C["UConvaiChatbotComponent\n管理与 Convai 的对话"]
    D["NPC 角色蓝图"] --> C
    D --> E["UConvaiFaceSyncComponent\n应用面部动画数据"]
    C -->|"面部动画数据"| E
    F["任意场景 Actor"] --> G["UConvaiObjectComponent\n该关卡中的所有聊天机器人均可见"]
```

和 `UConvaiPlayerComponent` 以及 `UConvaiChatbotComponent` 通过由以下对象管理的会话相连： `UConvaiSubsystem` ——这是插件自动注册的游戏实例子系统。在大多数蓝图设置中，你无需直接引用该子系统。

### 组件详情

{% tabs %}
{% tab title="Convai 聊天机器人" %}
`UConvaiChatbotComponent` 是非玩家角色的 AI 大脑。它包含 `CharacterID` ，用于将组件关联到你在 Convai 控制面板中创建的角色。运行时，它会连接到 Convai，并接收玩家通过 `UConvaiPlayerComponent`，并将响应流式传回。

**Details（详细信息）面板中可编辑的字段：**

| 字段                              | 默认值    | 说明                                                                                                                                                                                                  |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CharacterID`                   | *（空）*  | **必填。** Convai 控制面板中的唯一 ID，用于标识此组件代表哪个角色。                                                                                                                                                           |
| `bAutoInitializeSession`        | `true` | 当 `true`时，组件会在 BeginPlay 时自动连接到 Convai。设为 `false` 即可手动调用 `StartSession()` 。                                                                                                                         |
| `InterruptVoiceFadeOutDuration` | `1.0`  | 调用 `InterruptSpeech` 时，角色语音淡出的持续时间（秒）。 `0` 会立即切断音频。请参阅 [配置角色音频](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-character-audio.md). |

**运行时值（只读）：** `CharacterName` 会在会话加载后根据角色的控制面板配置填充。它是 `BlueprintReadOnly` 属性——可在 Blueprint 中读取，但无法在 **Details（详细信息）** 面板中编辑。请在 Convai 控制面板中管理角色配置。

**实用的运行时函数（可在 Blueprint 中调用）：**

| 函数                   | 蓝图显示名称 | 返回     | 说明                               |
| -------------------- | ------ | ------ | -------------------------------- |
| `GetIsTalking()`     | 是否正在说话 | `bool` | `true` 表示角色正在说话。                 |
| `IsInConversation()` | —      | `bool` | `true` 表示存在活动的对话会话（正在聆听、处理中或说话）。 |

`IsListening()` 和 `IsProcessing()` 已在 Blueprint 中公开，但目前在插件源码中返回 `false` 。在这些函数实现之前，请使用 `GetIsTalking()` 和 `和` IsInConversation()

**以可靠地检查状态。**

| 事件                                | 说明              |
| --------------------------------- | --------------- |
| `此组件触发的 Blueprint 事件：`            | 角色已确定要执行的动作。    |
| `OnEmotionStateChangedEvent`      | 角色的情绪状态已更新。     |
| `OnCharacterDataLoadEvent_V2`     | 控制面板中的角色元数据已就绪。 |
| `OnNarrativeSectionReceivedEvent` | 已触发叙事设计章节。      |
| `OnInteractionIDReceivedEvent`    | 为新的交互分配了一个 ID。  |
| `OnInterruptedEvent`              | 角色的语音被玩家的新输入打断。 |
| `OnFailureEvent`                  | 发生了网络或身份验证错误。   |

&#x20;`CharacterID`  字段是唯一必填字段。其他字段都有可用的默认值。
{% endtab %}

{% tab title="Convai 玩家" %}
`UConvaiPlayerComponent` 代表对话中的人类参与者。它会采集麦克风音频，并将其流式传输到当前活动的 `UConvaiChatbotComponent` （对话期间）。

**“细节”面板字段：**

| 字段           | 默认值     | 说明                                              |
| ------------ | ------- | ----------------------------------------------- |
| `PlayerName` | *（空）*   | 在对话上下文中向 AI 角色显示的玩家名称。                          |
| `EndUserID`  | *（空）*   | 此玩家的持久标识符，长期记忆功能会用它跨会话回忆过去的交互。                  |
| `bMute`      | `false` | 当 `true`时，会静音麦克风输入，但不会停止会话。可在运行时切换，以将玩家静音或取消静音。 |

**实用的运行时函数（可在 Blueprint 中调用）：**

| 函数                                 | 返回                | 说明                                            |
| ---------------------------------- | ----------------- | --------------------------------------------- |
| `UnmuteStreamingAudio()`           | `bool`            | 开始将麦克风音频流式传输到当前活动的聊天机器人。                      |
| `MuteStreamingAudio()`             | `void`            | 停止流式传输音频。                                     |
| `UpdateVadBP(EnableVAD)`           | `bool`            | 启用（`true`）或停用（`false`）免提语音活动检测。成功时返回 `true` 。 |
| `SendText(ChatbotComponent, Text)` | `void`            | 向指定的聊天机器人发送文本消息，无需使用麦克风输入。                    |
| `GetIsStreaming()`                 | `bool`            | `true` 表示音频正在向聊天机器人进行流式传输。                    |
| `GetAvailableCaptureDeviceNames()` | `TArray<FString>` | 可用麦克风设备名称列表。                                  |
| `SetCaptureDeviceByIndex(Index)`   | `bool`            | 切换到指定索引对应的设备。                                 |
| `SetCaptureDeviceByName(Name)`     | `bool`            | 切换到指定名称对应的设备。                                 |

一个 `UConvaiPlayerComponent` 挂载在玩家 Pawn 上，即可与关卡中的任意 `UConvaiChatbotComponent` 进行对话。

**VAD 设置（beta.20+）：** 可在项目级别的以下位置配置语音活动检测阈值： **编辑 > 项目设置 > 插件 > Convai > 音频设置 | VAD** 使用 `FConvaiVADSettings` 字段： `Confidence` （0.0–1.0，默认值为 0.7）、 `StartSecs` （默认值为 0.2）、 `StopSecs` （默认值为 2.2），以及 `MinVolume` （0.0–1.0，默认值为 0.6）。将 `bUseServerDefault` 设为 `true` 即可使用服务器端默认值。

**预配置的 Pawn：** `ConvaiPlayerWithVoiceActivation` (`Content/Core/ConvaiPlayerWithVoiceActivation`）是一个可直接使用的玩家 Pawn，支持语音激活采集。若要实现免提输入且不手动调用 `UpdateVadBP(true)` ，可将其用作起点。
{% endtab %}

{% tab title="Convai 对象" %}
`UConvaiObjectComponent` 用于标记场景中的 Actor，使关卡中的每个 Convai 聊天机器人都能通过名称引用它。将该组件附加到门、开关、物品、房间或任何 AI 角色需要能够命名、描述或与之交互的对象上。

**“细节”面板字段：**

| 字段                  | 默认值     | 说明                                                                                                                 |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `ObjectEntry`       | —       | 对象的身份信息，以内联字段的形式显示在 **详情** 面板中。必须设置 **Name** (**（必填）** ——AI 在对话和操作中用来指代此对象的名称）以及 **Description** （包含在角色上下文中的简短介绍）。 |
| `TrackedProperties` | *（空数组）* | `UPROPERTY` 值，以便监视父 Actor 中的这些值。被跟踪的值发生变化时，更新会自动推送到所有聊天机器人。                                                        |

该组件为每个对象提供：

* **身份信息** —— **Name** 和 **Description** 字段（位于 `ObjectEntry`中），这些字段会显示在角色上下文中。
* **实时状态** —— `TrackedProperties` 条目，用于监视 `UPROPERTY` Actor 上的值，并在它们发生变化时向聊天机器人推送更新。
  {% endtab %}

{% tab title="Convai 面部同步" %}
`UConvaiFaceSyncComponent` 负责 NPC 上基于混合形状的口型同步和面部动画。它接收由 `UConvaiChatbotComponent` 预先计算的面部动画数据，并使其与角色的语音音频同步，逐帧应用。

**“细节”面板字段：**

| 字段            | 默认值            | 说明                               |
| ------------- | -------------- | -------------------------------- |
| `LipSyncMode` | MetaHuman 混合形状 | 选择混合形状目标。必须与角色的骨架绑定相匹配。可用值请参阅下表。 |

**LipSyncMode 的值：**

| 显示名称           | 枚举值                               | 适用对象                                      |
| -------------- | --------------------------------- | ----------------------------------------- |
| 关闭             | `EC_LipSyncMode::Off`             | 完全禁用面部同步。                                 |
| 自动             | `EC_LipSyncMode::Auto`            | 允许插件根据可用数据选择模式。                           |
| 基于 Viseme      | `EC_LipSyncMode::VisemeBased`     | 使用 OVR Viseme（15 种形状）的自定义骨架。              |
| MetaHuman 混合形状 | `EC_LipSyncMode::BS_MHA`          | MetaHuman 角色和 Reallusion CC5 角色。 **（默认）** |
| ARKit 混合形状     | `EC_LipSyncMode::BS_ARKit`        | CC4 角色。                                   |
| CC4 扩展混合形状     | `EC_LipSyncMode::BS_CC4_Extended` | Reallusion CC4 角色。                        |
| {% endtab %}   |                                   |                                           |
| {% endtabs %}  |                                   |                                           |

### 蓝图封装组件

插件在 `Content/`中提供了各组件的蓝图封装版本。请使用这些组件，而不是直接使用原始 C++ 组件——它们开箱即用地集成了按键通话输入绑定、聊天小组件和音频采集功能。

| 资源                                                          | Content 路径                                 | 包含内容                                                             |
| ----------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------- |
| `BP_ConvaiChatbotComponent` (`BP Convai ChatBot Component`) | `ConvaiConveniencePack/ConvaiBPComponent/` | `UConvaiChatbotComponent` 已预先接入按键通话功能和 `Chat_WB`.                |
| `BP_ConvaiPlayerComponent` (`BP Convai Player Component`)   | `ConvaiConveniencePack/ConvaiBPComponent/` | `UConvaiPlayerComponent` 已预先接入按键通话功能、 `Chat_WB`以及 `UISelection`. |
| `BP_ConvaiSamplePlayer`                                     | `ConvaiConveniencePack/Sample/`            | 示例玩家 Pawn，附带 `BP_ConvaiPlayerComponent` 。                        |
| `BP_SampleGameMode`                                         | `ConvaiConveniencePack/Sample/`            | 用于设置 `BP_ConvaiSamplePlayer` 为默认 Pawn 的游戏模式。                     |
| `BP_Convai3DWidgetComponent` / `WBP_3DChatWidget`           | `ConvaiConveniencePack/3DWidget/`          | 游戏世界中的 3D 聊天 UI 小组件。                                             |
| `Chat_WB` / `MicSettings_WB`                                | `Widgets/`                                 | 屏幕空间聊天叠加层和麦克风设置面板。                                               |
| `ConvaiPlayerWithVoiceActivation`                           | `Core/`                                    | 默认启用语音激活（VAD）的玩家 Pawn。                                           |

{% hint style="warning" %}
`ConvaiBasePlayer` 和 `ConvaiBaseCharacter` 位于 `Content/Core/` 已弃用。请将类重新指定父类为标准的 Character 或 Pawn，并添加 `BP_ConvaiPlayerComponent` 或 `BP_ConvaiChatbotComponent` 来替代。
{% endhint %}

### 后续步骤

{% content-ref url="/pages/1f909841a8dc37e6adc6461224d8b1968155a87c" %}
[验证你的设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/validate-your-setup.md)
{% endcontent-ref %}

{% content-ref url="/pages/9b983ed32e78e3fecceef1f1ca84663abe05edca" %}
[配置对话输入](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-conversation-input.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/getting-started/scene-components-reference.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.
