使用 Convai 调试覆盖层检查角色

打开游戏内覆盖层，查看 Convai 角色当前拥有的上下文、事实、周围文本和动作队列。

当角色忽略指令、走向错误的物体，或像从未收到你发送的某个事实一样作答时，最快找出原因的方法不是看你自己的 Blueprint 图，而是看角色实际知道什么。Convai 调试叠加层是一个游戏内面板，它会实时显示角色收到的每个上下文状态、事实和环境句子，以及其当前行动队列。本页将向你展示如何将其开启、选择角色，并结合一个真实问题来读取这些面板。

先决条件

• Convai Unreal Engine 插件已安装，并且至少有一个 UConvaiChatbotComponent 被放置在关卡中。
• 你正在运行编辑器、在编辑器中运行（PIE），或开发版构建。除非你启用 允许在 Shipping 构建中使用 （参见 Convai Debug Overlay 参考).

启用叠加层

按 Ctrl+Alt+K 在 Play In Editor 或开发版构建中。如果某个文本字段当前拥有键盘焦点，该组合键会被忽略——请先点击视口。

你也可以通过控制台切换叠加层：

Convai.DebugOverlay

按键组合和控制台命令都会打开同一个叠加层，任意一种方式再次触发都可将其关闭。

默认按键是 K。如需使用其他按键，或允许在 Shipping 构建中显示叠加层，请打开 项目设置 > 插件 > Convai 并修改 切换键（配合 Ctrl+Alt） 或 允许在 Shipping 构建中使用 在以下位置 调试覆盖层。叠加层本身没有单独的开关——切换按键和控制台命令就是全部界面。

未选择角色时，标题显示 Convai 调试 — 无角色。一旦选择角色，标题会显示它的名称、它是在说话还是空闲，以及它正在看什么，例如 守卫 · 正在说话 · 正在看向 Crate_03.

选择要检查的角色或对象

叠加层会跟踪每个已注册角色以及每个已注册 UConvaiObjectComponent 在关卡中的目标，并在世界空间中用每个角色或对象上方的 ◆ 以及每个已命名、已启用的移动点上方的 ◇ 进行标记。

使用键盘循环选择：

• PgUp / PgDn — 切换到上一个或下一个项目。
• Shift + PgUp / PgDn — 在循环角色和循环对象之间切换。

所选角色的面板会填充在左侧，其行动队列和结果横幅会在其上方的世界空间中显示。

围绕一个问题阅读这些面板

每个面板都回答关于角色所知内容的不同问题。例如，要找出角色在被要求时为什么没有走到箱子旁：

1. 选择角色并检查 周围环境 箱子的条目。 — 已到达 表示角色上一次前往它的移动已完成； — 无路径 表示导航系统找不到路径； （待刷新） 表示更新仍在批处理中，尚未发送到 Convai。
2. 检查箱子所在行，查看角色接收到的关于它的原文句子——这是逐字的环境文本，不是摘要，因此你可以准确看到 AI 被告知了什么。
3. 检查角色上方的行动队列。一个 ▶ 表示当前正在执行的动作， · 表示其后的排队动作，而 ■ 正在取消 · 表示一个正在被取消的动作。动作完成后会显示 2.5 秒的结果横幅，内容为 <action> — 完成, <action> — 失败（<note>），或 <action> — 中止（<note>）.
4. 检查 上下文状态 和 事实 查找任何本应影响该决策的状态或事实。每个上下文状态行都有一个脉冲点：红色表示该状态已设置为响应 总是，琥珀色表示 Auto，灰色表示 从不 ——某个状态呈灰色脉冲，就解释了为什么角色从未对它作出反应。

事实 和 事件 在没有内容可显示时会自动折叠，因此它们未出现在面板中本身就很有信息。 事件 列出最近六个已提交事件，以及为下一次刷新暂存的内容或作为一次性发送的内容。

有关面板、标签和图形符号的完整列表，请参见 Convai Debug Overlay 参考.

验证叠加层正在显示实时数据

触发你正在调试的行为——发送上下文更新、移动角色，或等待一个动作完成——并确认相关面板会在一两秒内更新。

当你触发事件时会更新的面板，说明叠加层读取的是所选角色的实时状态，而不是缓存快照。

故障排查

叠加层未出现

症状： 按下 Ctrl+Alt+K 或运行 Convai.DebugOverlay 没有任何反应。

原因： 你当前处于 Shipping 或 Test 构建，并且 允许在 Shipping 构建中使用 处于关闭状态，或者某个文本字段当前拥有键盘焦点并吞掉了该按键组合。

解决方法： 点击视口以清除文本字段焦点，然后再试一次该组合键。如果你正在测试 Shipping 或 Test 构建，请启用 允许在 Shipping 构建中使用 在以下位置 项目设置 > 插件 > Convai > 调试叠加层 并重新打包。

验证： 标题行 Convai 调试 — 无角色 （或角色名称）出现在屏幕上。

某个面板始终为空

症状： 事实 或 事件 从未在所选角色上出现。

原因： 当没有内容可显示时，这两个面板都会折叠——该角色确实还没有任何事实或已提交事件。

解决方法： 向角色发送一个事实或上下文事件，并在其有内容后确认面板是否出现。

验证： 更新生效后，面板标题会出现在其各行上方。

下一步

Convai 调试覆盖层参考故障排除