> 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/how-spatial-awareness-works.md).

# 空间感知的工作原理

了解距离带、方向、朝向、视线、关系，以及空间事实如何变成角色读取的句子。

空间感知是在内部由轮询驱动的一次传递 `UConvaiContextSubsystem` 将已注册的原始位置 `UConvaiObjectComponent` 实例、其他角色以及玩家转换为每个主题、每个聊天机器人各一条通俗语言的“上下文事实”。该传递只在中央运行一次，然后根据每个聊天机器人的偏好筛选它交付给该聊天机器人的内容。

如果你还没有启用空间感知，请先从 [空间感知快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/spatial-awareness-quick-start.md)。本页解释了这套设置背后的心智模型。

### 主开关

`bEnableSpatialAwareness` （显示名称 **启用空间感知**，在 **编辑 > 项目设置 > 插件 > Convai**，默认 `true`) 是整个系统的主开关。关闭时，项目中任何聊天机器人都不会生成接近、视线或关系事实——本页所述的其他所有设置都会失效。

### 距离区间

在写成文字之前，聊天机器人能够感知的每个对象都会被分入三个距离区间之一：

| 区间 | 阈值                                    | 短语      |
| -- | ------------------------------------- | ------- |
| 附近 | 在 `NearbyDistance` （默认 `1000.0` 厘米）   | “近旁”    |
| 中等 | 在 `ModerateDistance` （默认 `4000.0` 厘米） | “有一段距离” |
| 远处 | 达到或超过 `ModerateDistance`              | “很远”    |

第四种状态“不可到达”会完全覆盖距离：当到某个对象没有可步行路径时，不管直线距离看起来有多近，这条事实都会写成没有步行路径。 `ModerateDistance` 应当保持大于 `NearbyDistance`；二者都在以下位置以厘米为单位配置： **编辑 > 项目设置 > 插件 > Convai**，类别 **空间感知**.

### 方向与朝向

方向是根据观察中的聊天机器人自身的局部坐标系计算的——相对于聊天机器人的前、右、上，而不是世界坐标。对象会被描述为在观察者的前方、后方、左侧或右侧、上方或下方；当对象位于对角线方向时会合并轴（“在你前方且在你右侧”）。如果对象基本上就在观察者的位置，则会写成“就在你旁边”，而不是某个方向。

对于具有有意义前向向量的对象——另一个角色或玩家——空间感知还会报告朝向：“面向你”或“背对你”。如果朝向与观察者大致成侧向，则不会猜测，而是省略。

### 视线

`bEnableLineOfSight` （项目设置，默认 `false`）在距离和方向之外又增加了一层可见性检查：在告诉聊天机器人某个对象在哪里之前，系统会检查聊天机器人是否真的能看到它。关闭视线后，无论它和观察者之间有什么，都会描述每个对象。

开启视线后，每次检查每个聊天机器人/对象对在每次轮询中都会消耗一次视线追踪。隐藏在墙后的对象会被报告为不在视野内，其位置不会被描述错误，而是会被省略。该追踪会忽略观察者自身的碰撞以及所有玩家角色，因此，站在某个物体前面的玩家不会让 NPC 看不到它。

### 对象之间的关系

`bEnableRelations` （项目设置，默认 `true`）会增加第二类事实：附近事物彼此之间如何关联，而不只是它们相对于观察中的聊天机器人——例如，“枪在箱子上面”。关系只会在 `RelationClusterDistance` （默认 `600.0` 厘米）范围内的对象之间触发，这样就不会因为同处一层而把房间两侧互不相关的道具描述成有关联。

### 每个聊天机器人的偏好

上面的项目设置决定空间系统计算什么；聊天机器人自身的偏好决定它实际接收到什么。这些设置位于 `UConvaiChatbotComponent` 在一个 `SpatialAwareness` 属性（`FConvaiSpatialAwarenessPreferences`，类别 **Convai | 空间感知**，高级），并划分为与事实本身相同的两类：

| 类别                   | 接收开关                               | 响应设置                                               | 发送设置                                                        |
| -------------------- | ---------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- |
| 周围环境——事物相对于该聊天机器人的位置 | `bReceiveSurroundings` （默认 `true`) | `SurroundingsResponse` (`EC_RunLLMOption`，默认 `从不`) | `SurroundingsDelivery` (`EConvaiContextDelivery`，默认 `正常发送`) |
| 关系——事物彼此之间如何摆放       | `bReceiveRelations` （默认 `true`)    | `RelationsResponse` (`EC_RunLLMOption`，默认 `从不`)    | `RelationsDelivery` (`EConvaiContextDelivery`，默认 `正常发送`)    |

关闭 `bReceiveSurroundings` 对于不应感知周围环境的聊天机器人——例如一个无实体的旁白。响应设置控制某个变化是静默发送（`从不`，默认）还是也会推动角色作出反应（`Auto`/`总是`）——当你希望角色在玩家靠近时向其打招呼，这很有用。发送设置只在响应设置为 `Auto` 或 `总是`: **正常发送** 会把反应批量并入下一次计划发送，而 **等待对话空闲** 会一直等到没人说话时才发送，因此角色不会在评论变化时打断自己的发言。

### 从事实到句子

空间感知只有在其句子实际发生变化时才发布事实，因此静止的场景不会在每次轮询时重复发送相同描述。聊天机器人收到的第一份完整空间视图会作为基线知识静默交付，而不是作为事件——一个刚刚开始的会话不应该听起来像是在对一切同时出现作出反应。

### 玩家视角

`bDescribePlayerPerspective` （显示名称 **从玩家视角描述**，在 **编辑 > 项目设置 > 插件 > Convai**，默认 `true`) 会为每条事实额外增加一个分句，从最近的玩家自身摄像机坐标系来定位对象，并明确命名该坐标系和对象——例如，“从 Eshmawy 的位置看，箱子就在附近，前方偏左。”这样角色就能从玩家自己的视角给出方向，而无需自己做旋转。

玩家视角分句绝不会因距离而被省略：远处对象仍会退化为单独的“很远”，而不会被删除，因此较早的“近旁”分句不会作为过期信息残留。由于这个分句会让空间文本长度大约翻倍，因此对于不需要给玩家指路的角色，应将其关闭。

### 下一步

{% content-ref url="/pages/280824f0950858984da0cf561a8148bbd7eee0e8" %}
[空间感知快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/spatial-awareness-quick-start.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/how-spatial-awareness-works.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.