> 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).

# 运行时管理环境

用于 chatbot 环境方法的参考，这些方法在活动游戏会话期间添加、移除和更新对象和角色。

使用这些方法可在游戏运行时更新聊天机器人的世界知识——例如，当新房间加载、道具生成或新的 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`             |
| 实用工具 | `EnsureObjectComponentsForEnvironmentObjects`                                                  | 生成缺失的 `UConvaiObjectComponent` 实例 |

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

### 该 `FConvaiEnvironmentData` 结构体

`（EnvironmentData` (`FConvaiEnvironmentData`）是静态配置， `UConvaiChatbotComponent` 在连接时发送给 Convai， `/connect` 并包含：

* `bEnableActions` (`布尔值`，默认 `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` （显示名称 `"收集环境附加项"`）在以下内部调用一次： `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` 之后调用，以便在你希望 [空间感知](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness.md) 和凝视系统跟踪动态添加的 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 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/features/scene-metadata/managing-the-environment-at-runtime.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.