> 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/troubleshooting/convai-debug-overlay-reference.md).

# Convai 调试覆盖层参考

游戏内 Convai 调试覆盖层暴露的每个面板、图标、按键和设置，以及准确的屏幕标签、颜色和键盘快捷键。

Convai 调试覆盖层是一个游戏内面板，用于显示所选角色的实时上下文状态、事实、周围文本、事件和动作队列。它没有 Blueprint API，也没有控制台变量——切换键和 `Convai.DebugOverlay` 控制台命令就是全部接口。若要查看任务导向的演练，请参阅 [使用 Convai 调试覆盖层检查角色](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay.md).

### 切换

| 方法    | 默认值                   | 注意                       |
| ----- | --------------------- | ------------------------ |
| 按键组合  | `Ctrl+Alt+K`          | 可配置。文本字段获得键盘焦点时会被忽略。     |
| 控制台命令 | `Convai.DebugOverlay` | 切换同一覆盖层；无论配置的按键是什么，都能使用。 |

### 设置

配置于 `UConvaiSettings`，类别 **调试覆盖层**，在 **项目设置 > 插件 > Convai**.

| 设置项                  | 类型     | 默认值     | 描述                                                                                 |
| -------------------- | ------ | ------- | ---------------------------------------------------------------------------------- |
| `切换键（配合 Ctrl+Alt）`   | `FKey` | `K`     | 与 `Ctrl+Alt` 组合后用于打开或关闭覆盖层。                                                        |
| `允许在 Shipping 构建中使用` | `bool` | `false` | 关闭时，该覆盖层在 Shipping 和 Test 构建中会静默无操作：不会出现任何小部件，切换键和 `Convai.DebugOverlay` 都不会有任何作用。 |

没有单独的启用开关。该覆盖层在编辑器、编辑器内运行以及开发构建中始终可用。

### 构建可用性

| 构建类型          | 行为                                                       |
| ------------- | -------------------------------------------------------- |
| 编辑器、编辑器内运行、开发 | 覆盖层始终可用。                                                 |
| Shipping、Test | 静默无操作，除非 `允许在 Shipping 构建中使用` 已开启。没有小部件，也不会响应按键组合或控制台命令。 |

### 标题

| 格式                                         | 显示时                       |
| ------------------------------------------ | ------------------------- |
| `Convai 调试 — 无角色`                          | 未选择角色。                    |
| `<CharacterName> · 正在说话 · 正看着 <Attention>` | 已选择一个角色，当前正在说话，并且设置了注意对象。 |
| `<CharacterName> · 空闲`                     | 已选择一个角色，未在说话，且未设置注意对象。    |

### 面板

面板适用于当前选中的角色。

| 面板标签    | 内容                                                                                                    |
| ------- | ----------------------------------------------------------------------------------------------------- |
| `上下文状态` | 每个已跟踪的上下文状态都显示键：值行。属于当前选中对象的行会以青色高亮。每一行都有一个脉冲圆点，其颜色由响应设置决定：红色表示 `总是`，琥珀色表示 `Auto`，灰色表示 `从不`.          |
| `事实`    | 提供给角色的事实的键：值行。当没有事实时会折叠。                                                                              |
| `周围环境`  | 每个附近对象一行：对象名称， `— 已到达` 在角色最后一次前往它的移动完成后， `— 无路径` 在导航无法找到路线时，角色收到的关于该对象的原文句子，以及 `（待刷新）` 当该条目已暂存但尚未发送时。 |
| `事件`    | 最近提交的六个事件，按时间顺序排列，后面跟着为下一次刷新而暂存的任何内容（标记为 `（待刷新）`）以及任何一次性事件（标记为 `（一次性）`）。当没有内容可显示时会折叠。                 |

### 世界空间标记

| 图形  | 含义                                      |
| --- | --------------------------------------- |
| `◆` | 已注册的角色或 `UConvaiObjectComponent` 位于关卡中。 |
| `◇` | 已注册对象上一个已命名、已启用的移动点。                    |

这两种标记在被关卡几何遮挡时都会淡出。

### 动作队列和结果

显示在所选角色上方。

| 图形或格式                   | 含义                     |
| ----------------------- | ---------------------- |
| `▶ <action>`            | 当前正在执行的动作。             |
| `■ 正在取消 · <action>`     | 当前动作，正在被取消。            |
| `· <action>`            | 已排队的动作，尚未执行。           |
| `<action> — 完成`         | 动作成功。会在结果栏中显示 2.5 秒。   |
| `<action> — 失败（<note>）` | 动作失败，带有可选说明。显示 2.5 秒。  |
| `<action> — 中止（<note>）` | 动作被中止，带有可选说明。显示 2.5 秒。 |

### 选择

| 输入                        | 效果                     |
| ------------------------- | ---------------------- |
| `PgUp`                    | 在当前选择模式中切换到上一个项目。      |
| `PgDn`                    | 在当前选择模式中切换到下一个项目。      |
| `Shift` + `PgUp` / `PgDn` | 在角色与对象之间切换选择模式，然后循环切换。 |

选择仅支持键盘；没有鼠标拾取。

### 不是 Blueprint 接口

调试覆盖层不暴露任何 Blueprint 节点、没有 `UFUNCTION`s，也没有控制台变量（CVars）。实现它的类是内部类：二者都不是 `BlueprintType`，且覆盖层小部件位于一个私有头文件中。切换键和 `Convai.DebugOverlay` 控制台命令就是完整 API——没有更多内容可从 Blueprint 或 C++ 中调用。

### 相关参考

{% content-ref url="/pages/1ed7761971047e9936d8725a20f0087277c2bd4b" %}
[使用 Convai 调试覆盖层检查角色](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay.md)
{% endcontent-ref %}

{% content-ref url="/pages/2c318643919de48c794a1f4b6b1eb25b6e0ed166" %}
[故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting.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/troubleshooting/convai-debug-overlay-reference.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.