> 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` 都不起作用。 |

没有单独的启用开关。该覆盖层在编辑器中、在编辑器内运行时（Play In Editor）以及在 Development 构建中始终可用。

### 构建可用性

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

### 请求头

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

### 面板

面板适用于当前所选角色。

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

### 世界空间标记

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

当被关卡几何体遮挡时，两种标记都会淡出。

### 动作队列与结果

显示在所选角色上方。

| 符号或格式                    | 含义                    |
| ------------------------ | --------------------- |
| `▶ <action>`             | 当前正在执行的动作。            |
| `■ 取消中 · <action>`       | 当前动作，正在取消过程中。         |
| `· <action>`             | 已入队的动作，尚未执行。          |
| `<action> — 完成`          | 动作成功。结果横幅显示 2.5 秒。    |
| `<action> — 失败（<note>）`  | 动作失败，可附带备注。显示 2.5 秒。  |
| `<action> — 已中止（<note>）` | 动作已中止，可附带备注。显示 2.5 秒。 |

### 选择

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

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

### 不是 Blueprint 接口面

调试覆盖层不暴露任何 Blueprint 节点，也不暴露任何 `UFUNCTION`，也没有控制台变量（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 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/troubleshooting/convai-debug-overlay-reference.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.