添加聊天 UI

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

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

屏幕空间叠加层

屏幕空间叠加层包含在 BP_ConvaiPlayerComponent。当你添加了 BP Convai Player Component 到你的玩家 Pawn 中时（见 添加您的第一个 Convai 角色），小部件已包含其中。它会在播放模式中自动显示——无需额外设置。

切换叠加层样式

内置叠加层是 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 小部件添加到角色

1

打开角色蓝图

打开已经附加了 BP_ConvaiChatbotComponent 的 NPC 角色蓝图。

2

添加 3D Widget 组件

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

3

定位小部件

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

4

编译并保存

单击 编译 是位于 保存 在蓝图编辑器工具栏中。

进入播放模式并对角色说话。3D 聊天面板会出现在角色上方，并在对话进行时随转录内容更新。

替换为自定义小部件

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

1

创建一个 Widget 蓝图

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

2

绑定转录委托

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

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

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

OnTranscriptionReceivedDelegate 可用于聊天机器人组件（角色回复）和玩家组件（玩家语音）。绑定到 聊天机器人组件 以获取角色所说内容，并绑定到 玩家组件 以获取玩家所说内容。参见 事件系统 以查看完整的委托签名。

3

禁用内置叠加层

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

故障排查

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

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

原因： 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 面板可见——视口角落不会出现第二个叠加层。

下一步

验证你的设置