> 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/scene-metadata/managing-the-environment-at-runtime.md).

# 运行时管理环境

在游戏运行时使用这些方法更新聊天机器人的世界知识——例如，当新房间加载、道具生成或新的 NPC 进入场景时。 `UConvaiChatbotComponent` 为对象、角色、当前对话对象、注意中的对象以及连接时的环境附加项提供变更方法。运行时变更方法位于 `BlueprintCallable` 在 `Convai|Actions` 类别； `GatherEnvironmentExtras` 属于 `BlueprintCallable` 在 `Convai|Session` 类别。

### 方法分组一览

| 组    | 方法                                                                                             | 用途                                |
| ---- | ---------------------------------------------------------------------------------------------- | --------------------------------- |
| 对象   | `AddObject`, `AddObjects`, `RemoveObject`, `RemoveObjects`, `ClearObjects`                     | 在会话进行中添加或移除世界对象                   |
| 角色   | `AddCharacter`, `AddCharacters`, `RemoveCharacter`, `RemoveCharacters`, `ClearCharacters`      | 添加或移除聊天机器人可引用的其他 NPC              |
| 对话对象 | `SetConversationPartner`                                                                       | 告诉聊天机器人它正在与谁交谈                    |
| 注意   | `SetObjectInAttention`, `TrySetObjectInAttentionFromGaze`, `TryClearObjectInAttentionFromGaze` | 设置、通过注视门控，或清除注意中的对象               |
| 会话开始 | `GatherEnvironmentExtras`                                                                      | 在 /connect 之前填充附加项 `/connect`     |
| 实用工具 | `EnsureObjectComponentsForEnvironmentObjects`                                                  | 生成缺失的 `UConvaiObjectComponent` 实例 |

大多数会推送网络更新的方法都接受一个 `bFlushImmediately` 参数。 `TryClearObjectInAttentionFromGaze` 通过非立即路径进行清除。参见 [防抖与刷新](#debounce-and-flush) 了解详情。

### 该 `FConvaiEnvironmentData` 结构体

`EnvironmentData` (`FConvaiEnvironmentData`）是静态配置， `UConvaiChatbotComponent` 会在以下时发送给 Convai `/connect` 。它包含：

* `bEnableActions` (`bool`，默认 `true`）—— 连接时的动作配置开关。当 `false`，则 `action_config` 块不会在 `/connect`发送，并且通过 `SetObjectInAttention` 不起作用。
* `动作` —— 默认动作列表（`移动到`, `跟随`, `停止移动`, `等待`).
* `对象` —— 在连接时暴露给聊天机器人的对象。
* `角色` —— 在连接时暴露给聊天机器人的角色。
* `CurrentAttentionObject` —— 当前用于注意和引用解析的对象。

请通过以下方法变更环境，而不是直接写入 `EnvironmentData` 来自 Blueprint 的字段。

### 添加和移除对象

| 方法                                              | 说明                                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------- |
| `AddObject(Object, bFlushImmediately)`          | 添加一个 `FConvaiObjectEntry` 并安排一次 `update-scene-metadata` 推送，当该对象不在连接时快照中时。 |
| `AddObjects(Objects, bFlushImmediately)`        | 一次调用添加多个条目。                                                               |
| `RemoveObject(ObjectName, bFlushImmediately)`   | 移除与给定名称匹配的条目并安排一次同步。                                                      |
| `RemoveObjects(ObjectNames, bFlushImmediately)` | 按名称移除多个条目。                                                                |
| `ClearObjects(bFlushImmediately)`               | 从本地列表中移除所有对象。                                                             |

{% hint style="warning" %}
如果某个对象包含在 `action_config` 在 `/connect`，调用 `AddObject` 使用相同名称不会更新冻结的 `action_config` 快照。只有对该会话来说是新增的对象才会通过实时 `update-scene-metadata` 通道传递。要将描述更改传播到现有对象，请调用 `StopSession` 然后 `StartSession` 以重新连接。
{% endhint %}

### 添加和移除角色

| 方法                                                      | 说明                               |
| ------------------------------------------------------- | -------------------------------- |
| `AddCharacter(Character, bFlushImmediately)`            | 添加一个 `FConvaiObjectEntry` 到角色列表。 |
| `AddCharacters(Characters, bFlushImmediately)`          | 添加多个条目。                          |
| `RemoveCharacter(InCharacterName, bFlushImmediately)`   | 按名称移除匹配的条目。                      |
| `RemoveCharacters(InCharacterNames, bFlushImmediately)` | 按名称移除多个条目。                       |
| `ClearCharacters(bFlushImmediately)`                    | 从本地列表中移除所有角色。                    |

### 设置对话对象

`SetConversationPartner(Partner, bFlushImmediately)` 告诉聊天机器人它当前正在与哪个其他角色交谈。如果 `Partner.Name` 尚未在 `EnvironmentData.Characters`中，该方法会自动添加它。

要在不从列表中移除该角色的情况下清除对话对象，请传入一个 `FConvaiObjectEntry` 带有空的 `Name`.

### 控制注意

`SetObjectInAttention(Object, Text, ShouldRespond, bFlushImmediately)` 设置聊天机器人当前关注的对象，并可选择触发上下文事件。该调用在 `bEnableActions` 属于 `false`。如果该对象尚未在对象列表中，该方法会自动添加它。

`AttentionSource` (`EConvaiAttentionSource`, `Transient`, `BlueprintReadOnly`，类别 `Convai|Actions`）反映上一次设置注意的是谁：

* `无` —— 未设置注意目标。
* `显式` (`显式（Blueprint/C++）`）—— 注意由 Blueprint 或 C++ 代码设置。
* `注视` —— 注意由注视管线设置。

当 `AttentionSource` 属于 `显式`时，对 `TrySetObjectInAttentionFromGaze` 的调用会被阻止并返回 `false`。这可防止注视系统覆盖显式的程序设置注意。

`TryClearObjectInAttentionFromGaze(ExpectedObject)` 仅在以下情况下清除由注视拥有的注意槽：当 `AttentionSource` 属于 `注视` 并且当前注意对象仍匹配 `ExpectedObject.Name`。这可保护较新的注意目标，避免被来自较旧目标的延迟注视结束事件清除。

### 在会话开始时填充环境

使用 `GatherEnvironmentExtras` 适用于关卡是程序生成的情况，或者你需要从运行时世界查询构建对象列表，而不是在 Details 面板中手动放置组件。

`GatherEnvironmentExtras` 是一个 `BlueprintNativeEvent` （显示名称 `“Gather Environment Extras”`）在以下内部调用一次 `StartSession()` 在 `/connect` 握手过程中。请在以下 Blueprint 子类中重写它： `UConvaiChatbotComponent` 以附加依赖于运行时世界状态的对象、角色或动作。

该重写会接收三个输出数组：

* `OutExtraActions` —— 附加到默认动作列表。
* `OutExtraObjects` —— 附加到 `EnvironmentData.Objects`.
* `OutExtraCharacters` —— 附加到 `EnvironmentData.Characters`.

该重写是在已配置的默认值上追加，而不是替换它们。这里才是通过世界查询填充环境的正确位置，而不是通过 Details 面板。

参见 [场景元数据使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-usage-examples.md) ，查看这种模式的完整伪代码示例。

### 确保对象组件

`EnsureObjectComponentsForEnvironmentObjects()` 遍历 `EnvironmentData.Objects`。对于每个具有有效 `Ref` actor，它会生成一个匹配的 `UConvaiObjectComponent` ，前提是尚无现有组件覆盖同一目标。它返回新生成组件的数量，并且可安全多次调用（幂等）。

自动生成的组件会注册到整个子系统范围的对象池中，因此关卡中的每个聊天机器人都能通过与手动放置的对象组件相同的接近度、跟踪属性和注视管线看到它们。

在以下时机调用它： `BeginPlay` 在填充之后 `EnvironmentData.Objects` 从代码中，或者在调用 `AddObject` / `AddObjects` 当你希望接近度和注视系统跟踪动态添加的 Actor 时。

### 防抖与刷新

所有变更方法都会在防抖窗口内批量处理更新，将快速调用合并为一条 WebRTC 消息。传入 `bFlushImmediately = true` 以绕过该窗口并立即发送。请谨慎使用 `bFlushImmediately` —— 高频调用会产生许多小消息并增加网络开销。

### 下一步

{% content-ref url="/pages/7fc985238017f8bd9de6df276f318c98902cac03" %}
[场景元数据使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-usage-examples.md)
{% endcontent-ref %}

{% content-ref url="/pages/35be910ed18e7f78411fd4d732770d70307e1434" %}
[排查场景元数据问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/troubleshoot-scene-metadata.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/features/scene-metadata/managing-the-environment-at-runtime.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.