> 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 插件提供的四个组件的参考。请在构建或调试场景时使用它。有关添加组件的逐步演示，请参见 [添加你的第一个 Convai 角色](/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 组件` | NPC 角色蓝图            |
| Convai Player | `UConvaiPlayerComponent`   | `BP Convai Player 组件`  | 玩家 Pawn 蓝图          |
| Convai Object | `UConvaiObjectComponent`   | `Convai Object`        | AI 应该了解的场景内任意 Actor |
| Convai 面部同步   | `UConvaiFaceSyncComponent` | `Convai 面部同步`          | NPC 角色蓝图            |

{% hint style="info" %}
**BP 与裸组件：** 搜索 `BP Convai ChatBot 组件` 或 `BP Convai Player 组件` 会添加 Blueprint 封装版本，其中预先连接了按键说话输入和聊天 UI 小组件。搜索 `Convai 聊天机器人` 或 `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对场景中的所有 chatbot 可见"]
```

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

### 组件详情

{% 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` 会立即切断音频。请参见 [配置角色音频](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-character-audio.md). |

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

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

| 函数                   | Blueprint 显示名称 | 返回值    | 描述                         |
| -------------------- | -------------- | ------ | -------------------------- |
| `GetIsTalking()`     | 正在说话           | `bool` | `true` ，当角色正在说话时。          |
| `IsInConversation()` | —              | `bool` | `true` 当存在活动会话（监听、处理或说话）时。 |

`IsListening()` 和 `IsProcessing()` 在 Blueprint 中公开，但目前返回 `false` 在插件源代码中。请使用 `GetIsTalking()` 和 `IsInConversation()` 进行可靠的状态检查，直到这些函数实现为止。

**该组件触发的 Blueprint 事件：**

| 事件                                | 描述                 |
| --------------------------------- | ------------------ |
| `OnActionReceivedEvent_V2`        | 角色已确定要执行的动作。       |
| `OnEmotionStateChangedEvent`      | 角色的情绪状态已更新。        |
| `OnCharacterDataLoadEvent_V2`     | 来自控制面板的角色元数据已准备就绪。 |
| `OnNarrativeSectionReceivedEvent` | 一个叙事设计段落被触发。       |
| `OnInteractionIDReceivedEvent`    | 一个新交互已分配 ID。       |
| `OnInterruptedEvent`              | 角色的语音被新的玩家输入打断。    |
| `OnFailureEvent`                  | 发生了网络或身份验证错误。      |

该 `CharacterID` 字段是唯一必需字段。所有其他字段都有可用的默认值。
{% endtab %}

{% tab title="Convai Player" %}
`UConvaiPlayerComponent` 表示对话中的人类参与者。它会捕获麦克风音频，并将其流式传输到当前活动的 `UConvaiChatbotComponent` ，在对话过程中。

**Details 面板字段：**

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

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

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

一个 `UConvaiPlayerComponent` 在 player pawn 上的一个组件可以与任何 `UConvaiChatbotComponent` 关卡中的

**VAD 设置（beta.20+）：** 语音活动检测阈值可在整个项目范围内配置于 **Edit > Project Settings > Plugins > Convai > Audio Settings | 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 Object" %}
`UConvaiObjectComponent` 会将场景中的一个 Actor 标记出来，使关卡中的每个 Convai chatbot 都能按名称引用它。将其附加到门、开关、物品、房间或任何你的 AI 角色应能够命名、描述或交互的对象上。

**Details 面板字段：**

| 字段                  | 默认值     | 描述                                                                                                 |
| ------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `ObjectEntry`       | —       | 对象的身份信息，显示为 **详细信息** 面板中的内联字段。设置 **名称** (**必填** ——AI 在对话和动作中用来指代该对象的名称）以及 **描述** （包含在角色上下文中的简短简介）。 |
| `TrackedProperties` | *（空数组）* | `UPROPERTY` 要监视的父 Actor 上的值。当被跟踪的值发生变化时，更新会自动推送给所有 chatbots。                                       |

该组件为每个对象提供：

* **身份信息** —— **名称** 和 **描述** 的字段 `ObjectEntry`，它们会出现在角色的上下文中。
* **实时状态** — `TrackedProperties` 用于监控 `UPROPERTY` Actor 上的值，并在它们变化时将更新推送给 chatbots。
  {% endtab %}

{% tab title="Convai 面部同步" %}
`UConvaiFaceSyncComponent` 驱动 NPC 上基于 blendshape 的口型同步和面部动画。它从 `UConvaiChatbotComponent` 接收预先计算好的面部动画数据，并与角色语音音频同步逐帧应用。

**Details 面板字段：**

| 字段            | 默认值                   | 描述                                    |
| ------------- | --------------------- | ------------------------------------- |
| `LipSyncMode` | MetaHuman Blendshapes | 选择 blendshape 目标。必须与角色的骨骼绑定匹配。可用值见下表。 |

**LipSyncMode 值：**

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

### Blueprint 包装器

插件在 `Content/`中提供了每个组件的 Blueprint 封装版本。请使用这些版本而不是裸 C++ 组件——它们开箱即包含按键说话输入绑定、聊天小组件集成和音频捕获。

| 资源                                                   | Content 路径                                 | 包含内容                                                            |
| ---------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------- |
| `BP_ConvaiChatbotComponent` (`BP Convai ChatBot 组件`) | `ConvaiConveniencePack/ConvaiBPComponent/` | `UConvaiChatbotComponent` 预先连接了按键说话和 `Chat_WB`.                 |
| `BP_ConvaiPlayerComponent` (`BP Convai Player 组件`)   | `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" %}
[验证你的设置](/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" %}
[配置对话输入](/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 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/getting-started/scene-components-reference.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.