> 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)），该小部件已自动包含在内。它会在 Play 模式下自动显示——无需额外设置。

#### 切换覆盖层样式

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

要更改样式：

1. 选中 **Convai Player** 玩家 Pawn 蓝图中的组件。
2. 在 **详情** 面板中，找到 `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 %}

#### 打开角色蓝图

打开已经包含以下内容的 NPC 角色蓝图 `BP_ConvaiChatbotComponent` 已附加。
{% 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" %}
进入 Play 模式并与角色对话。3D 聊天面板会出现在角色上方，并在对话进行时更新转录文本。
{% endhint %}

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

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

{% stepper %}
{% step %}

#### 创建 Widget 蓝图

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

{% step %}

#### 绑定转录委托

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

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

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

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

### 故障排查

#### 聊天覆盖层在 Play 模式下不显示

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

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

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

**验证：** 进入 Play 模式并确认聊天覆盖层出现在视口中。

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

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

**原因：** 聊天机器人会话尚未开始，或者 Character ID 无效，导致没有对话数据通过该会话传递。

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

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

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

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

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

**解决方法：** 设置 `UISelection` 为 `0` on `BP_ConvaiPlayerComponent` 以隐藏屏幕空间覆盖层，只保留 3D 小部件处于活动状态。

**验证：** 进入 Play 模式并确认只有角色上方的 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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.