> 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/blueprint-reference/convai-object-component.md).

# Convai Object Component

对象组件参考——Convai Object Component 暴露的每个 Blueprint 可见属性、函数和事件。

`UConvaiObjectComponent` 会添加到任何 `Actor` —— 门、开关、箱子、房间触发器、载具 ——，使其在关卡中自动对所有 Convai 聊天机器人可见。它对世界对象所起的作用与……相同，正如 `UConvaiChatbotComponent` 用于 AI 角色，而 `UConvaiPlayerComponent` 用于玩家。

添加组件路径： `Convai Object Component`. 无需手动向各个聊天机器人注册：插件的子系统会发现所有已注册的对象组件，并在会话开始时将它们的身份和状态初始化到每个聊天机器人中。

### 身份

该 `ObjectEntry` 属性通过……将对象的名称、描述以及移动目标数据以扁平的内部属性集形式暴露出来，使用 `ShowOnlyInnerProperties`. 下表中的所有字段都会直接显示在组件的 Details 面板中，而不是位于嵌套结构体内。父组件属性位于 `Convai|Object`；内部结构体字段保留其 `Convai|Action API` 元数据。

| 属性                                                                      | 类型                             | 默认         | 类别                   | 说明                                                                                     |
| ----------------------------------------------------------------------- | ------------------------------ | ---------- | -------------------- | -------------------------------------------------------------------------------------- |
| `名称` *（通过 `ObjectEntry`)*                                               | `FString`                      | `""`       | `Convai\|Action API` | 发送给 Convai 的显示名称。必须在关卡中的所有对象和角色之间保持唯一——重复项会由子系统自动重命名。                                  |
| `说明` *（通过 `ObjectEntry`)*                                               | `FString`                      | `""`       | `Convai\|Action API` | 供 AI 使用的该对象自然语言描述。                                                                     |
| `ObjectReference` *（通过 `ObjectEntry`，Blueprint 显示名称 `对象为`)*             | `EConvaiObjectReference`       | `整个 Actor` | `Convai\|Action API` | Actor 的哪一部分算作此对象——整个 Actor，还是其中的某个特定组件。控制角色在关注该对象时看向哪里，以及在……时走向哪里 `MovementPoints` 为空。 |
| `接受半径` *（通过 `ObjectEntry`)*                                             | `float` （厘米）                   | `150.0`    | `Convai\|Action API` | 在此距离下 `AI 移动到` 会认为移动完成。                                                                |
| `组件名称` *（通过 `ObjectEntry`)*                                             | `FString`                      | `""`       | `Convai\|Action API` | 在……时，与 Actor 的组件进行不区分大小写的子字符串匹配 `ObjectReference` 是 `特定组件`。留空则使用 Actor 原点。             |
| `Socket 或骨骼名称` *（通过 `ObjectEntry`)*                                     | `FName`                        | `无`        | `Convai\|Action API` | 已解析组件上的 Socket 或骨骼。仅在……时有效 `ObjectReference` 是 `特定组件`。如果未找到，则回退到组件原点。                  |
| `MovementPoints` *（通过 `ObjectEntry`)*                                   | `TArray<FConvaiMovementPoint>` | `[]`       | `Convai\|Action API` | 此对象的设计师编写目的地。参见 [移动点](#movement-points) 下文。                                            |
| `将对象用作回退` *(`bFallbackToObjectWhenPointsUnreachable`，通过 `ObjectEntry`)* | `bool`                         | `false`    | `Convai\|Action API` | 当所有 `MovementPoints` 条目都无法到达时，改为走向对象本身，而不是报告对象不可达。                                     |

有关……的完整说明 `FConvaiObjectEntry` 字段、 `EConvaiObjectReference` 枚举，以及 `FConvaiMovementPoint`的 SDK 方法，请参阅 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

#### 身份函数

| 函数                     | 返回                 | 类别               | 说明                                                                                 |
| ---------------------- | ------------------ | ---------------- | ---------------------------------------------------------------------------------- |
| `GetResolvedComponent` | `USceneComponent*` | `Convai\|Object` | 返回使用……解析得到的场景组件 `组件名称`，或 `nullptr` 当对象以整个 Actor 为目标时。结果会延迟解析并缓存；该节点不接受参数，并会自行重新验证。 |

### 移动点

中的每个条目 `MovementPoints` (`FConvaiMovementPoint`）标记角色走到此对象时站立的位置——对于门，请在两侧各创建一个。可直接在 Details 面板中编辑它们，或在选中对象时拖动视口可视化器添加的抓取手柄。解析器会选择可到达且步行路径最短的点；如果所有点都被禁用，则角色会直接走到对象本身。

Tick `bCreatesSeparateDestination` (Blueprint 显示名称 `创建单独目的地`）在某个点上，使其成为自己的命名目的地——例如一个电梯平台命名为 `上层平台` 可让 AI 被发送到 `电梯上层平台`，与平台分开。

完整的 `FConvaiMovementPoint` 字段表，请参见 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

### 移动感知

该 `MovementAwareness` 属性（`FConvaiObjectMovementSettings`，类别 `Convai\|Object\|Movement Awareness`）检测此对象的平移和旋转，并将简洁的移动方向输入空间上下文。

| 属性                                                   | 类型                           | 默认      | 说明                                                                                           |
| ---------------------------------------------------- | ---------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `bEnableMovementAwareness` (Blueprint 显示名称 `启用移动感知`) | `bool`                       | `true`  | 总开关。关闭后会移除移动相关措辞以及 `移动` 状态，但会保持普通位置和可达性感知不变。                                                 |
| `MovementSensitivity` (`敏感性`)                        | `EConvaiMovementSensitivity` | `中等`    | 连贯的平移或旋转达到多大程度才算移动。数值越高越能检测到细微运动；数值越低则会过滤更多物理漂移和碰撞抖动。                                        |
| `bExposeMovementState` (`添加移动状态`)                    | `bool`                       | `false` | 添加 `<ObjectName>.Movement` 到上下文中，并使其可供 Watch Property 动作用于。还会报告已确认的停止。空间事实中的移动方向表述无需此选项即可工作。 |
| `StartedMovingResponse` (`移动开始时`)                    | `EC_RunLLMOption`            | `从不`    | 已确认的开始是否应请求回复。仅在以下情况下生效： `bExposeMovementState` 已开启。                                         |
| `StoppedMovingResponse` (`移动停止时`)                    | `EC_RunLLMOption`            | `从不`    | 已确认的停止是否应请求回复。仅在以下情况下生效： `bExposeMovementState` 已开启。                                         |
| `传递`                                                 | `EConvaiContextDelivery`     | `正常发送`  | 当一个响应式过渡到达聊天机器人时。仅在以下情况下生效： `bExposeMovementState` 已开启，并且上面的两个回复字段中至少有一个不是 `从不`.             |
| `bFlushImmediately` (`Flush Immediately`)            | `bool`                       | `false` | 对响应式移动过渡绕过正常上下文批处理。生效条件与 `传递`.                                                               |

`EConvaiMovementSensitivity` 的条件相同。灵敏度值从低到高： `很低`, `低`, `中等`, `高`, `很高`.

### 跟踪的属性

AI 会实时关注此 Actor 上的属性。每个条目都会选择一个 `UPROPERTY` （或返回字符串的纯函数），说明其含义，可选地说明每个值的含义，并指定聊天机器人应如何对变化作出反应。

| 属性                  | 类型                               | 默认   | 类别               | 说明                                                         |
| ------------------- | -------------------------------- | ---- | ---------------- | ---------------------------------------------------------- |
| `TrackedProperties` | `TArray<FConvaiTrackedProperty>` | `[]` | `Convai\|Object` | 要监控的属性列表。每个被跟踪的属性都会在会话开始时发送给所有聊天机器人，并且在游戏过程中每当其值发生变化时再次发送。 |

有关……的完整说明 `FConvaiTrackedProperty` 和 `FConvaiTrackedPropertyStateValueDesc` 字段，请参阅 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

#### 跟踪属性函数

这些函数可在运行时添加、移除和更新跟踪属性——适用于只有在玩家采取动作后才变得相关的属性。

| 函数                                                 | 返回     | 输入                                                           | 类别               | 说明                                                                                 |
| -------------------------------------------------- | ------ | ------------------------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------- |
| `AddTrackedProperty(InProperty)`                   | `bool` | `InProperty（FConvaiTrackedProperty）`                         | `Convai\|Object` | 添加一个新的跟踪属性，并立即将其当前值推送给所有聊天机器人。返回 `false` 当该属性路径在此 Actor 上不存在、无法被跟踪（不支持的类型）或已在列表中时。 |
| `RemoveTrackedProperty(PropertyPath)`              | `bool` | `PropertyPath（FName）`                                        | `Convai\|Object` | 停止跟踪该属性。返回 `true` 如果已移除。最后一次广播的值会保留在每个聊天机器人的上下文中，并停止更新。                            |
| `UpdateTrackedProperty(PropertyPath, NewSettings)` | `bool` | `PropertyPath（FName）`, `NewSettings（FConvaiTrackedProperty）` | `Convai\|Object` | 更新描述、状态值描述，或 `ShouldRespond` 已跟踪属性的模式。 `PropertyPath` 是关键——如果需要针对其他属性，请先移除再重新添加。   |
| `GetTrackedProperties(OutProperties)`              | —      | `OutProperties（TArray<FConvaiTrackedProperty>&）`             | `Convai\|Object` | 返回当前跟踪属性列表的副本，以便在 Blueprint 中查看。                                                   |

### 距离与方向

`4.0.0-beta.22` 已弃用此组件过去用于计算的按对象近距离机制—— `bAutoGenerateProximityState` 以及合成的 `"<ObjectName>.ProximityToYou"` 状态键不再存在。现在，每个已注册对象的距离、方向、可达性和视线都由……集中计算。 [空间感知](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness.md) 子系统集中计算，并作为常规上下文的一部分传递给每个聊天机器人。请参见 [空间感知设置参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/spatial-awareness-reference.md) 用于控制此行为的项目设置。

### 凝视关注

控制此对象是否参与玩家的凝视流程，并为自定义凝视集成提供通知函数。有关跨玩家、对象、高亮和聊天机器人组件的完整凝视 API，请参阅 [凝视注意力参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-reference.md).

| 属性          | 类型     | 默认     | 类别                     | 说明                                                                                                                |
| ----------- | ------ | ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `bGazeable` | `bool` | `true` | `Convai\|Object\|Gaze` | 当 `false`，玩家组件的凝视流程会完全跳过此对象——没有高亮，也没有 `OnGazedIn`/`OnGazedOut` 事件，也不会提升注意力。适用于应被 AI 了解（用于动作或状态跟踪），但不应通过玩家凝视到达的对象。 |

#### 凝视函数

这些函数由 `UConvaiPlayerComponent` 在其凝视流程检测到此对象的进入、离开以及注意力阈值转换时自动调用。它们也会 `BlueprintCallable` 因此非凝视流程——过场摄像机、自定义聚焦系统、接近触发器——也可以驱动同一路径。

| 函数                                                      | 输入                                                                                   | 类别                     | 说明                                                                                                                                                       |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NotifyGazeBegin(Player)`                               | `Player（UConvaiPlayerComponent*）`                                                    | `Convai\|Object\|Gaze` | 当玩家的视线进入此对象的边界时调用。触发 `OnGazedIn`.                                                                                                                        |
| `NotifyGazeEnd(Player)`                                 | `Player（UConvaiPlayerComponent*）`                                                    | `Convai\|Object\|Gaze` | 当玩家的视线离开此对象时调用。触发 `OnGazedOut`.                                                                                                                          |
| `NotifyGazeAttentionBegin(Player, Text, ShouldRespond)` | `Player（UConvaiPlayerComponent*）`, `Text（FString）`, `ShouldRespond（EC_RunLLMOption）` | `Convai\|Object\|Gaze` | 当玩家的视线停留足够久，将此对象提升为“处于注意中”时调用。会分发到子系统已知的每个聊天机器人，要求它们通过其凝视门控的 setter 占用注意力槽位。每个聊天机器人都会根据其当前 `AttentionSource` —— 凝视无法覆盖一个 `显式` 设置。触发 `OnAttentionGained`. |
| `NotifyGazeAttentionEnd(Player)`                        | `Player（UConvaiPlayerComponent*）` —— 可能是 `nullptr`                                   | `Convai\|Object\|Gaze` | 当玩家停止注视此对象足够久，从而释放注意力槽位时调用。会向每个聊天机器人分发一个凝视门控的清除操作。即使当前没有聊天机器人持有此对象的凝视注意力，也可以安全调用。触发 `OnAttentionLost`.                                                   |

### 调试

| 属性                         | 类型     | 默认      | 类别                      | 说明                                                                                                                                                                                      |
| -------------------------- | ------ | ------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bDebugDrawProximityPaths` | `bool` | `false` | `Convai\|Object\|Debug` | 当 `true`，每次子系统轮询（通常为 `0.25 秒`）都会重新计算从每个已注册聊天机器人到此对象的导航路径，并在视口中重新绘制——当聊天机器人实际可到达该对象时显示为绿色，不可到达时显示为红色，已经到达时显示为青色。路径会一直保留到下一次重新计算。每个对象组件都拥有自己的线批次，因此多个启用此开关的组件不会相互覆盖。仅限编辑器/调试——在正式发布版本中禁用。 |

### 事件（可在 Blueprint 中绑定的委托）

这四个事件都共享 `FConvaiObjectGazeEvent` 委托签名： `（ObjectComponent: UConvaiObjectComponent, PlayerComponent: UConvaiPlayerComponent）`.

| 事件                  | 显示名称     | 类别                     | 触发条件：                                                                                                         |
| ------------------- | -------- | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| `OnGazedIn`         | `注视进入时`  | `Convai\|Object\|Gaze` | 玩家的视线进入此对象的边界时（在任何注意力停留阈值之前）。                                                                                 |
| `OnGazedOut`        | `注视离开时`  | `Convai\|Object\|Gaze` | 玩家的视线离开此对象时。                                                                                                  |
| `OnAttentionGained` | `获得注意力时` | `Convai\|Object\|Gaze` | 已达到凝视停留阈值，并尝试在各个聊天机器人之间提升注意力。聊天机器人的接受是独立的，如果……则可能失败 **启用操作** 已关闭或 `AttentionSource` 是 `显式（蓝图/C++）`.           |
| `OnAttentionLost`   | `失去注意力时` | `Convai\|Object\|Gaze` | 此对象将从聊天机器人的注意力槽位中释放。 `PlayerComponent` 可能是 `nullptr` 因为 `NotifyGazeAttentionEnd` 接受可为 null 的玩家参数；使用前务必进行空值检查。 |

### 相关参考

{% content-ref url="/pages/4a6e5ee0afdb709983f0b5685e8cf00febcf5282" %}
[Convai 聊天机器人组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-chatbot-component.md)
{% endcontent-ref %}

{% content-ref url="/pages/7882b4c0154c419a4eb6df2db3b2035b55cacb03" %}
[Convai 玩家组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-player-component.md)
{% endcontent-ref %}

{% content-ref url="/pages/96e94ab984072449ee1b8486ef735cc01a5fccde" %}
[数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md)
{% endcontent-ref %}

{% content-ref url="/pages/54960e661fc090cc4ab31a059146f22c63a84ad3" %}
[Convai 工具函数](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-utility-functions.md)
{% endcontent-ref %}

{% content-ref url="/pages/10f005ecc29d44fa4ef4dd6d6ca9cf6c1c257d02" %}
[空间感知](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/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 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/blueprint-reference/convai-object-component.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.