> 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-quick-start.md).

# Scene metadata quick start

Attach a `UConvaiObjectComponent` to a world `Actor`, give it a name and description, and test whether a Convai character can use that object as scene context during conversation.

### Prerequisites

* The Convai Unreal Engine plugin installed and the API key configured.
* A `UConvaiChatbotComponent` and a `UConvaiPlayerComponent` in the level, with a valid Character ID and a working microphone. See [Add your first Convai character](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/getting-started/add-your-first-convai-character.md) if you have not completed that setup.

### Expose an actor and verify recognition

{% stepper %}
{% step %}

#### Select the target actor

Open your level and click the `Actor` you want Convai characters to know about, such as a door, crate, or lever.
{% endstep %}

{% step %}

#### Add the object component

In the **Details** panel, click **Add Component** and search for `UConvaiObjectComponent` or `Convai Object`. Select the component to add it to the `Actor`.
{% endstep %}

{% step %}

#### Set the object name and description

With the **Convai Object Component** selected, set the object identity fields in the **Details** panel:

* **`Name`** — a short, unique label, for example `FrontDoor`.
* **`Description`** — a plain sentence about the object, for example `A large wooden door at the main entrance.`

Names must be unique in the level. See [Scene metadata component reference](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-component-reference.md) for details on duplicate handling and the full field list.
{% endstep %}

{% step %}

#### Enter Play mode and ask the character

Press **Play**. Walk up to the Convai character and ask: `"What do you know about the door?"` or `"Describe the objects near you."` The character should mention the name and description you set.

If the character does not reference the object, open the **Output Log** and filter by `ConvaiSubsystemLog` for registration warnings or `ConvaiObjectComponentLog` for component warnings. See [Troubleshoot scene metadata](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/troubleshoot-scene-metadata.md) for a full list of symptoms.
{% endstep %}

{% step %}

#### Add a tracked property (optional)

To give the character awareness of live game state, expand **Tracked Properties** in the Details panel and click **+** to add a row. Click **Bind** next to **Property Path** and select a `UPROPERTY` from the `Actor`. Set a plain-language **`Description`** and choose a **`ShouldRespond`** value.

For the full tracked property workflow, see [Scene metadata component reference — Tracked properties](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-component-reference.md#tracked-properties).
{% endstep %}
{% endstepper %}

{% hint style="success" %}
When configured correctly, the character responds to questions about the object using the name and description you set.
{% endhint %}

{% hint style="info" %}
For the full list of properties and functions available on the component, see [Scene metadata component reference](/api-docs/plugins-and-integrations/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-component-reference.md).
{% endhint %}

### Next steps

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

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


---

# 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-quick-start.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.