> 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

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 proximity state for background props

**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 generating per-chatbot proximity values for a fixed backdrop produces unnecessary network traffic.

#### 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."`
* **Auto Generate Proximity State** (`bAutoGenerateProximityState`): disabled.

The guide can receive the mural's object description, but the plugin does not compute or broadcast proximity data for it. Use this pattern for any large fixed prop whose spatial relationship to the chatbot is not meaningful.

### 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.