> 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 角色](/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 Player** 组件，位于你的玩家 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 项目——在这些项目中，屏幕空间覆盖层不适合沉浸式布局。

{% 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** ，位于 **组件** 面板。在 **Details** 面板中，调整 **Transform > Location** 以将小部件放置在角色头顶上方。对于标准身高的角色， `(X=0, Y=0, Z=200)` 大致会将面板放在头顶上方。
{% endstep %}

{% step %}

#### 编译并保存

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

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

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

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

{% stepper %}
{% step %}

#### 创建一个小部件蓝图

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

{% step %}

#### 绑定转录委托

在你的小部件事件图表中（或在拥有它的 Actor 蓝图中），绑定到 `OnTranscriptionReceivedDelegate` 在 `UConvaiChatbotComponent`:

* `Speaker` ——产生语音的组件（聊天机器人或玩家）。
* `监听器` ——接收转录内容的组件。
* `转录` ——此时该语句的转录文本。
* `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` 在 `BP_ConvaiPlayerComponent` 以隐藏内置覆盖层，使其不会与你的自定义小部件重叠。
{% endstep %}
{% endstepper %}

### 故障排除

#### 播放模式下聊天覆盖层不显示

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

**原因：** `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 聊天机器人** 组件，或者在 `StartSession()` 中提前调用 **角色 ID** 在对话开始前于蓝图中。确认

**验证：** 与你在 Convai 控制台中的角色相匹配。

#### 覆盖层和 3D 小部件同时显示

**症状：** 屏幕空间覆盖层和漂浮的 3D 面板都可见，导致转录显示重复。

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

**修复：** 设置 `UISelection` 为 `0` 在 `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 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.