> 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-unity-sdk/features/scene-metadata/quick-start.md).

# Scene metadata quick start

Set up Scene Metadata to give a Convai character awareness of named objects in your scene. By the end, your character knows what objects exist and can reference them in conversation — entirely from the Inspector.

### Prerequisites

Before starting, verify:

* [ ] A `ConvaiCharacter` is in the scene and responds to speech in Play Mode

{% stepper %}
{% step %}

#### Add ConvaiObjectMetadata to a scene object

Select any GameObject in your scene that the AI character should know about — a piece of equipment, a fire extinguisher, a door, an exhibit. In the Inspector, click **Add Component** and search for `Convai Object Metadata`.

The **Object Name** field auto-fills from the GameObject's name. Edit it to a clear, human-readable label if the GameObject name is not descriptive — for example, change `Prop_FireExt_01` to `Fire Extinguisher`.

Optionally fill in **Object Description** with one to two factual sentences: what the object is, where it is located, and any key attributes. Keep it under 200 characters.

{% hint style="warning" %}
**Object Name** is required. Leave it empty and the object is excluded from the payload — `Is Registered` shows `true`, but the object does not reach Convai.
{% endhint %}
{% endstep %}

{% step %}

#### Add ConvaiObjectMetadata to remaining objects

Add `ConvaiObjectMetadata` to each additional object the AI should know about. You do not need to add it to every GameObject — only to objects relevant to AI conversations.

Each component registers itself with `ConvaiMetadataRegistry` automatically when enabled. No manual wiring or registration calls are needed.
{% endstep %}

{% step %}

#### Add ConvaiSceneMetadataCollector and enable auto-collection

On any GameObject in your scene, click **Add Component** and search for `Convai Scene Metadata Collector`. Placing it on the same GameObject as `ConvaiManager` is a useful organizational convention.

In the Inspector, enable **Collect On Start**. This tells the collector to send the full metadata payload automatically when the room session connects.

Leave **Log Statistics** enabled — it writes a Console entry on each collection showing the object count and duration, which confirms everything is working.

`ConvaiSceneMetadataCollector` resolves its dependencies automatically at startup by finding `ConvaiManager` in the scene — no manual wiring required.
{% endstep %}

{% step %}

#### Enter Play Mode and verify

Press Play. When the room connects, the collector fires automatically. Check the Console for a debug entry similar to:

```
[ConvaiSceneMetadataCollector] Collected 4 metadata objects in 0.0010s. Registry stats: 4 total, 4 valid, 0 invalid
```

This confirms the payload was assembled and sent to Convai. Test the character by asking a question that requires scene awareness — for example: "What equipment is available on this floor?" or "Can you describe what's near the exit?"
{% endstep %}
{% endstepper %}

{% hint style="success" %}
The character responds with information that reflects the names and descriptions you entered. Scene Metadata is working.
{% endhint %}

### Next steps

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

{% content-ref url="/pages/66fddc4b0f911e97d589403a45f3ae569eb83b5d" %}
[Troubleshoot scene metadata](/api-docs/plugins-and-integrations/convai-unity-sdk/features/scene-metadata/troubleshooting-and-diagnostics.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/plugins-and-integrations/convai-unity-sdk/features/scene-metadata/quick-start.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.