> 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 对象组件

`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 的自然语言描述。                                                     |
| `移动目标模式` *（通过 `ObjectEntry`)*           | `EConvaiMoveTarget` | `Actor` | `Convai\|Action API` | AI 移动动作是针对整个 Actor（`将 Actor 作为目标`）还是其上的某个特定组件或 Socket（`将组件作为目标`).    |
| `接受半径` *（通过 `ObjectEntry`)*             | `float` （厘米）        | `150.0` | `Convai\|Action API` | ……的距离 `AI 移动到` 会认为移动已完成。                                             |
| `组件名称` *（通过 `ObjectEntry`)*             | `FString`           | `""`    | `Convai\|Action API` | 在对 Actor 的组件进行匹配时，不区分大小写的子字符串， `移动目标模式` 为 `将组件作为目标`。留空则使用 Actor 的原点。 |
| `Socket 或 Bone 名称` *（通过 `ObjectEntry`)* | `FName`             | `无`     | `Convai\|Action API` | 已解析组件上的 Socket 或骨骼。仅在 `移动目标模式` 为 `将组件作为目标`。未找到时回退到组件原点。              |
| `bStepOntoBounds` *（通过 `ObjectEntry`)*  | `bool`              | `false` | `Convai\|Action API` | 当 `true`，目标点会投影到目标边界框顶部，这样 AI 会走上平台或表面，而不是停在边缘。两种移动目标模式都适用。          |

有关 `FConvaiObjectEntry` 字段以及 `EConvaiMoveTarget` 枚举，请参见 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

#### 身份函数

| 函数                                    | 返回                 | 类别               | 说明                                                                              |
| ------------------------------------- | ------------------ | ---------------- | ------------------------------------------------------------------------------- |
| `GetResolvedComponent(bForceRefresh)` | `USceneComponent*` | `Convai\|Object` | 返回使用 `组件名称`，或 `nullptr` 当对象针对整个 Actor 时。结果会被缓存；传入 `bForceRefresh = true` 可绕过缓存。 |

### 跟踪属性

此 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 检查。                                                        |

### 接近状态

| 属性                            | 类型     | 默认值    | 类别               | 说明                                                                                                                                     |
| ----------------------------- | ------ | ------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `bAutoGenerateProximityState` | `bool` | `true` | `Convai\|Object` | 当 `true`，插件会自动为每个聊天机器人生成一个 `“<ObjectName>.ProximityToYou”` 状态键，用通俗语言描述该对象相对于每个聊天机器人的位置。示例值包括 `“附近，前方偏右”`, `“很远，在后方”`，以及 `“没有步行路径，后方”`. |

该接近度值会作为一个跟踪属性发送给每个聊天机器人，并带有 `ShouldRespond = Never`。当聊天机器人或对象正在移动时，插件会延迟更新，并复用上一次可达性结果，直到任一端移动超过 `~100 厘米`，因此静止场景几乎没有性能开销。设计师手动编写的 `TrackedProperties` 名为 `ProximityToYou` 会覆盖同一状态键的合成值。

{% hint style="info" %}
接近度状态使用 Unreal 的导航系统（允许部分路径），并在共享轮询 tick 上评估（通常每个对象 `0.25 s` 次）。当 `bStepOntoBounds` 为 `false`，路径终点位于……之内 `max(AcceptanceRadius * 2, 150 厘米)` 的水平范围内时会被视为可达；在默认 `接受半径` 为 `150.0`情况下，该水平容差为 `300 厘米`。当 `bStepOntoBounds` 为 `true`，终点必须位于对象的占地范围内，并带有一个很小的 `1.0 uu` 误差。垂直容差使用 `max(SourceHeight, 150 厘米)`.
{% endhint %}

### 注视注意力

控制该对象是否参与玩家的凝视管线，并为自定义凝视集成提供通知函数。有关覆盖玩家、对象、高亮和聊天机器人组件的完整凝视 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`，会在视口中绘制从每个已订阅聊天机器人到此对象的导航路径——当聊天机器人已在目标处时为青色，可达时为绿色，不可达时为红色。路径会在每次重新评估接近度时重绘，并一直保留到下一次。每个对象组件都拥有自己的线段批处理，因此多个开启此开关的组件不会相互覆盖。 `bAutoGenerateProximityState` 为 `false`。在正式发布构建中禁用。 |

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

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

| 事件                  | 显示名称    | 类别                     | 当                                                                                                        |
| ------------------- | ------- | ---------------------- | -------------------------------------------------------------------------------------------------------- |
| `OnGazedIn`         | `被凝视进入` | `Convai\|Object\|Gaze` | 玩家的凝视进入此对象的边界（在任何关注停留阈值之前）。                                                                              |
| `OnGazedOut`        | `被凝视离开` | `Convai\|Object\|Gaze` | 玩家的凝视离开此对象。                                                                                              |
| `OnAttentionGained` | `获得关注`  | `Convai\|Object\|Gaze` | 已达到凝视停留阈值，并已尝试跨聊天机器人提升关注。聊天机器人是否接受是单独的流程，若 **启用操作** 已关闭，或 `AttentionSource` 为 `Explicit（Blueprint/C++）`. |
| `OnAttentionLost`   | `失去关注`  | `Convai\|Object\|Gaze` | 该对象已从聊天机器人的关注槽位中释放。 `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 %}


---

# 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:

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.