> 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/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-usage-examples.md).

# Scene metadata usage examples

Complete scene metadata setups for training simulations, industrial drills, military bases, and runtime environment updates in Unreal Engine.

The examples below cover realistic setups for training simulations and interactive experiences. Each example describes the scenario, the required Details panel or Blueprint configuration, and the expected runtime outcome. Start with the example that matches your current complexity level.

### Example 1: Medical training simulation — anatomy lab

**Scenario:** A surgical training simulation where a medical instructor NPC guides trainees through an anatomy lab. The character must recognize and describe physical models and equipment in the room — trainees ask questions such as `"What is this organ?"` or `"Where is the aorta?"`

#### Setup

No Blueprint scripting is required for this example. Add a `UConvaiObjectComponent` to each anatomy model and equipment `Actor` in the level. In the **Details** panel, set the `Name` and `Description` fields on `ObjectEntry`:

| Name              | Description                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| `HeartModel`      | `"Life-size anatomical heart model on the center examination table. Shows all four chambers and major vessels."` |
| `LiverModel`      | `"Adult liver model mounted on the left side of the display rack. Hepatic veins are color-coded."`               |
| `SurgicalScalpel` | `"Standard surgical scalpel resting on the instrument tray. Handle is blue."`                                    |
| `Stethoscope`     | `"Stethoscope hanging on the hook next to the examination table."`                                               |

The instructor character receives all descriptions at session start, so questions about the room can use the actual scene entries as context.

{% hint style="success" %}
A trainee asks: `"What models are available for study?"` A useful response can reference the `HeartModel` and `LiverModel` descriptions from the scene metadata.
{% endhint %}

### Example 2: Industrial safety drill — phase-based object awareness

**Scenario:** A safety training module with multiple drill phases. Each phase introduces different hazards and equipment. Runtime object updates are useful when phase props are introduced after the session has started.

#### Setup

Use `ClearObjects` and `AddObject` on the chatbot component when each phase loads. Pass `bFlushImmediately = true` on the final call to coalesce all pending updates into a single message.

```cpp
// C++ — call on the chatbot component when transitioning to a new drill phase
void ASafetyDrillManager::LoadPhase(int32 PhaseIndex)
{
    // Remove all objects from the previous phase
    ChatbotComponent->ClearObjects(false);

    // Add only the props for the current phase
    const TArray<FConvaiObjectEntry>& PhaseEntries = PhaseProps[PhaseIndex];
    for (int32 i = 0; i < PhaseEntries.Num(); ++i)
    {
        bool bFlush = (i == PhaseEntries.Num() - 1); // flush on last entry
        ChatbotComponent->AddObject(PhaseEntries[i], bFlush);
    }
}
```

In Blueprint, wire **Clear Objects** (Flush Immediately: `false`) followed by one or more **Add Object** nodes, with **Flush Immediately** set to `true` on the last one.

This pattern sends new phase props through the runtime environment update path. If a phase object was already included in `action_config` at `/connect`, reconnect before the phase begins so the next session starts with the correct object set.

### Example 3: Military simulation — forward operating base with live gate state

**Scenario:** A military training simulation where the tactical officer knows the layout of a forward operating base. Security gates have a live access state, and gate changes should be sent to Convai as tracked state.

#### Setup

Add a `UConvaiObjectComponent` to each structure and security gate `Actor`. For static structures, only `Name` and `Description` are needed. For security gates, also add a tracked property:

1. Expand **Tracked Properties** and click **+**.
2. Click **Bind** next to **Property Path** and select `bIsOpen` from the gate `Actor`.
3. Set **`Description`** to `"Whether the security gate is currently open."`.
4. Set **`ShouldRespond`** to `Always`.

| Name          | Description                                                                                                 |
| ------------- | ----------------------------------------------------------------------------------------------------------- |
| `CommandPost` | `"Main command post at grid reference Alpha-7. Houses mission briefing room and communications equipment."` |
| `Armoury`     | `"Armory building on the eastern perimeter. Access is restricted to authorized personnel."`                 |
| `NorthGate`   | `"Northern security gate. Controls vehicle and personnel access to the forward operating base."`            |

When the `bIsOpen` property changes on the `NorthGate` `Actor` at runtime, the plugin detects the change on the tracked-property poll and schedules a dynamic context update with `ShouldRespond` set to `Always`.

{% hint style="success" %}
The player opens the north gate. The next tracked-property update sends the new `bIsOpen` value with a response request.
{% endhint %}

### Example 4: Tracking an enum with per-value descriptions

**Scenario:** A corporate onboarding simulation has a server room terminal with an `ETerminalState` `UPROPERTY` that cycles through `Offline`, `Standby`, and `Active`. The guide should have plain-language context for what each enum value means.

#### Setup

1. Bind `TerminalState` as a tracked property.
2. Set **`Description`** to `"The current operating state of the server terminal."`.
3. Expand **State Value Descriptions** (shown under **Advanced** in the Details panel) and add three rows:

| Value       | Description                          |
| ----------- | ------------------------------------ |
| `"Offline"` | `"Terminal has no power."`           |
| `"Standby"` | `"Terminal is powered but idle."`    |
| `"Active"`  | `"Terminal is processing requests."` |

The state-value descriptions are folded into the object's session-start description, while runtime changes send the current raw enum value. This gives Convai both the value context from `action_config` and the current state from dynamic context updates.

### Example 5: Dynamically populating the environment at session start

**Scenario:** A procedurally generated training facility where the room layout changes each session. The AI instructor's object awareness must be built from a runtime world query rather than from a fixed list in the Details panel.

#### Setup

Override `GatherEnvironmentExtras` in a Blueprint subclass of `UConvaiChatbotComponent`. This event runs once inside `StartSession()` before the `/connect` handshake, so every entry added here is included in the frozen `action_config` snapshot.

```
// Blueprint pseudocode — event graph override on a UConvaiChatbotComponent subclass
// Event: Gather Environment Extras (OutExtraActions, OutExtraObjects, OutExtraCharacters)

For each Actor in GetAllActorsWithComponent(UConvaiObjectComponent):
    Entry = Create FConvaiObjectEntry(
        Name        = Actor.ConvaiObjectComponent.ObjectEntry.Name,
        Description = Actor.ConvaiObjectComponent.ObjectEntry.Description,
        Ref         = Actor
    )
    OutExtraObjects.Add(Entry)
```

`OutExtraObjects` is merged with the configured `EnvironmentData.Objects` list before `action_config` is sent. Entries with the same name replace earlier entries in the merged environment.

### Example 6: Disabling movement awareness for a fixed background prop

**Scenario:** A museum guide simulation uses a large painted mural that spans the back wall of every gallery room. The mural is contextually useful for conversation, but it never moves, so there is no reason to spend a poll each cycle sampling its transform.

#### Setup

Add a `UConvaiObjectComponent` to the mural `Actor` and set:

* **`Name`**: `"HistoryMural"`
* **`Description`**: `"A large painted mural depicting the history of the institution, spanning the full back wall of each gallery."`
* **Enable Movement Awareness** (`bEnableMovementAwareness`, under `MovementAwareness`): disabled.

The guide still receives the mural's identity and its position and reachability through spatial awareness — see [Spatial awareness](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/spatial-awareness.md) — but the plugin no longer samples the mural's transform each poll or produces movement wording for it. Use this pattern for any large fixed prop that never moves.

### Next steps

{% content-ref url="/pages/vDCzfp22bc2x6dppbHkD" %}
[Troubleshoot scene metadata](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/troubleshoot-scene-metadata.md)
{% endcontent-ref %}

{% content-ref url="/pages/D7AS0tddjNnZ6oTWwtlC" %}
[Scene metadata component reference](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-component-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/ct7GZc4pJVR5cE2Nx02x" %}
[How scene metadata works](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/how-scene-metadata-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/0IWX9Z34917gjSpzDUY8" %}
[Managing the environment at runtime](/api-docs/plugins-and-integrations/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/plugins-and-integrations/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.