> 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 调试叠加层检查角色](https://docs.convai.com/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 构建中始终可用。

### 构建版本可用性

| 构建类型                              | 行为                                                             |
| --------------------------------- | -------------------------------------------------------------- |
| Editor、Play In Editor、Development | 叠加层始终可用。                                                       |
| Shipping、Test                     | 除非 `允许在 Shipping 构建中使用` 已开启，否则不会产生任何效果。不会显示小组件，也不会响应组合键或控制台命令。 |

### 请求头

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

### 面板

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

| 面板标签           | 内容                                                                                                                           |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `上下文状态`        | 每个受跟踪的上下文状态都以“键：值”行显示。属于当前选中对象的行会呈现青色。每行都带有脉冲圆点，其颜色由响应设置决定：Always 对应红色 `Always`，琥珀色表示 `Auto`，灰色表示 `Never`.                   |
| `FACTS`        | 显示提供给角色的事实键值行。没有事实时会折叠。                                                                                                      |
| `SURROUNDINGS` | 每个附近物体占一行：物体名称， `— reached` 角色上一次前往该物体的移动完成后显示， `— no path` 导航无法找到路径时显示；还包括角色收到的关于该物体的原句，以及 `(pending flush)` 表示该条目已暂存但尚未发送。 |
| `EVENTS`       | 按时间顺序显示最近六条已提交事件，后接为下一次刷新暂存的事件（标记为 `(pending flush)`）以及任何一次性事件（标记为 `(one-shot)`）。没有内容可显示时会折叠。                                |

### 世界空间标记

| 符号  | 含义                                    |
| --- | ------------------------------------- |
| `◆` | 关卡中已注册的角色或 `UConvaiObjectComponent` 。 |
| `◇` | 已注册物体上一个已命名且已启用的移动点。                  |

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

### 动作队列与结果

显示在所选角色上方。

| 符号或格式                         | 含义                      |
| ----------------------------- | ----------------------- |
| `▶ <action>`                  | 当前正在执行的动作。              |
| `■ cancelling · <action>`     | 当前动作正在取消过程中。            |
| `· <action>`                  | 已排队但尚未执行的动作。            |
| `<action> — done`             | 动作已成功完成。会在结果栏中显示 2.5 秒。 |
| `<action> — failed (<note>)`  | 动作失败，可附带备注。显示 2.5 秒。    |
| `<action> — aborted (<note>)` | 动作已中止，可附带备注。显示 2.5 秒。   |

### 选择

| 输入                        | 即可完全隐藏叠加层。             |
| ------------------------- | ---------------------- |
| `PgUp`                    | 切换到当前选择模式中的上一个项目。      |
| `PgDn`                    | 切换到当前选择模式中的下一个项目。      |
| `Shift` + `PgUp` / `PgDn` | 在字符和对象选择模式之间切换，然后循环切换。 |

只能通过键盘进行选择；无法使用鼠标拾取。

### 不是 Blueprint 接口

调试叠加层不公开任何 Blueprint 节点、不公开 `UFUNCTION`，也不公开任何控制台变量（CVar）。实现该功能的类均为内部类：它们都不是 `BlueprintType`，叠加层控件则位于私有头文件中。切换键和 `Convai.DebugOverlay` 控制台命令构成了完整的 API——没有其他可从 Blueprint 或 C++ 调用的内容。

### 相关参考

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

{% content-ref url="/pages/2c318643919de48c794a1f4b6b1eb25b6e0ed166" %}
[故障排查](https://docs.convai.com/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.
