> 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

将内置聊天覆盖层添加到场景中，在界面样式之间切换，将 3D 场景内小部件附加到角色上，或将其替换为自定义小部件。

Convai 插件提供两种聊天 UI 选项：一种是在视口中显示的屏幕空间叠加层，另一种是在关卡中悬浮于角色上方的 3D 世界内面板。两者都会显示对话记录和按住说话反馈。叠加层已集成在 `BP_ConvaiPlayerComponent`中；3D 面板则是一个独立组件，需要时可自行添加。

### 屏幕空间叠加层

屏幕空间叠加层已包含在 `BP_ConvaiPlayerComponent`中。当你将 `BP Convai Player Component` 添加到玩家 Pawn 后（请参阅 [添加你的第一个 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)），该控件便已包含其中。它会在 Play 模式下自动显示，无需额外设置。

#### 切换叠加层样式

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

要更改样式：

1. 在玩家 Pawn 蓝图中选择 **Convai Player** 组件。
2. 在 **Details** 面板中，在 `UISelection` 下找到该变量，所属类别为 **Convai** 。此变量定义在 `BP_ConvaiPlayerComponent` 上，纯 `UConvaiPlayerComponent` C++ 组件中没有此变量。
3. 将 `UISelection` 设为 `1`, `2`、 `3` 或 `0` 即可切换样式。将其设为

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

所有样式显示相同的对话数据和按住说话控件。只有视觉呈现方式不同。

### 3D 世界内聊天小组件

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

{% embed url="<https://www.youtube.com/watch?v=rUTrXkH1wfg>" %}
在 VR 项目中添加 3D 小组件和免提对话
{% endembed %}

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

{% stepper %}
{% step %}

#### 打开角色蓝图

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

{% step %}

#### 添加 3D Widget 组件

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

{% step %}

#### 调整小组件的位置

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

{% step %}

#### 编译并保存

在蓝图编辑器工具栏中点击 **编译** 和 **保存** 。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
进入运行模式并与角色交谈。3D 聊天面板会显示在角色上方，并随着对话进行而更新转录内容。
{% endhint %}

### 替换为自定义控件

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

{% stepper %}
{% step %}

#### 创建 Widget Blueprint

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

{% step %}

#### 绑定转录委托

在控件的事件图表中（或所属 Actor 的 Blueprint 中），绑定到 `OnTranscriptionReceivedDelegate` ，该委托位于 `UConvaiChatbotComponent`:

* `Speaker` — 生成语音的组件（聊天机器人或玩家）。
* `Listener` — 接收转录内容的组件。
* `Transcription` — 话语进行到此处时的转录文本。
* `IsTranscriptionReady` — 当文本可以渲染时为 `true` 。
* `IsFinal` — 当这是该话语的最后一次更新时为 `true` 。使用此标志将这一行提交到显示界面，并清除任何“正在输入...”指示。

将每条最终转录内容追加到显示面板，以累积对话历史记录。

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

{% step %}

#### 禁用内置叠加层

将 `UISelection` 设置为 `0` ，并在 `BP_ConvaiPlayerComponent` 上设置，以隐藏内置叠加层，避免其与自定义控件重叠。
{% endstep %}
{% endstepper %}

### 故障排查

#### 在 Play 模式下未显示聊天叠加层

**症状：** Play 模式已启动，但看不到聊天控件。

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

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

**验证：** 进入游戏模式，并确认聊天叠加层显示在视口中。

#### 3D 小组件可见，但没有显示文本

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

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

**修复：** 确认 `bAutoInitializeSession` 在 `true` 上 **Convai Chatbot** 组件，或在对话开始前于蓝图中调用 `StartSession()` 。确认 **Character ID** 与 Convai 控制面板中的某个角色相匹配。

**验证：** 与角色交谈，并确认 3D 面板会更新并显示转录文本。

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

**症状：** 屏幕空间叠加层和浮动 3D 面板同时可见，导致转录内容重复显示。

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

**修复：** 将 `UISelection` 设置为 `0` ，以便在 `BP_ConvaiPlayerComponent` 上隐藏屏幕空间叠加层，仅保留 3D 小组件。

**验证：** 进入游戏模式，并确认角色上方只显示 3D 面板——视口角落不再出现第二个叠加层。

### 后续步骤

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


---

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