> 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/scene-metadata-usage-examples.md).

# 场景元数据使用示例

在 Unreal Engine 中为训练模拟、工业演练、军事基地和运行时环境更新提供完整的场景元数据设置。

下面的示例涵盖了训练模拟和交互式体验的现实设置。每个示例都会描述场景、所需的 Details 面板或 Blueprint 配置，以及预期的运行时结果。请从最符合你当前复杂度水平的示例开始。

### 示例 1：医疗培训模拟——解剖实验室

**场景：** 一场外科训练模拟，医疗导师 NPC 引导受训者完成解剖实验室。角色必须识别并描述房间中的实体模型和设备——受训者会提问，例如 `“这是什么器官？”` 或 `“主动脉在哪里？”`

#### 设置

此示例无需 Blueprint 脚本。为 `UConvaiObjectComponent` 添加一个 `Actor` 到解剖模型和设备 **Details** 面板中，将 `名称` 和 `说明` 字段设置为 `ObjectEntry`:

| 名称                | 说明                                   |
| ----------------- | ------------------------------------ |
| `HeartModel`      | `“中心检查台上的真人大小解剖心脏模型。显示全部四个心腔和主要血管。”` |
| `LiverModel`      | `“安装在展示架左侧的成人肝脏模型。肝静脉已按颜色区分。”`       |
| `SurgicalScalpel` | `“放在器械托盘上的标准手术刀。刀柄为蓝色。”`             |
| `Stethoscope`     | `“挂在检查台旁挂钩上的听诊器。”`                   |

导师角色会在会话开始时接收所有描述，因此关于房间的问题可以使用实际场景条目作为上下文。

{% hint style="success" %}
受训者会问： `“有哪些模型可供学习？”` 一个有用的回答可以引用 `HeartModel` 和 `LiverModel` 场景元数据中的描述。
{% endhint %}

### 示例 2：工业安全演练——基于阶段的对象感知

**场景：** 一个包含多个演练阶段的安全培训模块。每个阶段都会引入不同的危险和设备。当前阶段道具是在会话开始后引入时，运行时对象更新会非常有用。

#### 设置

使用 `ClearObjects` 和 `AddObject` 在每个阶段加载时对聊天机器人组件调用 `bFlushImmediately = true` 在最终调用中传入，以将所有待处理更新合并为一条消息。

```cpp
// C++ — 切换到新的演练阶段时在聊天机器人组件上调用
void ASafetyDrillManager::LoadPhase(int32 PhaseIndex)
{
    // 移除上一阶段的所有对象
    ChatbotComponent->ClearObjects(false);

    // 仅添加当前阶段的道具
    const TArray<FConvaiObjectEntry>& PhaseEntries = PhaseProps[PhaseIndex];
    for (int32 i = 0; i < PhaseEntries.Num(); ++i)
    {
        bool bFlush = (i == PhaseEntries.Num() - 1); // 在最后一项时刷新
        ChatbotComponent->AddObject(PhaseEntries[i], bFlush);
    }
}
```

在 Blueprint 中连接 **Clear Objects** (Flush Immediately: `false`) 后接一个或多个 **Add Object** 节点，并在 **Flush Immediately** 设置为 `true` 上设置

此模式会将新的阶段道具通过运行时环境更新路径发送出去。如果某个阶段对象已经包含在 `action_config` 在 `/connect`中，请在阶段开始前重新连接，这样下一次会话就会以正确的对象集合开始。

### 示例 3：军事模拟——带有实时闸门状态的前沿作战基地

**场景：** 一场军事训练模拟，战术军官了解前沿作战基地的布局。安保闸门具有实时访问状态，闸门变化应作为跟踪状态发送给 Convai。

#### 设置

添加一个 `UConvaiObjectComponent` 添加到每个结构和安保闸门 `Actor`。对于静态结构，只需要 `名称` 和 `说明` 。对于安保闸门，还要添加一个跟踪属性：

1. 展开 **Tracked Properties** 并点击 **+**.
2. 点击 **绑定** 旁边的 **属性路径** 并选择 `bIsOpen` 来自闸门的 `Actor`.
3. 设置 **`说明`** 为 `“安保闸门当前是否打开。”`.
4. 设置 **`ShouldRespond`** 为 `始终`.

| 名称            | 说明                                    |
| ------------- | ------------------------------------- |
| `CommandPost` | `“Alpha-7 网格参考点的主要指挥所。设有任务简报室和通信设备。”` |
| `Armoury`     | `“东侧外围的军械库建筑。仅限授权人员进入。”`              |
| `NorthGate`   | `“北侧安保闸门。控制车辆和人员进入前沿作战基地。”`           |

当 `bIsOpen` 属性在 `NorthGate` `Actor` 运行时发生变化时，插件会在跟踪属性轮询中检测到该变化，并安排一次带有 `ShouldRespond` 设置为 `始终`.

{% hint style="success" %}
玩家打开了北门。下一次跟踪属性更新会发送新的 `bIsOpen` 值并附带响应请求。
{% endhint %}

### 示例 4：跟踪带有各值描述的枚举

**场景：** 一个企业入职模拟包含一个服务器机房终端，其 `ETerminalState` `UPROPERTY` 会在以下状态间循环： `离线`, `待机`，以及 `活动`。引导者应该为每个枚举值含义提供通俗易懂的上下文。

#### 设置

1. 绑定 `TerminalState` 作为一个跟踪属性。
2. 设置 **`说明`** 为 `“服务器终端当前的运行状态。”`.
3. 展开 **状态值描述** （显示在 Details 面板中的 **高级** 下方）并添加三行：

| 值      | 说明                 |
| ------ | ------------------ |
| `“离线”` | `“终端没有供电。”`        |
| `“待机”` | `“终端已通电，但处于空闲状态。”` |
| `“活动”` | `“终端正在处理请求。”`      |

状态值描述会并入对象会话开始时的描述，而运行时变化会发送当前原始枚举值。这样 Convai 既能从 `action_config` 中获得值上下文，也能从动态上下文更新中获得当前状态。

### 示例 5：在会话开始时动态填充环境

**场景：** 一个程序生成的训练设施，其房间布局每次会话都会变化。AI 导师的对象感知必须基于运行时世界查询构建，而不是基于 Details 面板中的固定列表。

#### 设置

重写 `GatherEnvironmentExtras` 在 `UConvaiChatbotComponent`的 Blueprint 子类中 `StartSession()` 在 `/connect` 握手过程中运行，因此这里添加的每个条目都会包含在冻结的 `action_config` 快照中。

```
// Blueprint 伪代码 — 在 UConvaiChatbotComponent 子类上重写事件图
// 事件：收集环境额外内容（OutExtraActions、OutExtraObjects、OutExtraCharacters）

对于 GetAllActorsWithComponent(UConvaiObjectComponent) 中的每个 Actor：
    Entry = Create FConvaiObjectEntry(
        Name        = Actor.ConvaiObjectComponent.ObjectEntry.Name,
        Description = Actor.ConvaiObjectComponent.ObjectEntry.Description,
        Ref         = Actor
    )
    OutExtraObjects.Add(Entry)
```

`OutExtraObjects` 会与已配置的 `EnvironmentData.Objects` 列表合并，然后 `action_config` 会被发送。名称相同的条目会在合并后的环境中替换更早的条目。

### 示例 6：为固定背景道具禁用移动感知

**场景：** 一个博物馆导览模拟使用一幅大型彩绘壁画，它横跨每个展厅的整面后墙。壁画在对话中很有上下文价值，但它从不移动，因此没有必要每个轮询周期都花费一次采样其变换。

#### 设置

添加一个 `UConvaiObjectComponent` 为壁画添加 `Actor` 并设置：

* **`名称`**: `“HistoryMural”`
* **`说明`**: `“一幅大型彩绘壁画，描绘该机构的历史，横跨每个展厅的整面后墙。”`
* **启用移动感知** (`bEnableMovementAwareness`，在 `MovementAwareness`下：已禁用。

导览员仍然会通过空间感知接收到壁画的身份及其位置和可达性——见 [空间感知](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness.md) ——但插件不再在每次轮询时采样壁画的变换，也不会为它生成移动相关措辞。对于任何从不移动的大型固定道具，都可以使用此模式。

### 下一步

{% 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 %}

{% content-ref url="/pages/5b34043c604b8f8fd8088c66f01ea7887fcd8846" %}
[场景元数据组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-component-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/a6fd7e3b5ee94be300d9c248743b197b93cc0c96" %}
[场景元数据的工作原理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/how-scene-metadata-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/4a8ee50a93a78b9b86484cb79897f6d0d6bde187" %}
[运行时管理环境](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/managing-the-environment-at-runtime.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/scene-metadata-usage-examples.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.