> 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`将对象的名称、描述和移动目标数据作为一组扁平的内部属性公开。下表中的所有字段都会直接显示在组件的“详细信息”面板中，而非嵌套结构体内。父组件属性位于 `Convai|Object`；内部结构体字段则保留其 `Convai|Action API` 元数据。

| 属性                                                                       | 类型                             | 默认值           | 类别                   | 说明                                                                                   |
| ------------------------------------------------------------------------ | ------------------------------ | ------------- | -------------------- | ------------------------------------------------------------------------------------ |
| `Name` *（通过 `ObjectEntry`)*                                              | `FString`                      | `""`          | `Convai\|Action API` | 发送给 Convai 的显示名称。在关卡中的所有对象和角色之间必须唯一；重复名称会由子系统自动重命名。                                  |
| `Description` *（通过 `ObjectEntry`)*                                       | `FString`                      | `""`          | `Convai\|Action API` | 供 AI 使用的此对象自然语言描述。                                                                   |
| `ObjectReference` *（通过 `ObjectEntry`，蓝图显示名称 `Object Is`)*                | `EConvaiObjectReference`       | `Whole Actor` | `Convai\|Action API` | actor 的哪一部分算作此对象——整个 actor，还是其中某个特定组件。这会控制角色关注该对象时看向哪里，以及在 `MovementPoints` 为空时走向哪里。 |
| `AcceptanceRadius` *（通过 `ObjectEntry`)*                                  | `float` （厘米）                   | `150.0`       | `Convai\|Action API` | 距离阈值，达到该距离时， `AI Move To` 会认为移动已完成。                                                  |
| `ComponentName` *（通过 `ObjectEntry`)*                                     | `FString`                      | `""`          | `Convai\|Action API` | 与演员的组件进行不区分大小写的子字符串匹配（当 `ObjectReference` 为 `特定组件`。留空则使用该 Actor 的原点。                 |
| `SocketOrBoneName` *（通过 `ObjectEntry`)*                                  | `FName`                        | `None`        | `Convai\|Action API` | 已解析组件上的插槽或骨骼。仅当 `ObjectReference` 为 `特定组件`时启用。未找到时回退到组件原点。                           |
| `MovementPoints` *（通过 `ObjectEntry`)*                                    | `TArray<FConvaiMovementPoint>` | `[]`          | `Convai\|Action API` | 为此对象手动设置的目的地。请参阅下文的 [移动点](#movement-points) 。                                        |
| `使用对象作为回退` *(`bFallbackToObjectWhenPointsUnreachable`，通过 `ObjectEntry`)* | `bool`                         | `false`       | `Convai\|Action API` | 当所有 `MovementPoints` 条目均不可到达时，改为走向对象本身，而不是报告对象不可到达。                                  |

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

#### 恒等函数

| 函数                     | 返回                 | 类别               | 说明                                                                                            |
| ---------------------- | ------------------ | ---------------- | --------------------------------------------------------------------------------------------- |
| `GetResolvedComponent` | `USceneComponent*` | `Convai\|Object` | 返回使用 `ComponentName`解析出的场景组件；如果对象指向整个 Actor，则返回 `nullptr` 。解析采用惰性方式，并会缓存结果；该节点不接受参数，并会自行重新验证。 |

### 移动点

MovementPoints `中的每个条目` (`FConvaiMovementPoint`）标记了角色走向该对象时站立的位置——例如门，应在门的两侧各设置一个点。可直接在“细节”面板中编辑，也可以在选中对象后拖动视口可视化工具添加的抓取手柄。解析器会选择可到达且行走路径最短的点；如果所有点都已禁用，角色就会直接走到对象本身。

勾选 `bCreatesSeparateDestination` （蓝图显示名称为 `Create Separate Destination`）可将某个点设为独立的命名目的地——例如，将电梯停靠层命名为 `Upper Landing` 后，就可以将 AI 指派到 `Elevator Upper Landing`，使其与电梯平台分开。

完整的 `FConvaiMovementPoint` 字段表，请参阅 [数据类型和枚举](https://docs.convai.com/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` （蓝图显示名称： `启用移动感知`) | `bool`                       | `true`  | 总开关。关闭后会移除移动相关描述和 `Movement` 状态，但不会影响常规的位置和可达性感知。                                          |
| `MovementSensitivity` (`灵敏度`)                 | `EConvaiMovementSensitivity` | `中`     | 设置达到何种程度的连贯平移或旋转才会被视为移动。值越高，越容易检测到细微动作；值越低，越能过滤物理漂移和碰撞抖动。                                  |
| `bExposeMovementState` (`添加移动状态`)             | `bool`                       | `false` | 添加 `<ObjectName>.Movement` 到上下文中，并使其可供“监视属性”操作使用。此选项还会报告已确认的停止状态。即使不启用此选项，空间事实中仍会包含移动方向描述。 |
| `StartedMovingResponse` (`移动开始时`)             | `EC_RunLLMOption`            | `Never` | 设置确认开始移动时是否应请求响应。仅在 `bExposeMovementState` 启用时生效。                                          |
| `StoppedMovingResponse` (`移动停止时`)             | `EC_RunLLMOption`            | `Never` | 设置确认停止移动时是否应请求响应。仅在 `bExposeMovementState` 启用时生效。                                          |
| `Delivery`                                    | `EConvaiContextDelivery`     | `正常发送`  | 设置响应式状态变化到达聊天机器人时的处理方式。仅在 `bExposeMovementState` 启用，且上方两个响应字段中至少有一个不为 `从不`.                |
| `bFlushImmediately` (`立即刷新`)                  | `bool`                       | `false` | 对响应式移动状态变化绕过常规上下文批处理。生效条件与 `Delivery`.                                                     |

`EConvaiMovementSensitivity` 各值按灵敏度从低到高排列： `极低`, `低`, `中`, `高`, `极高`.

### 跟踪的属性

此 Actor 上由 AI 实时持续关注的属性。每个条目都会选择 Actor 上的一个 `UPROPERTY` （或返回字符串的纯函数），描述其含义，可选地说明每个值的含义，并指定聊天机器人应如何响应更改。

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

有关 `FConvaiTrackedProperty` 和 `FConvaiTrackedPropertyStateValueDesc` 字段的完整说明，请参阅 [数据类型和枚举](https://docs.convai.com/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` 当此对象上不存在该属性路径、无法跟踪该属性（类型不受支持）或该属性已在列表中时。 |
| `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` | 返回当前跟踪属性列表的副本，以便在蓝图中查看。                                                         |

### 距离和方向

`4.0.0-beta.22` 移除了此组件用于计算的逐对象接近度机制—— `bAutoGenerateProximityState` 以及自动生成的 `"<ObjectName>.ProximityToYou"` 状态键已不复存在。现在，所有已注册对象的距离、方向、可达性和视线状况都由 [空间感知](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness.md) 子系统集中计算，并作为常规上下文的一部分提供给每个聊天机器人。有关控制此功能的项目设置，请参阅 [空间感知设置参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/spatial-awareness-reference.md) 。

### 凝视注意

控制此对象是否参与玩家的凝视流程，并提供用于自定义凝视集成的通知函数。如需了解涵盖玩家、对象、高亮显示和聊天机器人组件的完整凝视 API，请参阅 [凝视注意参考](https://docs.convai.com/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*)`, `文本 (FString)`, `ShouldRespond (EC_RunLLMOption)` | `Convai\|Object\|Gaze` | 当玩家的注视停留足够长时间，使此对象进入“受关注”状态时调用。此函数会向子系统中已知的每个聊天机器人广播请求，让它们通过注视门控的设置器争取注意力槽位。每个聊天机器人都会根据当前 `AttentionSource` 独立接受或拒绝——注视不能覆盖 `Explicit` 设置。触发 `OnAttentionGained`. |
| `NotifyGazeAttentionEnd(Player)`                        | `Player (UConvaiPlayerComponent*)` ——可能为 `nullptr`                                    | `Convai\|Object\|Gaze` | 当玩家停止注视此对象足够长时间，从而释放注意力槽位时调用。此函数会向每个聊天机器人广播受注视门控的清除请求。即使当前没有聊天机器人因注视而将此对象设为关注对象，调用也是安全的。触发 `OnAttentionLost`.                                                     |

### 调试

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

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

这四个事件共用 `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` 接受可为空的玩家参数；使用前务必检查是否为 null。     |

### 相关参考

{% content-ref url="/pages/4a6e5ee0afdb709983f0b5685e8cf00febcf5282" %}
[Convai 聊天机器人组件](https://docs.convai.com/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 玩家组件](https://docs.convai.com/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" %}
[数据类型和枚举](https://docs.convai.com/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 工具函数](https://docs.convai.com/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" %}
[空间感知](https://docs.convai.com/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.
