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

# 场景元数据使用示例

下面的示例涵盖了用于训练模拟和交互式体验的真实设置。每个示例都描述了场景、所需的 Details 面板或 Blueprint 配置，以及预期的运行时结果。请从与你当前复杂度级别相匹配的示例开始。

### 示例 1：医学训练模拟 — 解剖实验室

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

#### 设置

此示例无需 Blueprint 脚本。向 `UConvaiObjectComponent` 添加到每个解剖模型和设备 `Actor` 在关卡中。在 **Details** 面板中，将 `名称` 是位于 `说明` 字段设置到 `ObjectEntry`:

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

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

{% hint style="success" %}
一名学员会问： `“有哪些模型可供学习？”` 一个有用的回复可以引用 `HeartModel` 是位于 `LiverModel` 来自场景元数据的描述。
{% endhint %}

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

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

#### 设置

使用 `ClearObjects` 是位于 `AddObject` 在每个阶段加载时对 chatbot 组件调用。传入 `bFlushImmediately = true` 作为最后一次调用，以将所有待处理更新合并为一条消息。

```cpp
// C++ — 切换到新的演练阶段时，在 chatbot 组件上调用
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** （立即刷新： `false`）然后接一个或多个 **Add Object** 节点，并将 **Flush Immediately** 设置为 `true` 最后一个节点上的值。

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

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

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

#### 设置

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

1. 展开 **Tracked Properties** 并点击 **+**.
2. 单击 **Bind** 旁边的 **Property Path** 并选择 `bIsOpen` 来自门的 `Actor`.
3. 设置 **`说明`** 到 `“安保门当前是否打开。”`.
4. 设置 **`ShouldRespond`** 到 `始终`.

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

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

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

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

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

#### 设置

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

| 值           | 说明               |
| ----------- | ---------------- |
| `“Offline”` | `“终端没有电源。”`      |
| `“Standby”` | `“终端有电但处于空闲状态。”` |
| `“Active”`  | `“终端正在处理请求。”`    |

状态值描述会合并进对象的会话开始描述中，而运行时变化会发送当前原始枚举值。这样 Convai 同时拥有来自 `action_config` 的值上下文以及来自动态上下文更新的当前状态。

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

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

#### 设置

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

```
// Blueprint 伪代码 — 在 UConvaiChatbotComponent 子类上覆盖事件图
// 事件：Gather Environment Extras (OutExtraActions, OutExtraObjects, OutExtraCharacters)

对于 GetAllActorsWithComponent(UConvaiObjectComponent) 中的每个 Actor：
    条目 = 创建 FConvaiObjectEntry(
        名称        = Actor.ConvaiObjectComponent.ObjectEntry.Name,
        描述      = Actor.ConvaiObjectComponent.ObjectEntry.Description,
        引用         = Actor
    )
    OutExtraObjects.Add(Entry)
```

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

### 示例 6：为背景道具禁用接近状态

**场景：** 一个博物馆导览模拟使用一幅大型彩绘壁画，横跨每个展厅的整面后墙。这幅壁画对对话具有上下文价值，但为固定背景生成每个 chatbot 的接近值会产生不必要的网络流量。

#### 设置

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

* **`名称`**: `“HistoryMural”`
* **`说明`**: `“描绘机构历史的大型彩绘壁画，覆盖每个展厅的整面后墙。”`
* **Auto Generate Proximity State** (`bAutoGenerateProximityState`）：已禁用。

引导者可以接收壁画的对象描述，但插件不会为其计算或广播接近数据。对于任何与 chatbot 空间关系无关的大型固定道具，都可以使用此模式。

### 下一步

{% 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 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/scene-metadata-usage-examples.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.