> 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/add-the-chat-ui.md).

# 添加聊天 UI

Convai 插件提供两种聊天 UI 选项：一种是显示在视口中的屏幕空间叠加层，另一种是在场景中悬浮在关卡里角色上方的 3D 面板。两者都会显示对话转录和按键通话反馈。该叠加层内置于 `BP_ConvaiPlayerComponent`；3D 面板是一个需要时才添加的独立组件。

### 屏幕空间叠加层

屏幕空间叠加层包含在 `BP_ConvaiPlayerComponent`。当你添加了 `BP Convai Player Component` 到你的玩家 Pawn 中时（见 [添加您的第一个 Convai 角色](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/add-your-first-convai-character.md)），小部件已包含其中。它会在播放模式中自动显示——无需额外设置。

#### 切换叠加层样式

内置叠加层是 `Chat_WB` 小部件（`Content/Widgets/Chat_WB`). `BP_ConvaiPlayerComponent` 提供一个 `UISelection` 变量，用于选择小部件切换器显示哪种叠加层样式。插件附带三种背景纹理： `UI_CBFV1`, `UI_CBFV2`，以及 `UI_CBFV3` 在 `Content/Widgets/Images/`.

要更改样式：

1. 选择 **Convai 玩家** 组件，在你的玩家 Pawn 蓝图中。
2. 在 **Details** 面板中，找到 `UISelection` 在 **Convai** 类别。该变量定义在 `BP_ConvaiPlayerComponent` ——它不会出现在纯粹的 `UConvaiPlayerComponent` C++ 组件上。
3. 设置 `UISelection` 到 `1`, `2`，或 `3` 来切换样式。将其设为 `0` 即可完全隐藏叠加层。

| 值   | 效果                        |
| --- | ------------------------- |
| `0` | 叠加层已隐藏——不会显示屏幕空间聊天小部件。    |
| `1` | 样式 1——使用 `UI_CBFV1` 背景纹理。 |
| `2` | 样式 2——使用 `UI_CBFV2` 背景纹理。 |
| `3` | 样式 3——使用 `UI_CBFV3` 背景纹理。 |

所有样式都显示相同的对话数据和按键通话控件。仅视觉呈现不同。

### 3D 场景内聊天小部件

3D 小部件（`BP_Convai3DWidgetComponent` / `WBP_3DChatWidget`，位于 `ConvAI > ConvaiConveniencePack > 3DWidget`）会在世界空间中于角色上方渲染一个悬浮的对话面板。这适用于开放环境中玩家面对不同角色、需要分别查看每个角色的发言，适用于将显示内容作为环境一部分的自助终端安装，以及 VR、MR、AR 和其他 XR 项目，因为屏幕空间叠加层不适合这种沉浸式布局。

#### 将 3D 小部件添加到角色

{% stepper %}
{% step %}

#### 打开角色蓝图

打开已经附加了 `BP_ConvaiChatbotComponent` 的 NPC 角色蓝图。
{% endstep %}

{% step %}

#### 添加 3D Widget 组件

在 **组件** 面板中，点击 **添加**。搜索 `BP Convai 3D Widget Component` 并选择它。这会将 `BP_Convai3DWidgetComponent` 添加到蓝图中。
{% endstep %}

{% step %}

#### 定位小部件

选择 **BP Convai 3D Widget Component** 在 **组件** 面板。在 **Details** 面板中，调整 **Transform > Location** 以将小部件放置在角色头顶上方。对于标准身高的角色， `(X=0, Y=0, Z=200)` 会将面板大致放在头部上方。
{% endstep %}

{% step %}

#### 编译并保存

单击 **编译** 是位于 **保存** 在蓝图编辑器工具栏中。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
进入播放模式并对角色说话。3D 聊天面板会出现在角色上方，并在对话进行时随转录内容更新。
{% endhint %}

### 替换为自定义小部件

如果内置叠加层和 3D 面板都不符合你的项目 UI 设计，可以将一个完全自定义的小部件连接到转录委托：

{% stepper %}
{% step %}

#### 创建一个 Widget 蓝图

在 **内容浏览器**，右键单击并选择 **用户界面 > Widget 蓝图**。设计你的自定义聊天显示——滚动框、字幕栏，或任何你需要的布局。
{% endstep %}

{% step %}

#### 绑定转录委托

在你的小部件事件图中（或在所属 Actor 蓝图中），绑定到 `OnTranscriptionReceivedDelegate` 在 `UConvaiChatbotComponent`:

* `说话者` ——生成语音的组件（聊天机器人或玩家）。
* `接收者` ——接收转录内容的组件。
* `转录` ——当前发言阶段的转录文本。
* `IsTranscriptionReady` — `true` 当文本已准备好渲染时。
* `IsFinal` — `true` 当这是该发言的最后一次更新时。使用此标志将该行提交到显示区，并清除任何“typing...”指示器。

将每条最终转录附加到你的显示面板中，以构建对话历史。

`OnTranscriptionReceivedDelegate` 可用于聊天机器人组件（角色回复）和玩家组件（玩家语音）。绑定到 **聊天机器人组件** 以获取角色所说内容，并绑定到 **玩家组件** 以获取玩家所说内容。参见 [事件系统](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/event-system.md) 以查看完整的委托签名。
{% endstep %}

{% step %}

#### 禁用内置叠加层

设置 `UISelection` 到 `0` on `BP_ConvaiPlayerComponent` 以隐藏内置叠加层，使其不会与你的自定义小部件重叠。
{% endstep %}
{% endstepper %}

### 故障排查

#### 聊天叠加层在播放模式中未出现

**症状：** 播放模式已启动，但没有可见的聊天小部件。

**原因：** `UISelection` 被设置为 `0`，或者玩家 Pawn 使用的是纯粹的 `UConvaiPlayerComponent` （C++ 组件），而不是 `BP Convai Player Component` （包含该小部件的蓝图包装器）。

**修复：** 请确认 `UISelection` 被设置为 `1`, `2`，或 `3` 在 **Convai 玩家** 组件。确认玩家 Pawn 是使用 `BP Convai Player Component` ——如果添加的是纯 C++ 组件，请将其替换为蓝图包装器。

**验证：** 进入播放模式并确认聊天叠加层出现在视口中。

#### 3D 小部件可见但不显示文本

**症状：** 悬浮面板出现在角色上方，但在对话过程中始终为空。

**原因：** 聊天机器人会话尚未启动，或者 Character ID 无效，因此没有对话数据流经该会话。

**修复：** 请确认 `bAutoInitializeSession` 为 `true` 在 **Convai 聊天机器人** 组件，或者调用 `StartSession()` 在对话开始前在蓝图中。确认 **角色 ID** 与你在 Convai 控制台中的某个角色匹配。

**验证：** 对角色说话，并确认 3D 面板会随转录文本更新。

#### 叠加层和 3D 小部件同时显示

**症状：** 屏幕空间叠加层和悬浮的 3D 面板都可见，造成重复的转录显示。

**原因：** `BP_Convai3DWidgetComponent` 已添加到角色，但未禁用玩家 Pawn 上的屏幕空间叠加层。

**修复：** 设置 `UISelection` 到 `0` on `BP_ConvaiPlayerComponent` 以隐藏屏幕空间叠加层，只保留 3D 小部件处于活动状态。

**验证：** 进入播放模式并确认只有角色上方的 3D 面板可见——视口角落不会出现第二个叠加层。

### 下一步

{% 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 %}


---

# 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/add-the-chat-ui.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.