> 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 对象组件`。无需在各个聊天机器人中手动注册：插件子系统会发现所有已注册的对象组件，并在会话开始时将它们的身份和状态注入每个聊天机器人。

### 身份

该 `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，还是其中某个特定组件。它控制角色在注意该对象时看向哪里，以及在 `MovementPoints` 为空时忽略。 |
| `AcceptanceRadius` *（通过 `ObjectEntry`)*                                 | `float` （厘米）                   | `150.0`    | `Convai\|Action API` | 达到该距离时 `AI 移动到` 视为移动完成。                                                         |
| `ComponentName` *（通过 `ObjectEntry`)*                                    | `FString`                      | `""`       | `Convai\|Action API` | 在 `ObjectReference` 为 `特定组件`。留空则使用 Actor 原点。                                    |
| `SocketOrBoneName` *（通过 `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`，请参见 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

#### 身份函数

| 函数                     | 返回值                | 类别               | 描述                                                                                   |
| ---------------------- | ------------------ | ---------------- | ------------------------------------------------------------------------------------ |
| `GetResolvedComponent` | `USceneComponent*` | `Convai\|Object` | 返回使用 `ComponentName`，或 `nullptr` 当该对象指向整个 Actor 时返回。结果采用延迟解析并缓存；该节点不接受任何参数，并会自行重新验证。 |

### 移动点

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

Tick `bCreatesSeparateDestination` （蓝图显示名称 `创建单独目的地`在某个点上）将其设为具有独立名称的目的地——例如名为 `上层平台` 可让 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\|移动感知`）会检测该对象的平移和旋转，并将压缩的移动方向输入到空间上下文中。

| 属性                                           | 类型                           | 默认值     | 描述                                                                                                 |
| -------------------------------------------- | ---------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `bEnableMovementAwareness` （蓝图显示名称 `启用移动感知`) | `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` 各值从最不敏感到最敏感： `非常低`, `低`, `中`, `高`, `非常高`.

### 受跟踪属性

此 Actor 上会让 AI 实时了解的属性。每个条目会选择一个 `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\|凝视` | 当 `false`，玩家组件的凝视管线会完全跳过此对象——没有高亮，没有 `OnGazedIn`/`OnGazedOut` 事件，也不会提升注意力。用于那些应让 AI 知晓（用于动作或状态跟踪）但不应通过玩家凝视到达的对象。 |

#### 凝视函数

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

| 函数                                                      | 输入                                                                                      | 类别                   | 描述                                                                                                                                                |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NotifyGazeBegin(Player)`                               | `Player (UConvaiPlayerComponent*)`                                                      | `Convai\|Object\|凝视` | 当玩家的凝视进入该对象边界时调用。触发 `OnGazedIn`.                                                                                                                  |
| `NotifyGazeEnd(Player)`                                 | `Player (UConvaiPlayerComponent*)`                                                      | `Convai\|Object\|凝视` | 当玩家的凝视离开此对象时调用。触发 `OnGazedOut`.                                                                                                                   |
| `NotifyGazeAttentionBegin(Player, Text, ShouldRespond)` | `Player (UConvaiPlayerComponent*)`, `Text (FString)`, `ShouldRespond (EC_RunLLMOption)` | `Convai\|Object\|凝视` | 当玩家的凝视停留足够久，使该对象升级为“受关注”时调用。会分发给子系统已知的每个聊天机器人，请求它们通过各自受凝视门控的设置器占用注意力槽。每个聊天机器人会根据其当前 `AttentionSource` ——凝视无法覆盖一个 `显式` 已设置。触发 `OnAttentionGained`. |
| `NotifyGazeAttentionEnd(Player)`                        | `Player (UConvaiPlayerComponent*)` ——可能会是 `nullptr`                                     | `Convai\|Object\|凝视` | 当玩家停止注视该对象足够久，以释放注意力槽时调用。会向每个聊天机器人分发一次受凝视门控的清除。即使当前没有聊天机器人持有该对象的凝视注意力，也可安全调用。触发 `OnAttentionLost`.                                                |

### 调试

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

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

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

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

### 相关参考

{% 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 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/blueprint-reference/convai-object-component.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.