> 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 角色](/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 Chatbot   | `UConvaiChatbotComponent`  | `BP Convai ChatBot 组件` | NPC 角色蓝图            |
| Convai 播放器       | `UConvaiPlayerComponent`   | `BP Convai Player 组件`  | 玩家 Pawn 蓝图          |
| Convai 对象        | `UConvaiObjectComponent`   | `Convai 对象`            | AI 应该了解的场景中任意 Actor |
| Convai Face Sync | `UConvaiFaceSyncComponent` | `Convai Face Sync`     | NPC 角色蓝图            |

{% hint style="info" %}
**BP 与原生组件：** 搜索 `BP Convai ChatBot 组件` 或 `BP Convai Player 组件` 会添加蓝图封装版本，它预先连接了按住说话输入和聊天 UI 小部件。搜索 `Convai Chatbot` 或 `Convai 播放器` 会添加原生 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 Chatbot" %}
`UConvaiChatbotComponent` 是非玩家角色的 AI 大脑。它保存 `CharacterID` 将该组件链接到你在 Convai 控制面板中创建的角色的内容。运行时它会连接到 Convai，接收来自 `UConvaiPlayerComponent`的玩家语音或文本，并将响应流式传回。

**可编辑的详情面板字段：**

| 字段                              | 默认值    | 说明                                                                                                                                                                         |
| ------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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` ——在蓝图中可读，但在 **详情** 面板中不可编辑。在 Convai 控制面板中管理角色配置。

**有用的运行时函数（可由蓝图调用）：**

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

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

**此组件触发的蓝图事件：**

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

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

{% tab title="Convai 播放器" %}
`UConvaiPlayerComponent` 代表对话中的人类参与者。它捕获麦克风音频并将其流式传输到活动的 `UConvaiChatbotComponent` 在对话期间。

**详情面板字段：**

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

**有用的运行时函数（可由蓝图调用）：**

| 函数                                 | 返回                | 说明                                              |
| ---------------------------------- | ----------------- | ----------------------------------------------- |
| `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** using `FConvaiVADSettings` 字段： `置信度` （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`       | —       | 对象的身份，在 **详情** 面板中显示为内联字段。设置 **名称** (**必需** ——AI 在对话和动作中用来指代此对象的名称）和 **说明** （包含在角色上下文中的简短简介）。 |
| `TrackedProperties` | *（空数组）* | `UPROPERTY` 要监控的父 Actor 上的值。当某个受监控值发生变化时，更新会自动推送给所有聊天机器人。                                     |

该组件为每个对象提供：

* **身份** —— **名称** 和 **说明** 的字段， `ObjectEntry`，这些内容会出现在角色上下文中。
* **实时状态** — `TrackedProperties` 监控 `UPROPERTY` Actor 上的值，并在它们变化时向聊天机器人推送更新。
  {% endtab %}

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

**详情面板字段：**

| 字段            | 默认值                   | 说明                                    |
| ------------- | --------------------- | ------------------------------------- |
| `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 Extended Blendshapes | `EC_LipSyncMode::BS_CC4_Extended` | Reallusion CC4 角色。                        |
| {% endtab %}             |                                   |                                           |
| {% endtabs %}            |                                   |                                           |

### 蓝图封装

插件在 `Content/`中随附了每个组件的蓝图封装版本。请使用这些版本替代原生 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/`            | 带有 `BP_ConvaiPlayerComponent` 的示例玩家 Pawn。                       |
| `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 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.