> 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/features/spatial-awareness/spatial-awareness-quick-start.md).

# 空间感知快速开始

开启空间感知，针对关卡尺度调整距离带，并确认角色实际接收到什么。

本指南会为你的项目开启空间感知，调整距离分段以匹配关卡的比例，并通过 Convai Debug Overlay 确认聊天机器人确实收到了系统生成的句子。

### 先决条件

* 已安装 Convai Unreal Engine 插件。
* 至少有一个 `UConvaiChatbotComponent` 被放置在关卡中。
* 关卡中至少有另一个 Actor 具有一个 `UConvaiObjectComponent`，因此有可供聊天机器人获知的内容。

### 确认总开关已开启

{% stepper %}
{% step %}

#### 打开项目设置

前往 **编辑 > 项目设置 > 插件 > Convai** 并展开 **空间感知** 类别。
{% endstep %}

{% step %}

#### 确认“Enable Spatial Awareness”已勾选

**启用空间感知** (`bEnableSpatialAwareness`) 默认已勾选。如果未勾选，则项目中的任何聊天机器人都不会生成邻近、视线或关系事实——现在就勾选它。
{% endstep %}
{% endstepper %}

### 调整距离分段以匹配关卡的比例

空间感知会使用两个阈值（均以厘米为单位）将聊天机器人能够感知到的每个对象归入“近旁”“有一段距离”或“很远”。默认值假定关卡为人类尺度；更大或更小的关卡需要不同的数值。

{% stepper %}
{% step %}

#### 设置近距离

**近距离** (`NearbyDistance`，默认 `1000.0` ) 是上限，低于该值时对象会被判定为“近旁”。将其设置为大致相当于关卡中的角色应把某物视为伸手可及或几步之遥的范围。
{% endstep %}

{% step %}

#### 设置中距离

**中等距离** (`ModerateDistance`，默认 `4000.0` ) 是上限，低于该值时对象会被判定为“有一段距离”。超过它后，对象会被判定为“很远”。保持 `ModerateDistance` 大于 `NearbyDistance` ——系统不会替你强制这种顺序。
{% endstep %}
{% endstepper %}

{% hint style="info" %}
这两个距离都具有编辑条件 `bEnableSpatialAwareness`，因此在总开关打开之前它们会呈灰色。
{% endhint %}

### 确认聊天机器人已设置为接收周围环境

上面的项目设置决定空间系统计算什么；每个聊天机器人自身的偏好决定它实际接收什么。

{% stepper %}
{% step %}

#### 选择聊天机器人的 Convai Chatbot 组件

在角色 Blueprint 或关卡 Actor 中，选择 `UConvaiChatbotComponent`.
{% endstep %}

{% step %}

#### 确认 Receive Surroundings 已开启

展开 **Convai | 空间感知** （高级显示）并确认 `bReceiveSurroundings` 已勾选。默认情况下为 `true`。如果关闭，无论上面的项目设置如何，这个聊天机器人都不会接收周围环境事实。
{% endstep %}
{% endstepper %}

### 验证角色接收到的内容

进入播放模式，打开 [Convai 调试覆盖层](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay.md) 使用 **Ctrl+Alt+K**，并选择聊天机器人。

查看 **周围环境** 面板中带有以下内容的对象 `UConvaiObjectComponent` 来自你的前置条件。其所在行会显示聊天机器人接收到的逐字句子——例如，“箱子就在附近，在你前方。”这是直接传递给 Convai 的精确文本，而不是摘要，因此它是确认你的距离分段调整是否产生了你期望措辞的最快方式。

{% hint style="success" %}
如果该行显示对象处于错误的分段，请调整 `NearbyDistance` 或 `ModerateDistance` 并重新进入 Play 模式，以立即看到更改生效。
{% endhint %}

有关叠加层显示的每个面板、图标和标签，请参阅 [Convai Debug Overlay 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay-reference.md).

### 下一步

{% content-ref url="/pages/7e106191f2eaa9dd6a1b3cfbbbf3a7e6e171e3bf" %}
[空间感知的工作原理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/how-spatial-awareness-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/61357e0f0cdf694475bb5b1ab006fa4ae40d02e2" %}
[空间感知设置参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/spatial-awareness-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/7ae0cd173a36a87a1546f41623ce3ca4da2a289b" %}
[排查空间感知问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/troubleshoot-spatial-awareness.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/features/spatial-awareness/spatial-awareness-quick-start.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.